CALayer

CALayer Class Reference

Inherits from	NSObject
Conforms to	NSCoding CAMediaTiming NSObject (NSObject)
Framework	/System/Library/Frameworks/QuartzCore.framework
Availability	Available in iOS 2.0 and later.
Declared in	CALayer.h CAScrollLayer.h CATransform3D.h
Companion guides	Core Animation Programming Guide Core Animation Cookbook
Related sample code	AVSimpleEditoriOS CoreTextPageViewer MotionGraphs MTAudioProcessingTap Audio Processor oalTouch

Overview

The CALayer class manages image-based content and allows you to perform animations on that content. 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.

Tasks

Creating a Layer

• + layer
• – init
• – initWithLayer:

Accessing Related Layer Objects

• – presentationLayer
• – modelLayer

Accessing the Delegate

•    delegate  property

Providing the Layer’s Content

•    contents  property
•    contentsRect  property
•    contentsCenter  property
• – display
• – drawInContext:

Modifying the Layer’s Appearance

•    contentsGravity  property
•    opacity  property
•    hidden  property
•    masksToBounds  property
•    mask  property
•    doubleSided  property
•    cornerRadius  property
•    borderWidth  property
•    borderColor  property
•    backgroundColor  property
•    shadowOpacity  property
•    shadowRadius  property
•    shadowOffset  property
•    shadowColor  property
•    shadowPath  property
•    style  property

Accessing the Layer’s Filters

•    filters  property
•    compositingFilter  property
•    backgroundFilters  property
•    minificationFilter  property
•    minificationFilterBias  property
•    magnificationFilter  property

Configuring the Layer’s Rendering Behavior

•    opaque  property
•    edgeAntialiasingMask  property
• – contentsAreFlipped
•    geometryFlipped  property
•    drawsAsynchronously  property
•    shouldRasterize  property
•    rasterizationScale  property
• – renderInContext:

Modifying the Layer Geometry

•    frame  property
•    bounds  property
•    position  property
•    zPosition  property
•    anchorPointZ  property
•    anchorPoint  property
•    contentsScale  property

Managing the Layer’s Transform

•    transform  property
•    sublayerTransform  property
• – affineTransform
• – setAffineTransform:

Managing the Layer Hierarchy

•    sublayers  property
•    superlayer  property
• – addSublayer:
• – removeFromSuperlayer
• – insertSublayer:atIndex:
• – insertSublayer:below:
• – insertSublayer:above:
• – replaceSublayer:with:

Updating Layer Display

• – setNeedsDisplay
• – setNeedsDisplayInRect:
•    needsDisplayOnBoundsChange  property
• – displayIfNeeded
• – needsDisplay
• + needsDisplayForKey:

Layer Animations

• – addAnimation:forKey:
• – animationForKey:
• – removeAllAnimations
• – removeAnimationForKey:
• – animationKeys

Managing Layer Resizing and Layout

• – setNeedsLayout
• – layoutSublayers
• – layoutIfNeeded
• – needsLayout
• – preferredFrameSize

Getting the Layer’s Actions

• – actionForKey:
•    actions  property
• + defaultActionForKey:

Mapping Between Coordinate and Time Spaces

• – convertPoint:fromLayer:
• – convertPoint:toLayer:
• – convertRect:fromLayer:
• – convertRect:toLayer:
• – convertTime:fromLayer:
• – convertTime:toLayer:

Hit Testing

• – hitTest:
• – containsPoint:

Scrolling

•    visibleRect  property
• – scrollPoint:
• – scrollRectToVisible:

Identifying the Layer

•    name  property

Key-Value Coding Extensions

• – shouldArchiveValueForKey:
• + defaultValueForKey:

Properties

actions

A dictionary containing layer actions.

@property(copy) NSDictionary *actions

Discussion

The default value of this property is nil. You can use this dictionary to store custom actions for your layer. The contents of this dictionary searched as part of the standard implementation of the actionForKey: method.

Availability

• Available in iOS 2.0 and later.

See Also

• – actionForKey:

Declared In

CALayer.h

anchorPoint

Defines the anchor point of the layer's bounds rectangle. Animatable.

@property CGPoint anchorPoint

Discussion

You specify the value for this property using the unit coordinate space. The default value of this property is (0.5, 0.5), which represents the center of the layer’s bounds rectangle. All geometric manipulations to the view occur about the specified point. For example, applying a rotation transform to a layer with the default anchor point causes the layer to rotate around its center. Changing the anchor point to a different location would cause the layer to rotate around that new point.

For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property position

Related Sample Code

• Handling Touches Using Responder Methods and Gesture Recognizers
• MTAudioProcessingTap Audio Processor
• oalTouch

Declared In

CALayer.h

anchorPointZ

The anchor point for the layer’s position along the z axis. Animatable.

@property CGFloat anchorPointZ

Discussion

This property specifies the anchor point on the z axis around which geometric manipulations occur. The point is expressed as a distance (measured in points) along the z axis. The default value of this property is 0.

Availability

• Available in iOS 3.0 and later.

See Also

•   @property anchorPoint

Declared In

CALayer.h

backgroundColor

The background color of the receiver. Animatable.

@property CGColorRef backgroundColor

Discussion

The default value of this property is nil.

The value of this property is retained using the Core Foundation retain/release semantics. This behavior occurs despite the fact that the property declaration appears to use the default assign semantics for object retention.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AVLoupe
• CoreTextPageViewer
• StitchedStreamPlayer

Declared In

CALayer.h

backgroundFilters

An array of Core Image filters to apply to the content immediately behind the layer. Animatable.

@property(copy) NSArray *backgroundFilters

Discussion

Background filters affect the content behind the layer that shows through into the layer itself. Typically this content belongs to the superlayer that acts as the parent of the layer. These filters do not affect the content of the layer itself, including the layer’s background color and border. They also do not affect content outside of the layer’s bounds.

The default value of this property is nil.

Changing the inputs of the CIFilter object directly after it is attached to the layer causes undefined behavior. In OS X, it is possible to modify filter parameters after attaching them to the layer but you must use the layer’s setValue:forKeyPath: method to do so. In addition, you must assign a name to the filter so that you can identify it in the array. For example, to change the inputScale parameter of the filter, you could use code similar to the following:

CIFilter *filter = ...;

CALayer *layer = ...;

filter.name = @"myFilter";

layer.backgroundFilters = [NSArray arrayWithObject:filter];

[layer setValue:[NSNumber numberWithInt:1] forKeyPath:@"backgroundFilters.myFilter.inputScale"];

Special Considerations

This property is not supported on layers in iOS.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

borderColor

The color of the layer’s border. Animatable.

@property CGColorRef borderColor

Discussion

The default value of this property is an opaque black color.

The value of this property is retained using the Core Foundation retain/release semantics. This behavior occurs despite the fact that the property declaration appears to use the default assign semantics for object retention.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

borderWidth

The width of the layer’s border. Animatable.

@property CGFloat borderWidth

Discussion

When this value is greater than 0.0, the layer draws a border using the current borderColor value. The border is drawn inset from the receiver’s bounds by the value specified in this property. It is composited above the receiver’s contents and sublayers and includes the effects of the cornerRadius property.

The default value of this property is 0.0.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

bounds

The layer’s bounds rectangle. Animatable.

@property CGRect bounds

Discussion

The bounds rectangle is the origin and size of the layer in its own coordinate space. When you create a new standalone layer, the default value for this property is an empty rectangle, which you must change before using the layer. The values of each coordinate in the rectangle are measured in points.

For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AVLoupe
• AVSimpleEditoriOS
• CoreTextPageViewer
• MotionGraphs
• MTAudioProcessingTap Audio Processor

Declared In

CALayer.h

compositingFilter

A CoreImage filter used to composite the layer and the content behind it. Animatable.

@property(retain) id compositingFilter

Discussion

The default value of this property is nil, which causes the layer to use source-over compositing.

In OS X, it is possible to modify the filter’s parameters after attaching it to the layer but you must use the layer’s setValue:forKeyPath: method to do so. For example, to change the inputScale parameter of the filter, you could use code similar to the following:

CIFilter *filter = ...;

CALayer *layer = ...;

layer.compositingFilter = filter;

[layer setValue:[NSNumber numberWithInt:1] forKeyPath:@"compositingFilter.inputScale"];

Changing the inputs of the CIFilter object directly after it is attached to the layer causes undefined behavior.

Special Considerations

This property is not supported on layers in iOS.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property backgroundFilters

Declared In

CALayer.h

contents

An object that provides the contents of the layer. Animatable.

@property(retain) id contents

Discussion

The default value of this property is nil.

If you are using the layer to display a static image, you can set this property to the CGImageRef containing the image you want to display. (In OS X 10.6 and later, you can also set the property to an NSImage object.) Assigning a value to this property causes the layer to use your image rather than create a separate backing store.

If the layer object is tied to a view object, you should avoid setting the contents of this property directly. The interplay between views and layers usually results in the view replacing the contents of this property during a subsequent update.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property contentsRect

Related Sample Code

• MTAudioProcessingTap Audio Processor
• oalTouch

Declared In

CALayer.h

contentsCenter

The rectangle that defines how the layer contents are scaled during a resizing operation. Animatable.

@property CGRect contentsCenter

Discussion

You can use this property to subdivide the layer’s content into a 3x3 grid. The value in this property specifies the location and size of the center rectangle in that grid. If the layer’s contentsGravity property is set to one of the resizing modes, resizing the layer causes scaling to occur differently in each rectangle of the grid. The center rectangle is stretched in both dimensions, the top-center and bottom-center rectangles are stretched only horizontally, the left-center and right-center rectangles are stretched only vertically, and the four corner rectangles are not stretched at all. Therefore, you can use this technique to implement stretchable backgrounds or images using a three-part or nine-part image.

The value in this property is set to the unit rectangle (0.0,0.0) (1.0,1.0) by default, which causes the entire image to scale in both dimensions. If you specify a rectangle that extends outside the unit rectangle, the result is undefined. The rectangle you specify is applied only after the contentsRect property has been applied to the image.

Note: If the width or height of the rectangle in this property is very small or 0, the value is implicitly changed to the width or height of a single source pixel centered at the specified location.

Availability

• Available in iOS 3.0 and later.

See Also

•   @property contentsRect
•   @property contentsGravity
•   @property contents

Declared In

CALayer.h

contentsGravity

A constant that specifies how the layer's contents are positioned or scaled within its bounds.

@property(copy) NSString *contentsGravity

Discussion

The possible values for this property are listed in “Contents Gravity Values”. The default value of this property is kCAGravityResize.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

contentsRect

The rectangle, in the unit coordinate space, that defines the portion of the layer’s contents that should be used. Animatable.

@property CGRect contentsRect

Discussion

Defaults to the unit rectangle (0.0, 0.0, 1.0, 1.0).

If pixels outside the unit rectangle are requested, the edge pixels of the contents image will be extended outwards.

If an empty rectangle is provided, the results are undefined.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property contents

Declared In

CALayer.h

contentsScale

The scale factor applied to the layer.

@property CGFloat contentsScale

Discussion

This value defines the mapping between the logical coordinate space of the layer (measured in points) and the physical coordinate space (measured in pixels). Higher scale factors indicate that each point in the layer is represented by more than one pixel at render time. For example, if the scale factor is 2.0 and the layer’s bounds are 50 x 50 points, the size of the bitmap used to present the layer’s content is 100 x 100 pixels.

The default value of this property is 1.0. For layers attached to a view, the view changes the scale factor automatically to a value that is appropriate for the current screen. For layers you create and manage yourself, you must set the value of this property yourself based on the resolution of the screen and the content you are providing. Core Animation uses the value you specify as a cue to determine how to render your content.

Availability

• Available in iOS 4.0 and later.

Related Sample Code

• CoreTextPageViewer

Declared In

CALayer.h

cornerRadius

The radius to use when drawing rounded corners for the layer’s background. Animatable.

@property CGFloat cornerRadius

Discussion

Setting the radius to a value greater than 0.0 causes the layer to begin drawing rounded corners on its background. By default, the corner radius does not apply to the image in the layer’s contents property; it applies only to the background color and border of the layer. However, setting the masksToBounds property to YES causes the content to be clipped to the rounded corners.

The default value of this property is 0.0.

Availability

• Available in iOS 3.0 and later.

Related Sample Code

• GeocoderDemo

Declared In

CALayer.h

delegate

The layer’s delegate object.

@property(assign) id delegate

Discussion

You can use a delegate object to provide the layer’s contents, handle the layout of any sublayers, and provide custom actions in response to layer-related changes. The object you assign to this property should implement one or more of the methods of the CALayerDelegate informal protocol. For more information about that protocol, see CALayerDelegate Informal Protocol Reference

In iOS, if the layer is associated with a UIView object, this property must be set to the view that owns the layer.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• MotionGraphs

Declared In

CALayer.h

doubleSided

A Boolean indicating whether the layer displays its content when facing away from the viewer. Animatable.

@property(getter=isDoubleSided) BOOL doubleSided

Discussion

When the value in this property is NO, the layer hides its content when it faces away from the viewer. The default value of this property is YES.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

drawsAsynchronously

A Boolean indicating whether drawing commands are deferred and processed asynchronously in a background thread.

@property BOOL drawsAsynchronously

Discussion

When this property is set to YES, the graphics context used to draw the layer’s contents queues drawing commands and executes them on a background thread rather than executing them synchronously. Performing these commands asynchronously can improve performance in some apps. However, you should always measure the actual performance benefits before enabling this capability.

The default value for this property is NO.

Availability

• Available in iOS 6.0 and later.

Declared In

CALayer.h

edgeAntialiasingMask

A bitmask defining how the edges of the receiver are rasterized.

@property unsigned int edgeAntialiasingMask

Discussion

This property specifies which edges of the layer are antialiased and is a combination of the constants defined in “Edge Antialiasing Mask.” You can enable or disable antialiasing for each edge (top, left, bottom, right) separately. By default antialiasing is enabled for all edges.

Typically, you would use this property to disable antialiasing for edges that abut edges of other layers, to eliminate the seams that would otherwise occur.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

filters

An array of Core Image filters to apply to the contents of the layer and its sublayers. Animatable.

@property(copy) NSArray *filters

Discussion

The filters you add to this property affect the content of the layer, including its border, filled background and sublayers. The default value of this property is nil.

Changing the inputs of the CIFilter object directly after it is attached to the layer causes undefined behavior. It is possible to modify filter parameters after attaching them to the layer but you must use the layer’s setValue:forKeyPath: method to do so. In addition, you must assign a name to the filter so that you can identify it in the array. For example, to change the inputScale parameter of the filter, you could use code similar to the following:

CIFilter *filter = ...;

CALayer *layer = ...;

filter.name = @"myFilter";

layer.filters = [NSArray arrayWithObject:filter];

[layer setValue:[NSNumber numberWithInt:1] forKeyPath:@"filters.myFilter.inputScale"];

Special Considerations

This property is not supported on layers in iOS.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

frame

The layer’s frame rectangle.

@property CGRect frame

Discussion

The frame rectangle is position and size of the layer specified in the superlayer’s coordinate space. For layers, the frame rectangle is a computed property that is derived from the values in thebounds, anchorPoint and position properties. When you assign a new value to this property, the layer changes its position and bounds properties to match the rectangle you specified. The values of each coordinate in the rectangle are measured in points.

For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.

Note: The frame property is not directly animatable. Instead you should animate the appropriate combination of the bounds, anchorPoint and position properties to achieve the desired result.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AccelerometerGraph
• AVLoupe
• AVSimpleEditoriOS
• MotionGraphs
• oalTouch

Declared In

CALayer.h

geometryFlipped

A Boolean that indicates whether the geometry of the layer and its sublayers is flipped vertically.

@property(getter=isGeometryFlipped) BOOL geometryFlipped

Discussion

If the layer is providing the backing for a layer-backed view, the view is responsible for managing the value in this property. For standalone layers, this property controls whether geometry values for the layer are interpreted using the standard or flipped coordinate system. THe value of this property does not affect the rendering of the layer’s content.

The default value of this property is NO.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

hidden

A Boolean indicating whether the layer is displayed. Animatable.

@property(getter=isHidden) BOOL hidden

Discussion

The default value of this property is NO.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• oalTouch
• StitchedStreamPlayer

Declared In

CALayer.h

magnificationFilter

The filter used when increasing the size of the content.

@property(copy) NSString *magnificationFilter

Discussion

The possible values for this property are listed in “Scaling Filters”.

The default value of this property is kCAFilterLinear.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

mask

An optional layer whose alpha channel is used to mask the layer’s content.

@property(retain) CALayer *mask

Discussion

The layer’s alpha channel determines how much of the layer’s content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

The default value of this property is nil nil. When configuring a mask, remember to set the size and position of the mask layer to ensure it is aligned properly with the layer it masks.

Special Considerations

The layer you assign to this property must not have a superlayer. If it does, the behavior is undefined.

Availability

• Available in iOS 3.0 and later.

See Also

•   @property masksToBounds

Related Sample Code

• AVLoupe

Declared In

CALayer.h

masksToBounds

A Boolean indicating whether sublayers are clipped to the layer’s bounds. Animatable.

@property BOOL masksToBounds

Discussion

When the value of this property is YES, Core Animation creates an implicit clipping mask that matches the bounds of the layer and includes any corner radius effects. If a value for the mask property is also specified, the two masks are multiplied to get the final mask value.

The default value of this property is NO.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• GeocoderDemo

Declared In

CALayer.h

minificationFilter

The filter used when reducing the size of the content.

@property(copy) NSString *minificationFilter

Discussion

The possible values for this property are listed in “Scaling Filters”.

The default value of this property is kCAFilterLinear.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property minificationFilterBias

Declared In

CALayer.h

minificationFilterBias

The bias factor used by the minification filter to determine the levels of detail.

@property float minificationFilterBias

Discussion

This value is used by the minificationFilter when it is set to kCAFilterTrilinear.

The default value of this property is 0.0.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

name

The name of the receiver.

@property(copy) NSString *name

Discussion

The layer name is used by some layout managers to identify a layer. The default value of this property is nil.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• CoreTextPageViewer

Declared In

CALayer.h

needsDisplayOnBoundsChange

A Boolean indicating whether the layer contents must be updated when its bounds rectangle changes.

@property BOOL needsDisplayOnBoundsChange

Discussion

When this property is set to YES, the layer automatically calls its setNeedsDisplay method whenever its bounds property changes. The default value of this property is NO.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

opacity

The opacity of the receiver. Animatable.

@property float opacity

Discussion

The value of this property must be in the range 0.0 (transparent) to 1.0 (opaque). Values outside that range are clamped to the minimum or maximum. The default value of this property is 1.0.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

opaque

A Boolean value indicating whether the layer contains completely opaque content.

@property(getter=isOpaque) BOOL opaque

Discussion

The default value of this property is NO. If your app draws completely opaque content that fills the layer’s bounds, setting this property to YES lets the system optimize the rendering behavior for the layer. Specifically, when the layer creates the backing store for your drawing commands, Core Animation omits the alpha channel of that backing store. Doing so can improve the performance of compositing operations. If you set the value of this property to YES, you must fill the layer’s bounds with opaque content.

Setting this property affects only the backing store managed by Core Animation. If you assign an image with an alpha channel to the layer’s contents property, that image retains its alpha channel regardless of the value of this property.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• GLAirplay
• GLGravity
• GLPaint
• GLTextureAtlas
• SpeakHere

Declared In

CALayer.h

position

The layer’s position in its superlayer’s coordinate space. Animatable.

@property CGPoint position

Discussion

The value of this property is specified in points and is always specified relative to the value in the anchorPoint property. For new standalone layers, the default position is set to (0.0, 0.0). Changing the frame property also updates the value in this property.

For more information about the relationship between the frame, bounds, anchorPoint and position properties, see Core Animation Programming Guide.

Availability

• Available in iOS 2.0 and later.

See Also

•   @property anchorPoint

Related Sample Code

• AccelerometerGraph
• AVSimpleEditoriOS
• CoreTextPageViewer
• MotionGraphs
• oalTouch

Declared In

CALayer.h

rasterizationScale

The scale at which to rasterize content, relative to the coordinate space of the layer. Animatable

@property CGFloat rasterizationScale

Discussion

When the value in the shouldRasterize property is YES, the layer uses this property to determine whether to scale the rasterized content (and by how much). The default value of this property is 1.0, which indicates that the layer should be rasterized at its current size. Larger values magnify the content and smaller values shrink it.

Availability

• Available in iOS 3.2 and later.

Declared In

CALayer.h

shadowColor

The color of the layer’s shadow. Animatable.

@property CGColorRef shadowColor

Discussion

The default value of this property is an opaque black color.

The value of this property is retained using the Core Foundation retain/release semantics. This behavior occurs despite the fact that the property declaration appears to use the default assign semantics for object retention.

Availability

• Available in iOS 3.2 and later.

Related Sample Code

• MTAudioProcessingTap Audio Processor

Declared In

CALayer.h

shadowOffset

The offset (in points) of the layer’s shadow. Animatable.

@property CGSize shadowOffset

Discussion

The default value of this property is (0.0, -3.0).

Availability

• Available in iOS 3.2 and later.

Related Sample Code

• MTAudioProcessingTap Audio Processor

Declared In

CALayer.h

shadowOpacity

The opacity of the layer’s shadow. Animatable.

@property float shadowOpacity

Discussion

The value in this property must be in the range 0.0 (transparent) to 1.0 (opaque). The default value of this property is 0.0.

Availability

• Available in iOS 3.2 and later.

Related Sample Code

• AVSimpleEditoriOS
• MTAudioProcessingTap Audio Processor

Declared In

CALayer.h

shadowPath

The shape of the layer’s shadow. Animatable.

@property CGPathRef shadowPath

Discussion

The default value of this property is nil, which causes the layer to use a standard shadow shape. If you specify a value for this property, the layer creates its shadow using the specified path instead of the layer’s composited alpha channel. The path you provide defines the outline of the shadow. It is filled using the non-zero winding rule and the current shadow color, opacity, and blur radius.

Unlike most animatable properties, this property (as with all CGPathRef animatable properties) does not support implicit animation. However, the path object may be animated using any of the concrete subclasses of CAPropertyAnimation. Paths will interpolate as a linear blend of the "on-line" points; "off-line" points may be interpolated non-linearly (to preserve continuity of the curve's derivative). If the two paths have a different number of control points or segments, the results are undefined. If the path extends outside the layer bounds it will not automatically be clipped to the layer, only if the normal layer masking rules cause that.

Specifying an explicit path usually improves rendering performance.

The value of this property is retained using the Core Foundation retain/release semantics. This behavior occurs despite the fact that the property declaration appears to use the default assign semantics for object retention.

Availability

• Available in iOS 3.2 and later.

Declared In

CALayer.h

shadowRadius

The blur radius (in points) used to render the layer’s shadow. Animatable.

@property CGFloat shadowRadius

Discussion

You specify the radius The default value of this property is 3.0.

Availability

• Available in iOS 3.2 and later.

Related Sample Code

• MTAudioProcessingTap Audio Processor

Declared In

CALayer.h

shouldRasterize

A Boolean that indicates whether the layer is rendered as a bitmap before compositing. Animatable

@property BOOL shouldRasterize

Discussion

When the value of this property is YES, the layer is rendered as a bitmap in its local coordinate space and then composited to the destination with any other content. Shadow effects and any filters in the filters property are rasterized and included in the bitmap. However, the current opacity of the layer is not rasterized. If the rasterized bitmap requires scaling during compositing, the filters in the minificationFilter and magnificationFilter properties are applied as needed.

When the value of this property is NO, the layer is composited directly into the destination whenever possible. The layer may still be rasterized prior to compositing if certain features of the compositing model (such as the inclusion of filters) require it.

The default value of this property is NO.

Availability

• Available in iOS 3.2 and later.

Related Sample Code

• UnwindSegue

Declared In

CALayer.h

style

An optional dictionary used to store property values that aren't explicitly defined by the layer.

@property(copy) NSDictionary *style

Discussion

This dictionary may in turn have a style key, forming a hierarchy of default values. In the case of hierarchical style dictionaries the shallowest value for a property is used. For example, the value for “style.someValue” takes precedence over “style.style.someValue”.

If the style dictionary does not define a value for an attribute, the receiver’s defaultValueForKey: method is called. The default value of this property is nil.

The style dictionary is not consulted for the following keys: bounds, frame.

Warning: If the style dictionary or any of its ancestors are modified, the values of the layer's properties are undefined until the style property is reset.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

sublayers

An array containing the layer’s sublayers.

@property(copy) NSArray *sublayers

Discussion

The sublayers are listed in back to front order. The default value of this property is nil.

Special Considerations

When setting the sublayers property to an array populated with layer objects, each layer in the array must not already have a superlayer—that is, its superlayer property must currently be nil.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AVCam
• AVSimpleEditoriOS
• CoreTextPageViewer

Declared In

CALayer.h

sublayerTransform

Specifies the transform to apply to sublayers when rendering. Animatable.

@property CATransform3D sublayerTransform

Discussion

You typically use this property to add perspective and other viewing effects to embedded layers. You add perspective by setting the sublayer transform to the desired projection matrix. The default value of this property is the identity transform.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

superlayer

The superlayer of the layer. (read-only)

@property(readonly) CALayer *superlayer

Discussion

The superlayer manages the layout of its sublayers.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

transform

The transform applied to the layer’s contents. Animatable.

@property CATransform3D transform

Discussion

This property is set to the identity transform by default. Any transformations you apply to the layer occur relative to the layer’s anchor point.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• oalTouch

Declared In

CALayer.h

visibleRect

The visible region of the layer in its own coordinate space. (read-only)

@property(readonly) CGRect visibleRect

Discussion

The visible region is the area not clipped by the containing scroll layer.

Availability

• Available in iOS 2.0 and later.

Declared In

CAScrollLayer.h

zPosition

The layer’s position on the z axis. Animatable.

@property CGFloat zPosition

Discussion

The default value of this property is 0. Changing the value of this property changes the the front-to-back ordering of layers onscreen. This can affect the visibility of layers whose frame rectangles overlap.

The value of this property is measured in points.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• PhotosByLocation

Declared In

CALayer.h

Class Methods

defaultActionForKey:

Returns the default action for the current class.

+ (id < CAAction >)defaultActionForKey:(NSString *)key

Parameters

key

The identifier of the action.

Return Value

Returns a suitable action object for the given key or nil of no action object was associated with that key.

Discussion

Classes that want to provide default actions can override this method and use it to return those actions.

Availability

• Available in iOS 2.0 and later.

See Also

• – actionForKey:

Declared In

CALayer.h

defaultValueForKey:

Specifies the default value associated with the specified key.

+ (id)defaultValueForKey:(NSString *)key

Parameters

key

The name of one of the receiver’s properties.

Return Value

The default value for the named property. Returns nil if no default value has been set.

Discussion

If you define custom properties for a layer but do not set a value, this method returns a suitable “zero” default value based on the expected value of the key. For example, if the value for key is a CGSize struct, the method returns a size struct containing (0.0,0.0) wrapped in an NSValue object. For a CGRect an empty rectangle is returned. For CGAffineTransform and CATransform3D, the appropriate identity matrix is returned.

Special Considerations

If key is not a known for property of the class, the result of the method is undefined.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

layer

Creates and returns an instance of the layer object.

+ (id)layer

Return Value

The initialized layer object or nil if initialization was not successful.

Discussion

If you subclass CALayer, you may override this method and use it to provide an instance of your specific subclass.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AVLoupe
• AVSimpleEditoriOS
• CoreTextPageViewer
• MTAudioProcessingTap Audio Processor
• oalTouch

Declared In

CALayer.h

needsDisplayForKey:

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

+ (BOOL)needsDisplayForKey:(NSString *)key

Parameters

key

A string that specifies an attribute of the layer.

Return Value

YES if the layer requires a redisplay.

Discussion

Subclasses can override this method and return YES if the layer should be redisplayed when the value of the specified attribute changes. Animations changing the value of the attribute also trigger redisplay.

The default implementation of this method returns NO.

Availability

• Available in iOS 3.0 and later.

See Also

• + defaultActionForKey:
• + defaultValueForKey:

Declared In

CALayer.h

Instance Methods

actionForKey:

Returns the action object assigned to the specified key.

- (id < CAAction >)actionForKey:(NSString *)key

Parameters

key

The identifier of the action.

Return Value

Returns the object that provides the action for key. The object must implement the CAAction protocol.

Discussion

This method searches for the given action object of the layer. Actions define dynamic behaviors for a layer. For example, the animatable properties of a layer typically have corresponding action objects to initiate the actual animations. When that property changes, the layer looks for the action object associated with the property name and executes it. You can also associate custom action objects with your layer to implement app-specific actions.

This method searches for the layer’s associated actions in the following order:

1. If the layer has a delegate and that delegate implements the Accessing the Layer’s Filters method, the layer calls that method. The delegate must do one of the following:

   • Return the action object for the given key.

   • Return nil if it does not handle the action.

   • Return the NSNull object if it does not handle the action and the search should be terminated.

2. The layer looks in the layer’s actions dictionary.

3. The layer looks in the style dictionary for an actions dictionary that contains the key.

4. The layer calls its defaultActionForKey: method to look for any class-defined actions.

5. The layer looks for any implicit actions defined by Core Animation.

When an action object is invoked it receives three parameters: the name of the event, the object on which the event happened (the layer), and a dictionary of named arguments specific to each event kind.

Availability

• Available in iOS 2.0 and later.

See Also

• – Accessing the Layer’s Filters
•   @property actions
•   @property style
• + defaultActionForKey:

Related Sample Code

• iAdInterstitialSuite

Declared In

CALayer.h

addAnimation:forKey:

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

- (void)addAnimation:(CAAnimation *)anim forKey:(NSString *)key

Parameters

anim

The animation to be added to the render tree. This object is copied by the render tree, not referenced. Therefore, subsequent modifications to the object are not propagated into the render tree.

key

A string that identifies the animation. Only one animation per unique key is added to the layer. The special key kCATransition is automatically used for transition animations. You may specify nil for this parameter.

Discussion

If the duration property of the animation is zero or negative, the duration is changed to the current value of the kCATransactionAnimationDuration transaction property (if set) or to the default value of 0.25 seconds.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• MoveMe

Declared In

CALayer.h

addSublayer:

Appends the layer to the layer’s list of sublayers.

- (void)addSublayer:(CALayer *)aLayer

Parameters

aLayer

The layer to be added.

Discussion

If the array in the sublayers property is nil, calling this method creates an array for that property and adds the specified layer to it.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AVLoupe
• AVSimpleEditoriOS
• CoreTextPageViewer
• MTAudioProcessingTap Audio Processor
• SquareCam

Declared In

CALayer.h

affineTransform

Returns an affine version of the layer’s transform.

- (CGAffineTransform)affineTransform

Return Value

The affine transform structure that corresponds to the value in the layer’s transform property.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

animationForKey:

Returns the animation object with the specified identifier.

- (CAAnimation *)animationForKey:(NSString *)key

Parameters

key

A string that specifies the identifier of the animation. This string corresponds to the identifier string you passed to the addAnimation:forKey: method.

Return Value

The animation object matching the identifier, or nil if no such animation exists.

Discussion

You can use this string to retrieve animation objects already associated with a layer. However, you must not modify any properties of the returned object. Doing so will result in undefined behavior.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

animationKeys

Returns an array of strings that identify the animations currently attached to the layer.

- (NSArray *)animationKeys

Return Value

An array of NSString objects identifying the current animations.

Discussion

The order of the array matches the order in which animations will be applied to the layer.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

containsPoint:

Returns whether the receiver contains a specified point.

- (BOOL)containsPoint:(CGPoint)thePoint

Parameters

thePoint

A point in the receiver’s coordinate system.

Return Value

YES if the bounds of the layer contains the point.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

contentsAreFlipped

Returns a Boolean indicating whether the layer content is implicitly flipped when rendered.

- (BOOL)contentsAreFlipped

Return Value

YES if the layer contents are implicitly flipped when rendered or NO if they are not. This method returns NO by default.

Discussion

This method provides information about whether the layer’s contents are being flipped during drawing. You should not attempt to override this method and return a different value.

If the layer needs to flip its content, it returns YES from this method and applies a y-flip transform to the graphics context before passing it to the layer’s drawInContext: method. Similarly, the layer converts any rectangles passed to its setNeedsDisplayInRect: into the flipped coordinate space.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

convertPoint:fromLayer:

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

- (CGPoint)convertPoint:(CGPoint)aPoint fromLayer:(CALayer *)layer

Parameters

aPoint

A point specifying a location in the coordinate system of layer.

layer

The layer with aPoint in its coordinate system. The receiver and layer and must share a common parent layer. This parameter may be nil.

Return Value

The point converted to the receiver’s coordinate system.

Discussion

If you specify nil for the layer parameter, this method returns the original point.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

convertPoint:toLayer:

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

- (CGPoint)convertPoint:(CGPoint)aPoint toLayer:(CALayer *)layer

Parameters

aPoint

A point specifying a location in the coordinate system of layer.

layer

The layer into whose coordinate system aPoint is to be converted. The receiver and layer must share a common parent layer.

Return Value

The point converted to the coordinate system of layer.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

convertRect:fromLayer:

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

- (CGRect)convertRect:(CGRect)aRect fromLayer:(CALayer *)layer

Parameters

aRect

A point specifying a location in the coordinate system of layer.

layer

The layer with aRect in its coordinate system. The receiver and layer and must share a common parent layer.

Return Value

The rectangle converted to the receiver’s coordinate system.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

convertRect:toLayer:

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

- (CGRect)convertRect:(CGRect)aRect toLayer:(CALayer *)layer

Parameters

aRect

A point specifying a location in the coordinate system of layer.

layer

The layer into whose coordinate system aRect is to be converted. The receiver and layer and must share a common parent layer.

Return Value

The rectangle converted to the coordinate system of layer.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

convertTime:fromLayer:

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

- (CFTimeInterval)convertTime:(CFTimeInterval)timeInterval fromLayer:(CALayer *)layer

Parameters

timeInterval

A point specifying a location in the coordinate system of layer.

layer

The layer with timeInterval in its time space. The receiver and layer and must share a common parent layer.

Return Value

The time interval converted to the receiver’s time space.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

convertTime:toLayer:

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

- (CFTimeInterval)convertTime:(CFTimeInterval)timeInterval toLayer:(CALayer *)layer

Parameters

timeInterval

A point specifying a location in the coordinate system of layer.

layer

The layer into whose time space timeInterval is to be converted. The receiver and layer and must share a common parent layer.

Return Value

The time interval converted to the time space of layer.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

display

Reloads the content of this layer.

- (void)display

Discussion

Do not call this method directly. The layer calls this method at appropriate times to update the layer’s content. If the layer has a delegate object, this method attempts to call the delegate’s displayLayer: method, which the delegate can use to update the layer’s contents. If the delegate does not implement the displayLayer: method, this method creates a backing store and calls the layer’s drawInContext: method to fill that backing store with content. The new backing store replaces the previous contents of the layer.

Subclasses can override this method and use it to set the layer’s contents property directly. You might do this if your custom layer subclass handles layer updates differently.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• CoreTextPageViewer

Declared In

CALayer.h

displayIfNeeded

Initiates the update process for a layer if it is currently marked as needing an update.

- (void)displayIfNeeded

Discussion

You can call this method as needed to force an update to your layer’s contents outside of the normal update cycle. Doing so is generally not needed, though. The preferred way to update a layer is to call setNeedsDisplay and let the system update the layer during the next cycle.

Availability

• Available in iOS 3.0 and later.

See Also

• – needsDisplay

Declared In

CALayer.h

drawInContext:

Draws the layer’s content using the specified graphics context.

- (void)drawInContext:(CGContextRef)ctx

Parameters

ctx

The graphics context in which to draw the content. The context may be clipped to protect valid layer content. Subclasses that wish to find the actual region to draw can call CGContextGetClipBoundingBox.

Discussion

The default implementation of this method does not doing any drawing itself. If the layer’s delegate implements the drawLayer:inContext: method, that method is called to do the actual drawing.

Subclasses can override this method and use it to draw the layer’s content. When drawing, all coordinates should be specified in points in the logical coordinate space.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

hitTest:

Returns the farthest descendant of the receiver in the layer hierarchy (including itself) that contains the specified point.

- (CALayer *)hitTest:(CGPoint)thePoint

Parameters

thePoint

A point in the coordinate system of the receiver's superlayer.

Return Value

The layer that contains thePoint or nil if the point lies outside the receiver’s bounds rectangle.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

init

Returns an initialized CALayer object.

- (id)init

Return Value

An initialized CALayer object.

Discussion

This is the designated initializer for layer objects that are not in the presentation layer.

Availability

• Available in iOS 2.0 and later.

See Also

• + layer

Declared In

CALayer.h

initWithLayer:

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

- (id)initWithLayer:(id)layer

Parameters

layer

The layer from which custom fields should be copied.

Return Value

A layer instance with any custom instance variables copied from layer.

Discussion

This initializer is used to create shadow copies of layers, for example, for the presentationLayer method. Using this method in any other situation will produce undefined behavior. For example, do not use this method to initialize a new layer with an existing layer’s content.

If you are implementing a custom layer subclass, you can override this method and use it to copy the values of instance variables into the new object. Subclasses should always invoke the superclass implementation.

This method is the designated initializer for layer objects in the presentation layer.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

insertSublayer:above:

Inserts the specified sublayer above a different sublayer that already belongs to the receiver.

- (void)insertSublayer:(CALayer *)aLayer above:(CALayer *)sublayer

Parameters

aLayer

The sublayer to be inserted into the current layer.

sublayer

An existing sublayer in the current layer. The layer in aLayer is inserted after this layer in the sublayers array, and thus appears in front of it visually.

Special Considerations

If sublayer is not in the receiver’s sublayers array, this method raises an exception.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

insertSublayer:atIndex:

Inserts the specified layer into the receiver’s list of sublayers at the specified index.

- (void)insertSublayer:(CALayer *)aLayer atIndex:(unsigned)index

Parameters

aLayer

The sublayer to be inserted into the current layer.

index

The index at which to insert aLayer. This value must be a valid 0-based index into the sublayers array.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

insertSublayer:below:

Inserts the specified sublayer below a different sublayer that already belongs to the receiver.

- (void)insertSublayer:(CALayer *)aLayer below:(CALayer *)sublayer

Parameters

aLayer

The sublayer to be inserted into the current layer.

sublayer

An existing sublayer in the current layer. The layer in aLayer is inserted before this layer in the sublayers array, and thus appears behind it visually.

Discussion

If sublayer is not in the receiver’s sublayers array, this method raises an exception.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AVCam

Declared In

CALayer.h

layoutIfNeeded

Recalculate the receiver’s layout, if required.

- (void)layoutIfNeeded

Discussion

When this message is received, the layer’s super layers are traversed until a ancestor layer is found that does not require layout. Then layout is performed on the entire layer-tree beneath that ancestor.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

layoutSublayers

Tells the layer to update its layout.

- (void)layoutSublayers

Discussion

Subclasses can override this method and use it to implement their own layout algorithm. Your implementation must set the frame of each sublayer managed by the receiver.

The default implementation of this method calls the layoutSublayersOfLayer: method of the layer’s delegate object. If there is no delegate object, or the delegate does not implement that method, this method calls the layoutSublayersOfLayer: method of the object in the layoutManager property.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

modelLayer

Returns the model layer object associated with the receiver, if any.

- (id)modelLayer

Return Value

A layer instance representing the underlying model layer.

Discussion

Calling this method on a layer in the presentation tree returns the corresponding layer object in the model tree. This method returns a value only when a transaction involving changes to the presentation layer is in progress. If no transaction is in progress, the results of calling this method are undefined.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

needsDisplay

Returns a Boolean indicating whether the layer has been marked as needing an update.

- (BOOL)needsDisplay

Return Value

YES if the layer needs to be updated.

Availability

• Available in iOS 3.0 and later.

Declared In

CALayer.h

needsLayout

Returns a Boolean indicating whether the layer has been marked as needing a layout update.

- (BOOL)needsLayout

Return Value

YES if the layer has been marked as requiring a layout update.

Availability

• Available in iOS 3.0 and later.

See Also

• – setNeedsLayout

Declared In

CALayer.h

preferredFrameSize

Returns the preferred size of the layer in the coordinate space of its superlayer.

- (CGSize)preferredFrameSize

Return Value

The layer’s preferred frame size.

Discussion

In OS X, the default implementation of this method calls the preferredSizeOfLayer: method of its layout manager—that is, the object in its layoutManager property. If that object does not exist or does not implement that method, this method returns the size of the layer’s current bounds rectangle mapped into the coordinate space of its superlayer.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

presentationLayer

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

- (id)presentationLayer

Return Value

A copy of the current presentation layer object.

Discussion

The layer object returned by this method provides a close approximation of the layer that is currently being displayed onscreen. While an animation is in progress, you can retrieve this object and use it to get the current values for those animations.

The sublayers, mask, and superlayer properties of the returned layer return the corresponding objects from the presentation tree (not the model tree). This pattern also applies to any read-only layer methods. For example, the hitTest: method of the returned object queries the layer objects in the presentation tree.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

removeAllAnimations

Remove all animations attached to the layer.

- (void)removeAllAnimations

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

removeAnimationForKey:

Remove the animation object with the specified key.

- (void)removeAnimationForKey:(NSString *)key

Parameters

key

The identifier of the animation to remove.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

removeFromSuperlayer

Detaches the layer from its parent layer.

- (void)removeFromSuperlayer

Discussion

You can use this method to remove a layer (and all of its sublayers) from a layer hierarchy. This method updates both the superlayer’s list of sublayers and sets this layer’s superlayer property to nil.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

renderInContext:

Renders the receiver and its sublayers into the specified context.

- (void)renderInContext:(CGContextRef)ctx

Parameters

ctx

The graphics context to use to render the layer.

Discussion

This method renders directly from the layer tree, ignoring any animations added to the render tree. Renders in the coordinate space of the layer.

Important: The OS X v10.5 implementation of this method does not support the entire Core Animation composition model. QCCompositionLayer, CAOpenGLLayer, and QTMovieLayer layers are not rendered. Additionally, layers that use 3D transforms are not rendered, nor are layers that specify backgroundFilters, filters, compositingFilter, or a mask values. Future versions of OS X may add support for rendering these layers and properties.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

replaceSublayer:with:

Replaces the specified sublayer with a different layer object.

- (void)replaceSublayer:(CALayer *)oldLayer with:(CALayer *)newLayer

Parameters

oldLayer

The layer to be replaced.

newLayer

The layer with which to replace oldLayer.

Discussion

If oldLayer is not in the receiver’s sublayers array, the behavior of this method is undefined.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

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.

- (void)scrollPoint:(CGPoint)thePoint

Parameters

thePoint

The point in the current layer that should be scrolled into position.

Discussion

If the layer is not contained by a CAScrollLayer object, this method does nothing.

Availability

• Available in iOS 2.0 and later.

Declared In

CAScrollLayer.h

scrollRectToVisible:

Initiates a scroll in the layer’s closest ancestor scroll layer so that the specified rectangle becomes visible.

- (void)scrollRectToVisible:(CGRect)theRect

Parameters

theRect

The rectangle to be made visible.

Discussion

If the layer is not contained by a CAScrollLayer object, this method does nothing.

Availability

• Available in iOS 2.0 and later.

Declared In

CAScrollLayer.h

setAffineTransform:

Sets the layer’s transform to the specified affine transform.

- (void)setAffineTransform:(CGAffineTransform)m

Parameters

m

The affine transform to use for the layer’s transform.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• SquareCam

Declared In

CALayer.h

setNeedsDisplay

Marks the layer’s contents as needing to be updated.

- (void)setNeedsDisplay

Discussion

Calling this method causes the layer to recache its content. This results in the layer potentially calling either the displayLayer: or drawLayer:inContext: method of its delegate. The existing content in the layer’s contents property is removed to make way for the new content.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• AccelerometerGraph
• CoreTextPageViewer

Declared In

CALayer.h

setNeedsDisplayInRect:

Marks the region within the specified rectangle as needing to be updated.

- (void)setNeedsDisplayInRect:(CGRect)theRect

Parameters

theRect

The rectangular region of the layer to mark as invalid. You must specify this rectangle in the layer’s own coordinate system.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

setNeedsLayout

Invalidates the layer’s layout and marks it as needing an update.

- (void)setNeedsLayout

Discussion

You can call this method to indicate that the layout of a layer’s sublayers has changed and must be updated. The system typically calls this method automatically when the layer’s bounds change or when sublayers are added or removed. In OS X, if your layer’s layoutManager property contains an object that implements the invalidateLayoutOfLayer: method, that method is called too.

During the next update cycle, the system calls the layoutSublayers method of any layers requiring layout updates.

Availability

• Available in iOS 2.0 and later.

Declared In

CALayer.h

shouldArchiveValueForKey:

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

- (BOOL)shouldArchiveValueForKey:(NSString *)key

Parameters

key

The name of one of the receiver’s properties.

Return Value

YES if the specified property should be archived or NO if it should not.

Discussion

The default implementation returns YES.

Availability

• Available in iOS 4.0 and later.

Declared In

CALayer.h

Constants

Action Identifiers

These constants are the predefined action identifiers used by actionForKey:, addAnimation:forKey:, defaultActionForKey:, removeAnimationForKey:, Accessing the Layer’s Filters, and the CAAction protocol method runActionForKey:object:arguments:.

NSString * const kCAOnOrderIn;
NSString * const kCAOnOrderOut;
NSString * const kCATransition;

Constants

kCAOnOrderIn

The identifier that represents the action taken when a layer becomes visible, either as a result being inserted into the visible layer hierarchy or the layer is no longer set as hidden.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAOnOrderOut

The identifier that represents the action taken when the layer is removed from the layer hierarchy or is hidden.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCATransition

The identifier that represents a transition animation.

Available in iOS 2.0 and later.

Declared in CALayer.h.

Declared In

CALayer.h

Edge Antialiasing Mask

This mask is used by the edgeAntialiasingMask property.

   
enum CAEdgeAntialiasingMask
{
   kCALayerLeftEdge    = 1U << 0,
   kCALayerRightEdge    = 1U << 1,
   kCALayerBottomEdge    = 1U << 2,
   kCALayerTopEdge    = 1U << 3,
};

Constants

kCALayerLeftEdge

Specifies that the left edge of the receiver’s content should be antialiased.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCALayerRightEdge

Specifies that the right edge of the receiver’s content should be antialiased.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCALayerBottomEdge

Specifies that the bottom edge of the receiver’s content should be antialiased.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCALayerTopEdge

Specifies that the top edge of the receiver’s content should be antialiased.

Available in iOS 2.0 and later.

Declared in CALayer.h.

Declared In

CALayer.h

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. The are used by the contentsGravity property.

NSString * const kCAGravityCenter;
NSString * const kCAGravityTop;
NSString * const kCAGravityBottom;
NSString * const kCAGravityLeft;
NSString * const kCAGravityRight;
NSString * const kCAGravityTopLeft;
NSString * const kCAGravityTopRight;
NSString * const kCAGravityBottomLeft;
NSString * const kCAGravityBottomRight;
NSString * const kCAGravityResize;
NSString * const kCAGravityResizeAspect;
NSString * const kCAGravityResizeAspectFill;

Constants

kCAGravityCenter

The content is horizontally and vertically centered in the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityTop

The content is horizontally centered at the top-edge of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityBottom

The content is horizontally centered at the bottom-edge of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityLeft

The content is vertically centered at the left-edge of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityRight

The content is vertically centered at the right-edge of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityTopLeft

The content is positioned in the top-left corner of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityTopRight

The content is positioned in the top-right corner of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityBottomLeft

The content is positioned in the bottom-left corner of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityBottomRight

The content is positioned in the bottom-right corner of the bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityResize

The content is resized to fit the entire bounds rectangle.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityResizeAspect

The content is resized to fit the bounds rectangle, preserving the aspect of the content. If the content does not completely fill the bounds rectangle, the content is centered in the partial axis.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAGravityResizeAspectFill

The content is resized to completely fill the bounds rectangle, while still preserving the aspect of the content. The content is centered in the axis it exceeds.

Available in iOS 2.0 and later.

Declared in CALayer.h.

Declared In

CALayer.h

Identity Transform

Defines the identity transform matrix used by Core Animation.

const CATransform3D CATransform3DIdentity

Constants

CATransform3DIdentity

The identity transform: [1 0 0 0; 0 1 0 0; 0 0 1 0; 0 0 0 1].

Available in iOS 2.0 and later.

Declared in CATransform3D.h.

Declared In

CATransform3D.h

Scaling Filters

These constants specify the scaling filters used by magnificationFilter and minificationFilter.

NSString * const kCAFilterLinear;
NSString * const kCAFilterNearest;
NSString * const kCAFilterTrilinear;

Constants

kCAFilterLinear

Linear interpolation filter.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAFilterNearest

Nearest neighbor interpolation filter.

Available in iOS 2.0 and later.

Declared in CALayer.h.

kCAFilterTrilinear

Trilinear minification filter. Enables mipmap generation. Some renderers may ignore this, or impose additional restrictions, such as source images requiring power-of-two dimensions..

Available in iOS 3.0 and later.

Declared in CALayer.h.

Declared In

CALayer.h

CATransform3D

Defines the standard transform matrix used throughout Core Animation.

struct CATransform3D
{
CGFloat m11, m12, m13, m14;
CGFloat m21, m22, m23, m24;
CGFloat m31, m32, m33, m34;
CGFloat m41, m42, m43, m44;
};
typedef struct CATransform3D CATransform3D;

Fields

m11

The entry at position 1,1 in the matrix.

m12

The entry at position 1,2 in the matrix.

m13

The entry at position 1,3 in the matrix.

m14

The entry at position 1,4 in the matrix.

m21

The entry at position 2,1 in the matrix.

m22

The entry at position 2,2 in the matrix.

m23

The entry at position 2,3 in the matrix.

m24

The entry at position 2,4 in the matrix.

m31

The entry at position 3,1 in the matrix.

m32

The entry at position 3,2 in the matrix.

m33

The entry at position 3,3 in the matrix.

m34

The entry at position 3,4 in the matrix.

m41

The entry at position 4,1 in the matrix.

m42

The entry at position 4,2 in the matrix.

m43

The entry at position 4,3 in the matrix.

m44

The entry at position 4,4 in the matrix.

Discussion

The transform matrix is used to rotate, scale, translate, skew, and project the layer content. Functions are provided for creating, concatenating, and modifying CATransform3D data.

Availability

• Available in iOS 2.0 and later.

Declared In

CATransform3D.h