Class

CALayer

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

Declaration

@interface CALayer : NSObject

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.

Topics

Creating a Layer

layer

Creates and returns an instance of the layer object.

init

Returns an initialized CALayer object.

initWithLayer:

Override to copy or initialize custom fields of the specified layer.

layerWithRemoteClientId:

Initializes a layer with a remote client ID.

Accessing Related Layer Objects

presentationLayer

Returns a copy of the presentation layer object that represents the state of the layer as it currently appears onscreen.

modelLayer

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.

drawInContext:

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.

hidden

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.

doubleSided

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.

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

opaque

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.

geometryFlipped

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.

renderInContext:

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:atIndex:

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.

setNeedsDisplayInRect:

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.

needsDisplayForKey:

Returns a Boolean indicating whether changes to the specified key require the layer to be redisplayed.

Layer Animations

addAnimation:forKey:

Add the specified animation object to the layer’s render tree.

animationForKey:

Returns the animation object with the specified identifier.

removeAllAnimations

Remove all animations attached to the layer.

removeAnimationForKey:

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.

resizeWithOldSuperlayerSize:

Informs the receiver that the size of its superlayer changed.

resizeSublayersWithOldSize:

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

actionForKey:

Returns the action object assigned to the specified key.

actions

A dictionary containing layer actions.

defaultActionForKey:

Returns the default action for the current class.

Mapping Between Coordinate and Time Spaces

convertPoint:fromLayer:

Converts the point from the specified layer’s coordinate system to the receiver’s coordinate system.

convertPoint:toLayer:

Converts the point from the receiver’s coordinate system to the specified layer’s coordinate system.

convertRect:fromLayer:

Converts the rectangle from the specified layer’s coordinate system to the receiver’s coordinate system.

convertRect:toLayer:

Converts the rectangle from the receiver’s coordinate system to the specified layer’s coordinate system.

convertTime:fromLayer:

Converts the time interval from the specified layer’s time space to the receiver’s time space.

convertTime:toLayer:

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.

containsPoint:

Returns whether the receiver contains a specified point.

Scrolling

visibleRect

The visible region of the layer in its own coordinate space.

scrollPoint:

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

shouldArchiveValueForKey:

Returns a Boolean indicating whether the value of the specified key should be archived.

defaultValueForKey:

Specifies the default value associated with the specified key.

Constants

CAAutoresizingMask

These constants are used by the autoresizingMask property.

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.

Relationships

Inherits From

See Also

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 objects to respond to actions triggered by a CALayer change.