Core Animation

Core Animation Reference

Search these docs to answer questions about Core Animation (the QuartzCore framework). Use this skill when working directly with CALayer, layer-backed UIKit/AppKit views, explicit keyframe or spring animations on layer properties, particle systems, or per-frame callbacks via CADisplayLink.

For SwiftUI's declarative animation API (withAnimation, Animation, .animation(_:value:), transitions), use guide-swiftui-animations instead. For SwiftUI immediate-mode drawing, use swiftui/canvas.md and swiftui/graphicscontext.md.

Return Format

Always include: 1. Summary — answer the question concisely. 2. File paths — list relevant files for full details, e.g.:

• calayer.md for layer geometry, contents, hierarchy
• cabasicanimation.md for animating a single property between two values
• catransaction.md for batching, disabling implicit animations, or changing default duration

Files

When to Reach for Core Animation

• You need to animate a layer property SwiftUI/UIKit doesn't expose declaratively (e.g., CAGradientLayer.colors, CAShapeLayer.strokeEnd, CAEmitterLayer.birthRate).
• You need explicit keyframe or spring control with timing functions (CAMediaTimingFunction) per segment.
• You want to batch implicit animations off (CATransaction.setDisableActions(true)).
• You need a CADisplayLink per-frame callback (custom drawing loops, scrubbing, physics).
• You're rendering thousands of particles with CAEmitterLayer or replicating sublayers with CAReplicatorLayer.

If your problem fits inside withAnimation { ... } in SwiftUI or UIView.animate { ... } in UIKit, prefer those — Core Animation sits underneath both and is rarely the right starting point in 2026-era code.

Fetching More Docs

1. Search this skill's local .md files first. 2. If the topic is not here, check the other installed Apple skills, then grep their local files. 3. If no installed skill has the page, the QuartzCore path on Apple's site is /documentation/quartzcore/<symbol> — fetch via the sosumi.ai Markdown mirror (e.g. https://sosumi.ai/documentation/quartzcore/camediatimingfunction) or by running pnpm fetch-doc against the apple-skills tooling.

Navigation: Quartzcore

Class

CAAnimation

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

The abstract superclass for animations in Core Animation.

class CAAnimation

Overview

CAAnimation provides the basic support for the CAMediaTiming and CAAction protocols. You do not create instance of CAAnimation: to animate Core Animation layers or SceneKit objects, create instances of the concrete subclasses CABasicAnimation, CAKeyframeAnimation, CAAnimationGroup, or CATransition.

Animating Core Animation Layers

You can animate the contents of your iOS or macOS app’s user interface by attaching animations to CALayer objects. For more information, see Core Animation Programming Guide.

Animating Scene Kit Content

In Scene Kit, animation objects represent not only property-based animations, but also animations of geometry data created with external 3D authoring tools and loaded from a scene file. You use the properties of the CAAnimation object representing a geometry animation to control its timing, monitor its progress, and attach actions for Scene Kit to trigger during the animation. You can attach animations to Scene Kit objects that adopt the SCNAnimatable protocol, including nodes, geometries, and materials.

In a Scene Kit app, CAAnimation objects support additional methods and properties, listed under Controlling SceneKit Animation Timing, Fading between SceneKit Animations, and Attaching SceneKit Animation Events.

Inherits From

• NSObject

Inherited By

• CAAnimationGroup
• CAPropertyAnimation
• CATransition

Conforms To

• CAAction
• CAMediaTiming
• CVarArg
• Copyable
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Escapable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• NSSecureCoding
• SCNAnimationProtocol

Creating an Animation

• init(SCNAnimation:)) Creates an animation from a SceneKit animation.

Animation Attributes

• isRemovedOnCompletion Determines if the animation is removed from the target layer’s animations upon completion.
• timingFunction An optional timing function defining the pacing of the animation.

Providing Default Values

• defaultValue(forKey:)) Specifies the default value of the property with the specified key.

Designating a Delegate

• delegate Specifies the receiver’s delegate object.

Archiving Properties

• shouldArchiveValue(forKey:)) Specifies whether the value of the property for a given key is archived.

Controlling SceneKit Animation Timing

• usesSceneTimeBase For animations attached to SceneKit objects, a Boolean value that determines whether the animation is evaluated using the scene time or the system time.

Fading between SceneKit Animations

• fadeInDuration For animations attached to SceneKit objects, the duration for transitioning into the animation’s effect as it begins.
• fadeOutDuration For animations attached to SceneKit objects, the duration for transitioning out of the animation’s effect as it ends.

Attaching SceneKit Animation Events

• animationEvents For animations attached to SceneKit objects, a list of events attached to an animation.

Initializers

• init(SCNAnimation:)) Creates an animation from a SceneKit animation.
• init(coder:))

Instance Properties

• preferredFrameRateRange

Animation

• CAAnimationDelegate Methods your app can implement to respond when animations start and stop.
• CAPropertyAnimation An abstract subclass for creating animations that manipulate the value of layer properties.
• CABasicAnimation An object that provides basic, single-keyframe animation capabilities for a layer property.
• CAKeyframeAnimation An object that provides keyframe animation capabilities for a layer object.
• CASpringAnimation An animation that applies a spring-like force to a layer’s properties.
• CATransition An object that provides an animated transition between a layer’s states.
• CAValueFunction An object that provides a flexible method of defining animated transformations.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAAnimationGroup

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

An object that allows multiple animations to be grouped and run concurrently.

class CAAnimationGroup

Overview

The grouped animations run in the time space specified by the CAAnimationGroup instance.

The duration of the grouped animations are not scaled to the duration of their CAAnimationGroup. Instead, the animations are clipped to the duration of the animation group. For example, a 10 second animation grouped within an animation group with a duration of 5 seconds displays only the first 5 seconds of the animation.

The following code shows how you can create a grouped animation containing opacity and scale animations to fade out a layer while expanding it. The animation starts with an opacity of 1 and a scale of 1 on all axes. As the animation’s scale increases to (3, 3, 3), the opacity drops to 0 and the animated layer vanishes.

let fadeOut = CABasicAnimation(keyPath: "opacity")
fadeOut.fromValue = 1
fadeOut.toValue = 0
fadeOut.duration = 1
     
let expandScale = CABasicAnimation()
expandScale.keyPath = "transform"
expandScale.valueFunction = CAValueFunction(name: kCAValueFunctionScale)
expandScale.fromValue = [1, 1, 1]
expandScale.toValue = [3, 3, 3]
     
let fadeAndScale = CAAnimationGroup()
fadeAndScale.animations = [fadeOut, expandScale]
fadeAndScale.duration = 1

Important: The delegate and isRemovedOnCompletion properties of animations in the animations array are currently ignored. The CAAnimationGroup delegate does receive these messages.

Inherits From

• CAAnimation

Conforms To

• CAAction
• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Grouped animations

• animations An array of CAAnimation objects to be evaluated in the time space of the receiver.

Animation Groups

• CATransaction A mechanism for grouping multiple layer-tree operations into atomic updates to the render tree.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CABasicAnimation

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

An object that provides basic, single-keyframe animation capabilities for a layer property.

class CABasicAnimation

Overview

You create an instance of CABasicAnimation using the inherited init(keyPath:)) method, specifying the key path of the property to be animated in the render tree.

For example, you can animate a layer’s scalar (i.e. containing a single value) properties such as its opacity. The following code fades in a layer by animating its opacity from 0 to 1.

let animation = CABasicAnimation(keyPath: "opacity") 
animation.fromValue = 0 
animation.toValue = 1

Non-scalar properties, such as backgroundColor, can also be animated. Core Animation will interpolate between the fromValue color and the toValue color. The animation created in the following code fades a layer’s background color from red to blue.

let animation = CABasicAnimation(keyPath: "backgroundColor")
animation.fromValue = NSColor.red.cgColor
animation.toValue = NSColor.blue.cgColor

If you want to animate the individual components of a non-scalar property with different values, you pass the values to toValue and fromValue as arrays. The following animation moves a layer from (0, 0) to (100, 100).

let animation = CABasicAnimation(keyPath: "position")
animation.fromValue = [0, 0]
animation.toValue = [100, 100]

The keyPath can access the individual components of a property. For example, the following animation stretches a layer by animating its transform object’s x from 1 to 2.

let animation = CABasicAnimation(keyPath: "transform.scale.x")
animation.fromValue = 1
animation.toValue = 2

Setting Interpolation Values

The fromValue, byValue and toValue properties define the values being interpolated between. All are optional, and no more than two should be non-nil. The object type should match the type of the property being animated.

The interpolation values are used as follows:

• Both fromValue and toValue are non-nil. Interpolates between fromValue and toValue.
• fromValue and byValue are non-nil. Interpolates between fromValue and (fromValue + byValue).
• byValue and toValue are non-nil. Interpolates between (toValue - byValue) and toValue.
• fromValue is non-nil. Interpolates between fromValue and the current presentation value of the property.
• toValue is non-nil. Interpolates between the current value of keyPath in the target layer’s presentation layer and toValue.
• byValue is non-nil. Interpolates between the current value of keyPath in the target layer’s presentation layer and that value plus byValue.
• All properties are nil. Interpolates between the previous value of keyPath in the target layer’s presentation layer and the current value of keyPath in the target layer’s presentation layer.

Inherits From

• CAPropertyAnimation

Inherited By

• CASpringAnimation

Conforms To

• CAAction
• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Interpolation values

• fromValue Defines the value the receiver uses to start interpolation.
• toValue Defines the value the receiver uses to end interpolation.
• byValue Defines the value the receiver uses to perform relative interpolation.

Animation

• CAAnimation The abstract superclass for animations in Core Animation.
• CAAnimationDelegate Methods your app can implement to respond when animations start and stop.
• CAPropertyAnimation An abstract subclass for creating animations that manipulate the value of layer properties.
• CAKeyframeAnimation An object that provides keyframe animation capabilities for a layer object.
• CASpringAnimation An animation that applies a spring-like force to a layer’s properties.
• CATransition An object that provides an animated transition between a layer’s states.
• CAValueFunction An object that provides a flexible method of defining animated transformations.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CADisplayLink

Available on: iOS 3.1+, iPadOS 3.1+, Mac Catalyst 13.1+, macOS 14.0+, tvOS 9.0+, visionOS 1.0+

A timer object that allows your app to synchronize its drawing to the refresh rate of the display.

class CADisplayLink

Overview

Your app initializes a new display link by providing a target object and a selector to call when the system updates the screen. To synchronize your display loop with the display, your application adds it to a run loop using the add(to:forMode:)) method.

Once you associate the display link with a run loop, the system calls the selector on the target when the screen’s contents need to update. The target can read the display link’s timestamp property to retrieve the time the system displayed the previous frame. For example, an app that displays movies might use timestamp to calculate which video frame to display next. An app that performs its own animations might use timestamp to determine where and how visible objects appear in the upcoming frame.

The duration property provides the amount of time between frames at the maximumFramesPerSecond. To calculate the actual frame duration, use targetTimestamp - timestamp. You can use this value in your app to calculate the frame rate of the display, the approximate time the system displays the next frame, and to adjust the drawing behavior so that the next frame is ready in time to display.

Your app can disable notifications by setting isPaused to true. Also, if your app can’t provide frames in the time the system provides, you may want to choose a slower frame rate. An app with a slower but consistent frame rate appears smoother to the user than an app that skips frames. You can define the number of frames per second by setting preferredFramesPerSecond.

When your app finishes with a display link, call invalidate()) to remove it from all run loops and to disassociate it from the target.

The code listing below shows how to create a display link and add it to the current run loop. The display link invokes the step function, which prints the target timestamp with each screen update.

Swift

func createDisplayLink() {
    let displaylink = CADisplayLink(target: self,
                                    selector: #selector(step))
    
    displaylink.add(to: .current,
                    forMode: .defaultRunLoopMode)
}
     
func step(displaylink: CADisplayLink) {
    print(displaylink.targetTimestamp)
}

Objective-C

- (void)createDisplayLink {
    CADisplayLink *displayLink = [CADisplayLink displayLinkWithTarget:self
                                                             selector:@selector(step:)];
    [displayLink addToRunLoop:[NSRunLoop currentRunLoop]
                      forMode:NSRunLoopCommonModes];
}

- (void)step:(CADisplayLink *)sender {
    NSLog(@"%f", sender.targetTimestamp);
}

You shouldn’t subclass CADisplayLink.

Preferred and Actual Frame Rates

You control a display link’s frame rate (the number of times the system calls the selector of its target, per second) by setting preferredFramesPerSecond. However, the actual frames per second may differ from the preferred value you set; actual frame rates are always a factor of the maximum refresh rate of the device. For example, if your device’s maximum refresh rate is 60 frames per second (defined by maximumFramesPerSecond), actual frame rates include 15, 20, 30, and 60 frames per second. If you set a display link’s preferred frame rate to a value higher than the maximum, the actual frame rate is the maximum.

In iOS 15, frame rate availability can change due to the system factoring in the system policy and user preference — including Low Power Mode, critical thermal state, and accessibility settings.

The system rounds, to the nearest factor, preferred frame rates that aren’t a divisor of the maximum frame rate. For example, setting a preferred frame rate to either 26 or 35 frames per second on a device with a maximum refresh rate of 60 frames per second yields an actual frame rate of 30 times per second.

The code listing below shows how to calculate the actual frame rate by dividing 1 by your display link’s timestamp subtracted from its targetTimestamp.

Swift

// Calculate the actual frame rate.
let actualFramesPerSecond = 1 / (displaylink.targetTimestamp - displaylink.timestamp)

Objective-C

// Calculate the actual frame rate.
double actualFramesPerSecond = 1 / (displaylink.targetTimestamp - displaylink.timestamp);

Note: If your app needs more control over refresh rate to ensure smooth rendering of frames, use CAMetalDisplayLink and the information from CAMetalLayer instances to render frames.

Inherits From

• NSObject

Conforms To

• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSObjectProtocol

Creating a Display Link

• init(target:selector:)) Creates a display link for a target that calls its selector.

Configuring a Display Link

• duration The time interval between screen refresh updates.
• preferredFrameRateRange A range of frequencies your app allows for frame updates, affecting how often the system invokes your delegate’s callback.
• preferredFramesPerSecond A frequency your app prefers for frame updates, affecting how often the system invokes your delegate’s callback.
• isPaused A Boolean value that indicates whether the system suspends the display link’s notifications to the target.
• timestamp The time interval that represents when the last frame displayed.
• targetTimestamp The time interval that represents when the next frame displays.
• frameInterval The number of frames that must pass before the display link notifies the target again.

Scheduling a Display Link to Send Notifications

• add(to:forMode:)) Registers the display link with a run loop.
• remove(from:forMode:)) Removes the display link from the run loop for the given mode.
• invalidate()) Removes the display link from all run loop modes.

Related Documentation

• Presenting content on a connected display Fill connected displays with additional content from your app.

Animation Timing

• CACurrentMediaTime()) Returns the current absolute time, in seconds.
• CAMediaTimingFunction A function that defines the pacing of an animation as a timing curve.
• CAMediaTiming Methods that model a hierarchical timing system, allowing objects to map time between their parent and local time.
• CAMetalDisplayLink A class your Metal app uses to register for callbacks to synchronize its animations for a display.
• CAMetalDisplayLink.Update Stores information about a single update from a Metal display link instance.
• CAMetalDisplayLinkDelegate A protocol your app implements to respond to callbacks from Core Animation for a Metal display link.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAEmitterCell

Available on: iOS 5.0+, iPadOS 5.0+, Mac Catalyst 13.1+, macOS 10.6+, tvOS 9.0+, visionOS 1.0+

The definition of a particle emitted by a particle layer.

class CAEmitterCell

Overview

The CAEmitterCell class represents one source of particles being emitted by a CAEmitterLayer object. An emitter cell defines the direction and properties of the emitted particles. Emitter cells can have an array of sub-cells, which lets the particles themselves emit particles.

Inherits From

• NSObject

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding

Providing Emitter Cell Content

• contents An object that provides the contents of the layer. Animatable.
• contentsRect A rectangle (in the unit coordinate space) that specifies the portion of contents that the receiver should draw. Animatable.
• emitterCells An optional array containing the sub-cells of this cell.

Setting Emitter Cell Visual Attributes

• isEnabled A Boolean value indicating whether or not cells from this emitter are rendered.
• color The color of each emitted object. Animatable.
• redRange The amount by which the red color component of the cell can vary. Animatable.
• greenRange The amount by which the green color component of the cell can vary. Animatable.
• blueRange The amount by which the blue color component of the cell can vary. Animatable.
• alphaRange The amount by which the alpha component of the cell can vary. Animatable.
• redSpeed The speed, in seconds, at which the red color component changes over the lifetime of the cell. Animatable.
• greenSpeed The speed, in seconds, at which the green color component changes over the lifetime of the cell. Animatable.
• blueSpeed The speed, in seconds, at which the blue color component changes over the lifetime of the cell. Animatable.
• alphaSpeed The speed, in seconds, at which the alpha component changes over the lifetime of the cell. Animatable.
• magnificationFilter The filter used when increasing the size of the content.
• minificationFilter The filter used when reducing the size of the content.
• minificationFilterBias The bias factor used by the minification filter to determine the levels of detail.
• scale Specifies the scale factor applied to the cell. Animatable.
• scaleRange Specifies the range over which the scale value can vary. Animatable.
• contentsScale The scale factor of the cell contents.
• name The name of the cell.
• style An optional dictionary containing additional style values that are not explicitly defined by the receiver.

Setting Emitter Cell Motion Attributes

• spin The rotational velocity, measured in radians per second, to apply to the cell. Animatable.
• spinRange The amount by which the spin of the cell can vary over its lifetime. Animatable.
• emissionLatitude The latitudinal orientation of the emission angle. Animatable.
• emissionLongitude The longitudinal orientation of the emission angle. Animatable.
• emissionRange The angle, in radians, defining a cone around the emission angle. Animatable.

Setting Emitter Cell Temporal Attributes

• lifetime The lifetime of the cell, in seconds. Animatable.
• lifetimeRange The mean value by which the lifetime of the cell can vary. Animatable.
• birthRate The number of emitted objects created every second. Animatable.
• scaleSpeed The speed at which the scale changes over the lifetime of the cell. Animatable.
• velocity The initial velocity of the cell. Animatable.
• velocityRange The amount by which the velocity of the cell can vary. Animatable.
• xAcceleration The x component of an acceleration vector applied to cell.
• yAcceleration The y component of an acceleration vector applied to cell.
• zAcceleration The z component of an acceleration vector applied to cell.

Using Key-Value Coding Extensions

• defaultValue(forKey:)) Returns the default value of the property with the specified key.
• shouldArchiveValue(forKey:)) Returns a Boolean value indicating whether the value for a given key should be archived.

Initializers

• init(coder:))

Particle Systems

• CAEmitterLayer A layer that emits, animates, and renders a particle system.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAEmitterLayer

Available on: iOS 5.0+, iPadOS 5.0+, Mac Catalyst 13.1+, macOS 10.6+, tvOS 9.0+, visionOS 1.0+

A layer that emits, animates, and renders a particle system.

class CAEmitterLayer

Overview

The particles, defined by instances of CAEmitterCell, are drawn above the layer’s background color and border.

The following code shows how to set up a simple point (the default emitterShape is point) particle emitter. It uses an image named RadialGradient.png as the cell contents and, by setting the emitter cell’s emissionRange to 2 × pi, the particles are emitted in all directions.

let emitterLayer = CAEmitterLayer()
    
emitterLayer.emitterPosition = CGPoint(x: 320, y: 320)
    
let cell = CAEmitterCell()
cell.birthRate = 100
cell.lifetime = 10
cell.velocity = 100
cell.scale = 0.1
    
cell.emissionRange = CGFloat.pi * 2.0
cell.contents = UIImage(named: "RadialGradient.png")!.cgImage
    
emitterLayer.emitterCells = [cell]
    
view.layer.addSublayer(emitterLayer)

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Specifying Particle Emitter Cells

• emitterCells The array emitter cells attached to the layer.

Emitter Geometry

• renderMode Defines how particle cells are rendered into the layer.
• emitterPosition The position of the center of the particle emitter. Animatable.
• emitterShape Specifies the emitter shape.
• emitterZPosition Specifies the center of the particle emitter shape along the z-axis. Animatable.
• emitterDepth Determines the depth of the emitter shape.
• emitterSize Determines the size of the particle emitter shape. Animatable.

Emitter Cell Attribute Multipliers

• scale Defines a multiplier applied to the cell-defined particle scale.
• seed Specifies the seed used to initialize the random number generator.
• spin Defines a multiplier applied to the cell-defined particle spin. Animatable.
• velocity Defines a multiplier applied to the cell-defined particle velocity. Animatable.
• birthRate Defines a multiplier that is applied to the cell-defined birth rate. Animatable
• emitterMode Specifies the emitter mode.
• lifetime Defines a multiplier applied to the cell-defined lifetime range when particles are created. Animatable.
• preservesDepth Defines whether the layer flattens the particles into its plane.

Constants

• Emitter Shape The emission shape is a one, two or three dimensional shape that defines where the emitted particles originate. The shapes are defined by a subset of emitterPosition, emitterZPosition, emitterSize and emitterDepth properties.
• Emitter Modes These constants specify the possible emitter modes. They are used by the emitterMode property.
• Emitter Render Order These constants specify the order that emitter cells are composited. They are used by the renderMode property.

Particle Systems

• CAEmitterCell The definition of a particle emitted by a particle layer.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAGradientLayer

Available on: iOS 3.0+, iPadOS 3.0+, Mac Catalyst 13.1+, macOS 10.6+, tvOS 9.0+, visionOS 1.0+

A layer that draws a color gradient over its background color, filling the shape of the layer.

class CAGradientLayer

Overview

You use a gradient layer to create a color gradient containing an arbitrary number of colors. By default, the colors are spread uniformly across the layer, but you can optionally specify locations for control over the color positions through the gradient.

The following code shows how to create a gradient layer containing four colors that are evenly distributed through the gradient. Rotating the layer by 90° (pi ⁄ 2 radians) gives a horizontal gradient.

gradientLayer.colors = [UIColor.red.cgColor,
                        UIColor.yellow.cgColor,
                        UIColor.green.cgColor,
                        UIColor.blue.cgColor]
     
gradientLayer.transform = CATransform3DMakeRotation(CGFloat.pi / 2, 0, 0, 1)

The following figure shows the appearance of the gradient layer.

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Gradient Style Properties

• colors An array of CGColorRef objects defining the color of each gradient stop. Animatable.
• locations An optional array of NSNumber objects defining the location of each gradient stop. Animatable.
• endPoint The end point of the gradient when drawn in the layer’s coordinate space. Animatable.
• startPoint The start point of the gradient when drawn in the layer’s coordinate space. Animatable.
• type Style of gradient drawn by the layer.

Constants

• Gradient Types The style of gradient drawn by the layer.

Text, Shapes, and Gradients

• CATextLayer A layer that provides simple text layout and rendering of plain or attributed strings.
• CAShapeLayer A layer that draws a cubic Bezier spline in its coordinate space.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAKeyframeAnimation

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

An object that provides keyframe animation capabilities for a layer object.

class CAKeyframeAnimation

Overview

You create a CAKeyframeAnimation object using the inherited init(keyPath:)) method, specifying the key path of the property that you want to animate on the layer. You can then specify the keyframe values to use to control the timing and animation behavior.

For most types of animations, you specify the keyframe values using the values and keyTimes properties. During the animation, Core Animation generates intermediate values by interpolating between the values you provide. When animating a value that is a coordinate point, such as the layer’s position, you can specify a path for that point to follow instead of individual values. The pacing of the animation is controlled by the timing information you provide.

The following code shows how to create a keyframe animation that animates a layer’s background color from red to green to blue over a two second duration.

let colorKeyframeAnimation = CAKeyframeAnimation(keyPath: "backgroundColor")

colorKeyframeAnimation.values = [UIColor.red.cgColor,
                                 UIColor.green.cgColor,
                                 UIColor.blue.cgColor]
colorKeyframeAnimation.keyTimes = [0, 0.5, 1]
colorKeyframeAnimation.duration = 2

Inherits From

• CAPropertyAnimation

Conforms To

• CAAction
• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Providing keyframe values

• values An array of objects that specify the keyframe values to use for the animation.
• path The path for a point-based property to follow.

Keyframe timing

• keyTimes An optional array of NSNumber objects that define the time at which to apply a given keyframe segment.
• timingFunctions An optional array of CAMediaTimingFunction objects that define the pacing for each keyframe segment.
• calculationMode Specifies how intermediate keyframe values are calculated by the receiver.

Rotation Mode Attribute

• rotationMode Determines whether objects animating along the path rotate to match the path tangent.

Cubic Mode Attributes

• tensionValues An array of numbers that define the tightness of the curve.
• continuityValues An array of numbers that define the sharpness of the timing curve’s corners.
• biasValues An array of numbers that define the position of the curve relative to a control point.

Constants

• Rotation Mode Values These constants are used by the rotationMode property.
• Value calculation modes These constants are used by the calculationMode property.

Animation

• CAAnimation The abstract superclass for animations in Core Animation.
• CAAnimationDelegate Methods your app can implement to respond when animations start and stop.
• CAPropertyAnimation An abstract subclass for creating animations that manipulate the value of layer properties.
• CABasicAnimation An object that provides basic, single-keyframe animation capabilities for a layer property.
• CASpringAnimation An animation that applies a spring-like force to a layer’s properties.
• CATransition An object that provides an animated transition between a layer’s states.
• CAValueFunction An object that provides a flexible method of defining animated transformations.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CALayer

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

An object that manages image-based content and allows you to perform animations on that content.

class CALayer

Overview

Layers are often used to provide the backing store for views but can also be used without a view to display content. A layer’s main job is to manage the visual content that you provide but the layer itself has visual attributes that can be set, such as a background color, border, and shadow. In addition to managing visual content, the layer also maintains information about the geometry of its content (such as its position, size, and transform) that is used to present that content onscreen. Modifying the properties of the layer is how you initiate animations on the layer’s content or geometry. A layer object encapsulates the duration and pacing of a layer and its animations by adopting the CAMediaTiming protocol, which defines the layer’s timing information.

If the layer object was created by a view, the view typically assigns itself as the layer’s delegate automatically, and you should not change that relationship. For layers you create yourself, you can assign a delegate object and use that object to provide the contents of the layer dynamically and perform other tasks. A layer may also have a layout manager object (assigned to the layoutManager property) to manage the layout of subviews separately.

Inherits From

• NSObject

Inherited By

• CAEAGLLayer
• CAEmitterLayer
• CAGradientLayer
• CAMetalLayer
• CAOpenGLLayer
• CAReplicatorLayer
• CAScrollLayer
• CAShapeLayer
• CATextLayer
• CATiledLayer
• CATransformLayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding

Creating a layer

• init()) Returns an initialized CALayer object.
• init(layer:)) Override to copy or initialize custom fields of the specified layer.
• init(remoteClientId:)) Initializes a layer with a remote client ID.

Accessing related layer objects

• presentation()) Returns a copy of the presentation layer object that represents the state of the layer as it currently appears onscreen.
• model()) Returns the model layer object associated with the receiver, if any.

Accessing the delegate

• delegate The layer’s delegate object.

Providing the layer’s content

• contents An object that provides the contents of the layer. Animatable.
• contentsRect The rectangle, in the unit coordinate space, that defines the portion of the layer’s contents that should be used. Animatable.
• contentsCenter The rectangle that defines how the layer contents are scaled if the layer’s contents are resized. Animatable.
• display()) Reloads the content of this layer.
• draw(in:)) Draws the layer’s content using the specified graphics context.

Modifying the layer’s appearance

• contentsGravity A constant that specifies how the layer’s contents are positioned or scaled within its bounds.
• Contents Gravity Values The contents gravity constants specify the position of the content object when the layer bounds is larger than the bounds of the content object. They are used by the contentsGravity property.
• opacity The opacity of the receiver. Animatable.
• isHidden A Boolean indicating whether the layer is displayed. Animatable.
• masksToBounds A Boolean indicating whether sublayers are clipped to the layer’s bounds. Animatable.
• mask An optional layer whose alpha channel is used to mask the layer’s content.
• isDoubleSided A Boolean indicating whether the layer displays its content when facing away from the viewer. Animatable.
• cornerRadius The radius to use when drawing rounded corners for the layer’s background. Animatable.
• maskedCorners
• CACornerMask
• borderWidth The width of the layer’s border. Animatable.
• borderColor The color of the layer’s border. Animatable.
• backgroundColor The background color of the receiver. Animatable.
• shadowOpacity The opacity of the layer’s shadow. Animatable.
• shadowRadius The blur radius (in points) used to render the layer’s shadow. Animatable.
• shadowOffset The offset (in points) of the layer’s shadow. Animatable.
• shadowColor The color of the layer’s shadow. Animatable.
• shadowPath The shape of the layer’s shadow. Animatable.
• style An optional dictionary used to store property values that aren’t explicitly defined by the layer.
• allowsEdgeAntialiasing A Boolean indicating whether the layer is allowed to perform edge antialiasing.
• allowsGroupOpacity A Boolean indicating whether the layer is allowed to composite itself as a group separate from its parent.

Layer filters

• filters An array of Core Image filters to apply to the contents of the layer and its sublayers. Animatable.
• compositingFilter A CoreImage filter used to composite the layer and the content behind it. Animatable.
• backgroundFilters An array of Core Image filters to apply to the content immediately behind the layer. Animatable.
• minificationFilter The filter used when reducing the size of the content.
• minificationFilterBias The bias factor used by the minification filter to determine the levels of detail.
• magnificationFilter The filter used when increasing the size of the content.

Configuring the layer’s rendering behavior

• isOpaque A Boolean value indicating whether the layer contains completely opaque content.
• edgeAntialiasingMask A bitmask defining how the edges of the receiver are rasterized.
• contentsAreFlipped()) Returns a Boolean indicating whether the layer content is implicitly flipped when rendered.
• isGeometryFlipped A Boolean that indicates whether the geometry of the layer and its sublayers is flipped vertically.
• drawsAsynchronously A Boolean indicating whether drawing commands are deferred and processed asynchronously in a background thread.
• shouldRasterize A Boolean that indicates whether the layer is rendered as a bitmap before compositing. Animatable
• rasterizationScale The scale at which to rasterize content, relative to the coordinate space of the layer. Animatable
• contentsFormat A hint for the desired storage format of the layer contents.
• render(in:)) Renders the layer and its sublayers into the specified context.

Modifying the layer geometry

• frame The layer’s frame rectangle.
• bounds The layer’s bounds rectangle. Animatable.
• position The layer’s position in its superlayer’s coordinate space. Animatable.
• zPosition The layer’s position on the z axis. Animatable.
• anchorPointZ The anchor point for the layer’s position along the z axis. Animatable.
• anchorPoint Defines the anchor point of the layer’s bounds rectangle. Animatable.
• contentsScale The scale factor applied to the layer.

Managing the layer’s transform

• transform The transform applied to the layer’s contents. Animatable.
• sublayerTransform Specifies the transform to apply to sublayers when rendering. Animatable.
• affineTransform()) Returns an affine version of the layer’s transform.
• setAffineTransform(_:)) Sets the layer’s transform to the specified affine transform.

Managing the layer hierarchy

• sublayers An array containing the layer’s sublayers.
• superlayer The superlayer of the layer.
• addSublayer(_:)) Appends the layer to the layer’s list of sublayers.
• removeFromSuperlayer()) Detaches the layer from its parent layer.
• insertSublayer(_:at:)) Inserts the specified layer into the receiver’s list of sublayers at the specified index.
• insertSublayer(_:below:)) Inserts the specified sublayer below a different sublayer that already belongs to the receiver.
• insertSublayer(_:above:)) Inserts the specified sublayer above a different sublayer that already belongs to the receiver.
• replaceSublayer(_:with:)) Replaces the specified sublayer with a different layer object.

Updating layer display

• setNeedsDisplay()) Marks the layer’s contents as needing to be updated.
• setNeedsDisplay(_:)) Marks the region within the specified rectangle as needing to be updated.
• needsDisplayOnBoundsChange A Boolean indicating whether the layer contents must be updated when its bounds rectangle changes.
• displayIfNeeded()) Initiates the update process for a layer if it is currently marked as needing an update.
• needsDisplay()) Returns a Boolean indicating whether the layer has been marked as needing an update.
• needsDisplay(forKey:)) Returns a Boolean indicating whether changes to the specified key require the layer to be redisplayed.

Layer animations

• add(_:forKey:)) Add the specified animation object to the layer’s render tree.
• animation(forKey:)) Returns the animation object with the specified identifier.
• removeAllAnimations()) Remove all animations attached to the layer.
• removeAnimation(forKey:)) Remove the animation object with the specified key.
• animationKeys()) Returns an array of strings that identify the animations currently attached to the layer.

Managing layer resizing and layout

• layoutManager The object responsible for laying out the layer’s sublayers.
• setNeedsLayout()) Invalidates the layer’s layout and marks it as needing an update.
• layoutSublayers()) Tells the layer to update its layout.
• layoutIfNeeded()) Recalculate the receiver’s layout, if required.
• needsLayout()) Returns a Boolean indicating whether the layer has been marked as needing a layout update.
• autoresizingMask A bitmask defining how the layer is resized when the bounds of its superlayer changes.
• resize(withOldSuperlayerSize:)) Informs the receiver that the size of its superlayer changed.
• resizeSublayers(withOldSize:)) Informs the receiver’s sublayers that the receiver’s size has changed.
• preferredFrameSize()) Returns the preferred size of the layer in the coordinate space of its superlayer.

Managing layer constraints

• constraints The constraints used to position current layer’s sublayers.
• addConstraint(_:)) Adds the specified constraint to the layer.

Getting the layer’s actions

• action(forKey:)) Returns the action object assigned to the specified key.
• actions A dictionary containing layer actions.
• defaultAction(forKey:)) Returns the default action for the current class.

Mapping between coordinate and time spaces

• convert(_:from:)-8kl76) Converts the point from the specified layer’s coordinate system to the receiver’s coordinate system.
• convert(_:to:)-7dcke) Converts the point from the receiver’s coordinate system to the specified layer’s coordinate system.
• convert(_:from:)-4kx9l) Converts the rectangle from the specified layer’s coordinate system to the receiver’s coordinate system.
• convert(_:to:)-tly5) Converts the rectangle from the receiver’s coordinate system to the specified layer’s coordinate system.
• convertTime(_:from:)) Converts the time interval from the specified layer’s time space to the receiver’s time space.
• convertTime(_:to:)) Converts the time interval from the receiver’s time space to the specified layer’s time space

Hit testing

• hitTest(_:)) Returns the farthest descendant of the receiver in the layer hierarchy (including itself) that contains the specified point.
• contains(_:)) Returns whether the receiver contains a specified point.

Scrolling

• visibleRect The visible region of the layer in its own coordinate space.
• scroll(_:)) Initiates a scroll in the layer’s closest ancestor scroll layer so that the specified point lies at the origin of the scroll layer.
• scrollRectToVisible(_:)) Initiates a scroll in the layer’s closest ancestor scroll layer so that the specified rectangle becomes visible.

Identifying the layer

• name The name of the receiver.

Key-value coding extensions

• shouldArchiveValue(forKey:)) Returns a Boolean indicating whether the value of the specified key should be archived.
• defaultValue(forKey:)) Specifies the default value associated with the specified key.

High dynamic range

• preferredDynamicRange
• contentsHeadroom
• wantsExtendedDynamicRangeContent

Constants

• CAAutoresizingMask These constants are used by the autoresizingMask property.
• Action Identifiers These constants are the predefined action identifiers used by action(forKey:)), add(_:forKey:)), defaultAction(forKey:)), removeAnimation(forKey:)), Layer Filters, and the CAAction protocol method run(forKey:object:arguments:)).
• CAEdgeAntialiasingMask This mask is used by the edgeAntialiasingMask property.
• Identity Transform Defines the identity transform matrix used by Core Animation.
• Scaling Filters These constants specify the scaling filters used by magnificationFilter and minificationFilter.
• CATransform3D The standard transform matrix used throughout Core Animation.
• CALayer.DynamicRange

Instance properties

• cornerCurve
• wantsDynamicContentScaling

Type methods

• cornerCurveExpansionFactor(_:))

Initializers

• init(coder:))

Instance Properties

• toneMapMode

Layer Basics

• CALayerDelegate Methods your app can implement to respond to layer-related events.
• CAConstraint A representation of a single layout constraint between two layers.
• CALayoutManager Methods that allow an object to manage the layout of a layer and its sublayers.
• CAConstraintLayoutManager An object that provides a constraint-based layout manager.
• CAAction An interface that allows instances to respond to actions triggered by a Core Animation layer change.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Protocol

CAMediaTiming

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

Methods that model a hierarchical timing system, allowing objects to map time between their parent and local time.

protocol CAMediaTiming

Overview

Absolute time is defined as mach time converted to seconds. The CACurrentMediaTime()) function is provided as a convenience for getting the current absolute time.

The conversion from parent time to local time has two stages:

1. Conversion to “active local time.” This includes the point at which the object appears in the parent object’s timeline and how fast it plays relative to the parent. 2. Conversion from “active local time” to “basic local time.” The timing model allows for objects to repeat their basic duration multiple times and, optionally, to play backwards before repeating.

Conforming Types

• CAAnimation
• CAAnimationGroup
• CABasicAnimation
• CAEAGLLayer
• CAEmitterCell
• CAEmitterLayer
• CAGradientLayer
• CAKeyframeAnimation
• CALayer
• CAMetalLayer
• CAOpenGLLayer
• CAPropertyAnimation
• CAReplicatorLayer
• CAScrollLayer
• CAShapeLayer
• CASpringAnimation
• CATextLayer
• CATiledLayer
• CATransformLayer
• CATransition

Animation Start Time

• beginTime Specifies the begin time of the receiver in relation to its parent object, if applicable.
• timeOffset Specifies an additional time offset in active local time.

Repeating Animations

• repeatCount Determines the number of times the animation will repeat.
• repeatDuration Determines how many seconds the animation will repeat for.

Duration and Speed

• duration Specifies the basic duration of the animation, in seconds.
• speed Specifies how time is mapped to receiver’s time space from the parent time space.

Playback Modes

• autoreverses Determines if the receiver plays in the reverse upon completion.
• fillMode Determines if the receiver’s presentation is frozen or removed once its active duration has completed.

Constants

• Fill Modes These constants determine how the timed object behaves once its active duration has completed. They are used with the fillMode property.

Animation Timing

• CACurrentMediaTime()) Returns the current absolute time, in seconds.
• CAMediaTimingFunction A function that defines the pacing of an animation as a timing curve.
• CADisplayLink A timer object that allows your app to synchronize its drawing to the refresh rate of the display.
• CAMetalDisplayLink A class your Metal app uses to register for callbacks to synchronize its animations for a display.
• CAMetalDisplayLink.Update Stores information about a single update from a Metal display link instance.
• CAMetalDisplayLinkDelegate A protocol your app implements to respond to callbacks from Core Animation for a Metal display link.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAMetalLayer

Available on: iOS 8.0+, iPadOS 8.0+, Mac Catalyst 13.1+, macOS 10.11+, tvOS 9.0+, visionOS 1.0+

A Core Animation layer that Metal can render into, typically displayed onscreen.

class CAMetalLayer

Overview

Use a CAMetalLayer when you want to use Metal to render a layer’s contents; for example, to render into a view. Consider using MTKView instead, because this class automatically wraps a CAMetalLayer object and provides a higher-level abstraction.

If you’re using UIKit, to create a view that uses a CAMetalLayer, create a subclass of UIView and override its layerClass class method to return a CAMetalLayer:

+ (Class) layerClass
{
    return [CAMetalLayer class];
}

If you’re using AppKit, configure an NSView object to use a backing layer and assign a CAMetalLayer object to the view:

myView.wantsLayer = YES;
myView.layer = [CAMetalLayer layer];

Adjust the layer’s properties to configure its underlying pixel format and other display behaviors.

Rendering the Layer’s Contents

A CAMetalLayer creates a pool of Metal drawable objects (CAMetalDrawable). At any given time, one of these drawable objects contains the contents of the layer. To change the layer’s contents, ask the layer for a drawable object, render into it, and then update the layer’s contents to point to the new drawable.

Call the layer’s nextDrawable()) method to obtain a drawable object. Get the drawable object’s texture and create a render pass that renders to that texture, as shown in the code below:

CAMetalLayer *metalLayer = (CAMetalLayer*)self.layer;
id<CAMetalDrawable> *drawable = [metalLayer nextDrawable];

MTLRenderPassDescriptor *renderPassDescriptor
                               = [MTLRenderPassDescriptor renderPassDescriptor];

renderPassDescriptor.colorAttachments[0].texture = drawable.texture;
renderPassDescriptor.colorAttachments[0].loadAction = MTLLoadActionClear;
renderPassDescriptor.colorAttachments[0].clearColor = MTLClearColorMake(0.0,0.0,0.0,1.0);
...

To change the layer’s contents to the new drawable, call the present(_:)) method (or one of its variants) on the command buffer containing the encoded render pass, passing in the drawable object to present.

[commandBuffer presentDrawable:drawable];

Keeping References to Drawables

The layer reuses a drawable only if it isn’t onscreen and there are no strong references to it. Further, if a drawable isn’t available when you call nextDrawable()), the system waits for one to become available. To avoid stalls in your app, request a new drawable only when you need it, and release any references to it as quickly as possible after you’re done with it.

For example, before retrieving a new drawable, you might perform other work on the CPU or submit commands to the GPU that don’t require the drawable. Then, obtain the drawable and encode a command buffer to render into it, as described above. After you commit this command buffer, release all strong references to the drawable. If you don’t release drawables correctly, the layer runs out of drawables, and future calls to nextDrawable()) return nil.

Releasing the Drawable

Don’t release the drawable explicitly; instead, embed your render loop within an autorelease pool block:

Swift

func draw(in view: MTKView) {
    autoreleasepool {
        render(view: view)
    }
}

Objective-C

- (void)drawInMTKView:(MTKView *)view {
    @autoreleasepool {
        [self render:view];
    }
}

This block releases drawables promptly and avoids possible deadlock situations with multiple drawables. Release drawables as soon as possible after committing your onscreen render pass.

Note: As of iOS 10 and tvOS 10, you can safely retain a drawable to query its properties, such as drawableID and presentedTime, after the system has presented it. If you don’t need to query these properties, release the drawable when you no longer need it.

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Configuring the Metal Device

• device The Metal device responsible for the layer’s drawable resources.
• preferredDevice The device object that the system recommends using for this layer.

Configuring the Layer’s Drawable Objects

• pixelFormat The pixel format of the layer’s textures.
• colorspace The color space of the rendered content.
• framebufferOnly A Boolean value that determines whether the layer’s textures are used only for rendering.
• drawableSize The size, in pixels, of textures for rendering layer content.

Configuring Presentation Behavior

• presentsWithTransaction A Boolean value that determines whether the layer presents its content using a Core Animation transaction.
• displaySyncEnabled A Boolean value that determines whether the layer synchronizes its updates to the display’s refresh rate.

Configuring Extended Dynamic Range Behavior

• wantsExtendedDynamicRangeContent Enables extended dynamic range values onscreen.
• edrMetadata Metadata describing the tone mapping to apply to the extended dynamic range (EDR) values in the layer.

Obtaining a Metal Drawable

• nextDrawable()) Waits until a Metal drawable is available, and then returns it.
• maximumDrawableCount The number of Metal drawables in the resource pool managed by Core Animation.
• allowsNextDrawableTimeout A Boolean value that determines whether requests for a new buffer expire if the system can’t satisfy them.

Configuring the Metal Performance HUD

• developerHUDProperties The properties of the Metal performance heads-up display.

Instance Properties

• residencySet

Metal and OpenGL

• CAMetalDrawable A Metal drawable associated with a Core Animation layer.
• CAEAGLLayer A layer that supports drawing OpenGL content in iOS and tvOS applications.
• CAEDRMetadata Metadata describing how extended dynamic range (EDR) values should be tone mapped.
• CAOpenGLLayer A layer that provides a layer suitable for rendering OpenGL content.
• CARenderer A layer that allows an application to render a layer tree into a Core OpenGL context.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAPropertyAnimation

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

An abstract subclass for creating animations that manipulate the value of layer properties.

class CAPropertyAnimation

Overview

The property to animate is specified using a key path that is relative to the layer using the animation.

You do not create instances of CAPropertyAnimation: to animate the properties of a Core Animation layer, create instance of the concrete subclasses CABasicAnimation or CAKeyframeAnimation.

Inherits From

• CAAnimation

Inherited By

• CABasicAnimation
• CAKeyframeAnimation

Conforms To

• CAAction
• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Animated Key Path

• keyPath Specifies the key path the receiver animates.

Property Value Calculation Behavior

• isCumulative Determines if the value of the property is the value at the end of the previous repeat cycle, plus the value of the current repeat cycle.
• isAdditive Determines if the value specified by the animation is added to the current render tree value to produce the new render tree value.
• valueFunction An optional value function that is applied to interpolated values.

Creating an Animation

• init(keyPath:)) Creates and returns an CAPropertyAnimation instance for the specified key path.

Animation

• CAAnimation The abstract superclass for animations in Core Animation.
• CAAnimationDelegate Methods your app can implement to respond when animations start and stop.
• CABasicAnimation An object that provides basic, single-keyframe animation capabilities for a layer property.
• CAKeyframeAnimation An object that provides keyframe animation capabilities for a layer object.
• CASpringAnimation An animation that applies a spring-like force to a layer’s properties.
• CATransition An object that provides an animated transition between a layer’s states.
• CAValueFunction An object that provides a flexible method of defining animated transformations.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAReplicatorLayer

Available on: iOS 3.0+, iPadOS 3.0+, Mac Catalyst 13.1+, macOS 10.6+, tvOS 9.0+, visionOS 1.0+

A layer that creates a specified number of sublayer copies with varying geometric, temporal, and color transformations.

class CAReplicatorLayer

Overview

You can use a CAReplicatorLayer object to build complex layouts based on a single source layer that is replicated with transformation rules that can affect the position, rotation color, and time.

The following shows a simple example: a red square is added to a replicator layer with an instance count of 5. The position of each replicated instance is offset along the x axis so that it appears to the right of the previous instance. The blue and green color channels are offset so that their values reach 0 at the final instance.

let replicatorLayer = CAReplicatorLayer()
     
let redSquare = CALayer()
redSquare.backgroundColor = NSColor.white.cgColor
redSquare.frame = CGRect(x: 0, y: 0, width: 100, height: 100)
     
let instanceCount = 5
     
replicatorLayer.instanceCount = instanceCount
replicatorLayer.instanceTransform = CATransform3DMakeTranslation(110, 0, 0)
     
let offsetStep = -1 / Float(instanceCount)
replicatorLayer.instanceBlueOffset = offsetStep
replicatorLayer.instanceGreenOffset = offsetStep
    
replicatorLayer.addSublayer(redSquare)

The result of the code above is a row of five squares, with colors graduating from white to red.

Replicator layers can be nested. The following code adds replicatorLayer to a second replicator layer that offsets the position of each instance vertically and subtracts from the red channel.

let outerReplicatorLayer = CAReplicatorLayer()

outerReplicatorLayer.addSublayer(replicatorLayer)

outerReplicatorLayer.instanceCount = instanceCount
outerReplicatorLayer.instanceTransform = CATransform3DMakeTranslation(0, 110, 0)
outerReplicatorLayer.instanceRedOffset = offsetStep

The result of adding this code is to create a grid with the value of the red channel being reduced in the vertical direction.

Note: The CAReplicatorLayer implementation of hitTest(_:)) currently tests only the first instance of z replicator layer’s sublayers. This may change in the future.

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Setting Instance Display Properties

• instanceCount The number of copies to create, including the source layers.
• instanceDelay Specifies the delay, in seconds, between replicated copies. Animatable.
• instanceTransform The transform matrix applied to the previous instance to produce the current instance. Animatable.

Modifying Instance Layer Geometry

• preservesDepth Defines whether this layer flattens its sublayers into its plane.

Accessing Instance Color Values

• instanceColor Defines the color used to multiply the source object. Animatable.
• instanceRedOffset Defines the offset added to the red component of the color for each replicated instance. Animatable.
• instanceGreenOffset Defines the offset added to the green component of the color for each replicated instance. Animatable.
• instanceBlueOffset Defines the offset added to the blue component of the color for each replicated instance. Animatable.
• instanceAlphaOffset Defines the offset added to the alpha component of the color for each replicated instance. Animatable.

Advanced Layer Options

• CAScrollLayer A layer that displays scrollable content larger than its own bounds.
• CATiledLayer A layer that provides a way to asynchronously provide tiles of the layer’s content, potentially cached at multiple levels of detail.
• CATransformLayer Objects used to create true 3D layer hierarchies, rather than the flattened hierarchy rendering model used by other layer types.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CAShapeLayer

Available on: iOS 3.0+, iPadOS 3.0+, Mac Catalyst 13.1+, macOS 10.6+, tvOS 9.0+, visionOS 1.0+

A layer that draws a cubic Bezier spline in its coordinate space.

class CAShapeLayer

Overview

The shape is composited between the layer’s contents and its first sublayer.

The shape will be drawn antialiased, and whenever possible it will be mapped into screen space before being rasterized to preserve resolution independence. However, certain kinds of image processing operations, such as CoreImage filters, applied to the layer or its ancestors may force rasterization in a local coordinate space.

The following code shows how you can build complex, composite paths and display them using a shape layer. In this example, a series of progressively transformed ellipses form a simple flower shape. The shape layer that displays the path has its fillRule set to evenOdd which stops the overlapping “petals” from filling with the yellow fillColor.

let width: CGFloat = 640
let height: CGFloat = 640
     
let shapeLayer = CAShapeLayer()
shapeLayer.frame = CGRect(x: 0, y: 0,
                          width: width, height: height)
     
let path = CGMutablePath()
     
stride(from: 0, to: CGFloat.pi * 2, by: CGFloat.pi / 6).forEach {
    angle in 
    var transform  = CGAffineTransform(rotationAngle: angle)
        .concatenating(CGAffineTransform(translationX: width / 2, y: height / 2))
    
    let petal = CGPath(ellipseIn: CGRect(x: -20, y: 0, width: 40, height: 100),
                       transform: &transform)
    
    path.addPath(petal)
}
    
shapeLayer.path = path
shapeLayer.strokeColor = UIColor.red.cgColor
shapeLayer.fillColor = UIColor.yellow.cgColor
shapeLayer.fillRule = kCAFillRuleEvenOdd

The following figure shows the resulting shape layer.

Note: Shape rasterization may favor speed over accuracy. For example, pixels with multiple intersecting path segments may not give exact results.

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Specifying the Shape Path

• path The path defining the shape to be rendered. Animatable.

Accessing Shape Style Properties

• fillColor The color used to fill the shape’s path. Animatable.
• fillRule The fill rule used when filling the shape’s path.
• lineCap Specifies the line cap style for the shape’s path.
• lineDashPattern The dash pattern applied to the shape’s path when stroked.
• lineDashPhase The dash phase applied to the shape’s path when stroked. Animatable.
• lineJoin Specifies the line join style for the shape’s path.
• lineWidth Specifies the line width of the shape’s path. Animatable.
• miterLimit The miter limit used when stroking the shape’s path. Animatable.
• strokeColor The color used to stroke the shape’s path. Animatable.
• strokeStart The relative location at which to begin stroking the path. Animatable.
• strokeEnd The relative location at which to stop stroking the path. Animatable.

Constants

• Shape Fill Mode Values These constants specify the possible fill modes for fillRule.
• Line Join Values These constants specify the shape of the joints between connected segments of a stroked path.
• Line Cap Values These constants specify the shape of endpoints for an open path when stroked.

Text, Shapes, and Gradients

• CATextLayer A layer that provides simple text layout and rendering of plain or attributed strings.
• CAGradientLayer A layer that draws a color gradient over its background color, filling the shape of the layer.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CASpringAnimation

Available on: iOS 9.0+, iPadOS 9.0+, Mac Catalyst 13.1+, macOS 10.11+, tvOS 9.0+, visionOS 1.0+

An animation that applies a spring-like force to a layer’s properties.

class CASpringAnimation

Overview

You would typically use a spring animation to animate a layer’s position so that it appears to be pulled towards a target by a spring. The further the layer is from the target, the greater the acceleration towards it is.

CASpringAnimation allows control over physically based attributes such as the spring’s damping and stiffness.

You can use a spring animation to animation properties of a layer other than its position. The following code shows how to create a spring animation that bounces a layer into view by animating its scale from 0 to 1. Because the spring animation can overshoot its toValue, the animated layer may exceed its frame.

let springAnimation = CASpringAnimation(keyPath: "transform.scale")

springAnimation.fromValue = 0
springAnimation.toValue = 1

Inherits From

• CABasicAnimation

Conforms To

• CAAction
• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSCopying
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Configuring Physical Attributes

• damping Defines how the spring’s motion should be damped due to the forces of friction.
• initialVelocity The initial velocity of the object attached to the spring.
• mass The mass of the object attached to the end of the spring.
• settlingDuration The estimated duration required for the spring system to be considered at rest.
• stiffness The spring stiffness coefficient.

Initializers

• init(perceptualDuration:bounce:))

Instance Properties

• allowsOverdamping
• bounce
• perceptualDuration

Animation

• CAAnimation The abstract superclass for animations in Core Animation.
• CAAnimationDelegate Methods your app can implement to respond when animations start and stop.
• CAPropertyAnimation An abstract subclass for creating animations that manipulate the value of layer properties.
• CABasicAnimation An object that provides basic, single-keyframe animation capabilities for a layer property.
• CAKeyframeAnimation An object that provides keyframe animation capabilities for a layer object.
• CATransition An object that provides an animated transition between a layer’s states.
• CAValueFunction An object that provides a flexible method of defining animated transformations.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CATextLayer

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

A layer that provides simple text layout and rendering of plain or attributed strings.

class CATextLayer

Overview

The first line is aligned to the top of the layer.

Note: CATextLayer disables sub-pixel antialiasing when rendering text. Text can only be drawn using sub-pixel antialiasing when it is composited into an existing opaque background at the same time that it’s rasterized. There is no way to draw text with sub-pixel antialiasing by itself, whether into an image or a layer, in advance of having the background pixels to weave the text pixels into. Setting the opacity property of the layer to true does not change the rendering mode.

Note: In macOS, when a CATextLayer instance is positioned using the CAConstraintLayoutManager class the bounds of the layer is resized to fit the text content.

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Getting and Setting the Text

• string The text to be rendered by the receiver.

Text Visual Properties

• font The font used to render the receiver’s text.
• fontSize The font size used to render the receiver’s text. Animatable.
• foregroundColor The color used to render the receiver’s text. Animatable.
• allowsFontSubpixelQuantization Determines whether to allow subpixel quantization for the graphics context used for text rendering.

Text Alignment and Truncation

• isWrapped Determines whether the text is wrapped to fit within the receiver’s bounds.
• alignmentMode Determines how individual lines of text are horizontally aligned within the receiver’s bounds.
• truncationMode Determines how the text is truncated to fit within the receiver’s bounds.

Constants

• Truncation modes These constants are used by the truncationMode property.
• Horizontal alignment modes These constants are used by the alignmentMode property.

Text, Shapes, and Gradients

• CAShapeLayer A layer that draws a cubic Bezier spline in its coordinate space.
• CAGradientLayer A layer that draws a color gradient over its background color, filling the shape of the layer.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CATiledLayer

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

A layer that provides a way to asynchronously provide tiles of the layer’s content, potentially cached at multiple levels of detail.

class CATiledLayer

Overview

As more data is required by the renderer, the layer’s draw(in:)) method is called on one or more background threads to supply the drawing operations to fill in one tile of data. The clip bounds and current transformation matrix (CTM) of the drawing context can be used to determine the bounds and resolution of the tile being requested.

Regions of the layer may be invalidated using the setNeedsDisplay(_:)) method however the update will be asynchronous. While the next display update will most likely not contain the updated content, a future update will.

Important: Do not attempt to directly modify the contents property of a CATiledLayer object. Doing so disables the ability of a tiled layer to asynchronously provide tiled content, effectively turning the layer into a regular CALayer object.

Inherits From

• CALayer

Conforms To

• CAMediaTiming
• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSCoding
• NSObjectProtocol
• NSSecureCoding
• Sendable
• SendableMetatype

Visual Fade

• fadeDuration()) The time, in seconds, that newly added images take to “fade-in” to the rendered representation of the tiled layer.

Levels of detail

• levelsOfDetail The number of levels of detail maintained by this layer.
• levelsOfDetailBias The number of magnified levels of detail for this layer.

Layer tile size

• tileSize The maximum size of each tile used to create the layer’s content.

Advanced Layer Options

• CAScrollLayer A layer that displays scrollable content larger than its own bounds.
• CATransformLayer Objects used to create true 3D layer hierarchies, rather than the flattened hierarchy rendering model used by other layer types.
• CAReplicatorLayer A layer that creates a specified number of sublayer copies with varying geometric, temporal, and color transformations.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: Quartzcore

Class

CATransaction

Available on: iOS 2.0+, iPadOS 2.0+, Mac Catalyst 13.1+, macOS 10.5+, tvOS 9.0+, visionOS 1.0+

A mechanism for grouping multiple layer-tree operations into atomic updates to the render tree.

class CATransaction

Overview

CATransaction is the Core Animation mechanism for batching multiple layer-tree operations into atomic updates to the render tree. Every modification to a layer tree must be part of a transaction. Nested transactions are supported.

Core Animation supports two types of transactions: implicit transactions and explicit transactions. Implicit transactions are created automatically when the layer tree is modified by a thread without an active transaction and are committed automatically when the thread’s runloop next iterates. Explicit transactions occur when the the application sends the CATransaction class a begin()) message before modifying the layer tree, and a commit()) message afterwards.

CATransaction allows you to override default animation properties that are set for animatable properties. You can customize duration, timing function, whether changes to properties trigger animations, and provide a handler that informs you when all animations from the transaction group are completed.

During a transaction you can temporarily acquire a recursive spin lock for managing property atomicity.

CATransaction supports nested transactions. The following code shows how you can fade out a layer (named transitioningLayer) over a 2 second duration while scaling it to three times its original size. The scale animation is within a nested transaction with its own duration of 1 second. After the outer transaction completes, a completion block removes transitioningLayer from its parent layer.

let transitioningLayer = CALayer()
     
// Outer transaction animates `opacity` to 0 over 2 seconds
CATransaction.begin()
CATransaction.setAnimationDuration(2)
CATransaction.setCompletionBlock {
    transitioningLayer.removeFromSuperlayer()
}
    
transitioningLayer.opacity = 0
     
// Inner transaction animates scale to (3, 3, 3) over 1 second
CATransaction.begin()
CATransaction.setAnimationDuration(1)
     
transitioningLayer.transform = CATransform3DMakeScale(3, 3, 3)
     
CATransaction.commit() // Commits inner transaction
CATransaction.commit() // Commits outer transaction

Inherits From

• NSObject

Conforms To

• CVarArg
• CustomDebugStringConvertible
• CustomStringConvertible
• Equatable
• Hashable
• NSObjectProtocol

Creating and Committing Transactions

• begin()) Begin a new transaction for the current thread.
• commit()) Commit all changes made during the current transaction.
• flush()) Flushes any extant implicit transaction.

Overriding Animation Duration and Timing

• animationDuration()) Returns the animation duration used by all animations within this transaction group.
• setAnimationDuration(_:)) Sets the animation duration used by all animations within this transaction group.
• animationTimingFunction()) Returns the timing function used for all animations within this transaction group.
• setAnimationTimingFunction(_:)) Sets the timing function used for all animations within this transaction group.

Temporarily Disabling Property Animations

• disableActions()) Returns whether actions triggered as a result of property changes made within this transaction group are suppressed.
• setDisableActions(_:)) Sets whether actions triggered as a result of property changes made within this transaction group are suppressed.

Getting and Setting Completion Block Objects

• completionBlock()) Returns the completion block object.
• setCompletionBlock(_:)) Sets the completion block object.

Managing Concurrency

• lock()) Attempts to acquire a recursive spin-lock lock, ensuring that returned layer values are valid until unlocked.
• unlock()) Relinquishes a previously acquired transaction lock.

Getting and Setting Transaction Properties

• setValue(_:forKey:)) Sets the arbitrary keyed-data for the specified key.
• value(forKey:)) Returns the arbitrary keyed-data specified by the given key.

Constants

• Transaction properties These constants define the property keys used by value(forKey:)) and setValue(_:forKey:)).

Animation Groups

• CAAnimationGroup An object that allows multiple animations to be grouped and run concurrently.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.