CAEmitterLayer Class Reference

Inherits from	CALayer : NSObject
Conforms to	NSCoding (CALayer) CAMediaTiming (CALayer) NSObject (NSObject)
Framework	/System/Library/Frameworks/QuartzCore.framework
Availability	Available in OS X v10.6 and later.
Declared in	CAEmitterLayer.h
Companion guides	Core Animation Programming Guide Core Animation Cookbook
Related sample code	Fire Fireworks

Overview

The CAEmitterLayer class provides a particle emitter system for Core Animation. The particles are defined by instances of CAEmitterCell.

The particles are drawn above the layer’s background color and border

Tasks

Specifying Particle Emitter Cells

Emitter Geometry

Emitter Cell Attribute Multipliers

Properties

birthRate

Defines a multiplier that is applied to the cell-defined birth rate. Animatable

@property float birthRate

Discussion

The birth rate of each cell is multiplied by this number to give the actual number of particles created every second. Default value is 1.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

emitterCells

The array emitter cells attached to the layer.

@property(copy) NSArray *emitterCells

Discussion

Each object in the array must be an instance of the CAEmitterCell class.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

CAEmitterLayer.h

emitterDepth

Determines the depth of the emitter shape.

@property CGFloat emitterDepth

Discussion

How the emitter depth is applied depends on the emitter shape. See “Emitter Shape” for details. Depending on the value of emitterShape, this value may be ignored.

Default is 0.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

emitterMode

Specifies the emitter mode.

@property(copy) NSString *emitterMode

Discussion

The possible values for emitterMode are shown in “Emitter Modes.” The default value is kCAEmitterLayerVolume.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Fire

Declared In

CAEmitterLayer.h

emitterPosition

The position of the center of the particle emitter. Animatable.

@property CGPoint emitterPosition

Discussion

See “Emitter Shape” for details of how the emitterPosition relates to the possible emitter shapes.

Default is (0.0,0.0).

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

CAEmitterLayer.h

emitterShape

Specifies the emitter shape.

@property(copy) NSString *emitterShape

Discussion

The possible values for emitterMode are shown in “Emitter Shape.” The default value is kCAEmitterLayerPoint.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Fire

Declared In

CAEmitterLayer.h

emitterSize

Determines the size of the particle emitter shape. Animatable.

@property CGSize emitterSize

Discussion

How the emitter size is applied depends on the emitter shape. See “Emitter Shape” for details. Depending on the value of emitterShape, this value may be ignored.

Default is 0.0.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Fire

Declared In

CAEmitterLayer.h

emitterZPosition

Specifies the center of the particle emitter shape along the z-axis. Animatable.

@property CGFloat emitterZPosition

Discussion

See “Emitter Shape” for details of how the emitterZPosition relates to the possible emitter shapes.

Default is 0.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

lifetime

Defines a multiplier applied to the cell-defined lifetime range when particles are created. Animatable.

@property float lifetime

Discussion

Default value is 1.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

preservesDepth

Defines whether the layer flattens its the particles into its plane.

@property BOOL preservesDepth

Discussion

If YES, the layer renders its particles as if they directly inhabit the three-dimensional coordinate space of the layer’s superlayer. When enabled, the effect of the layer’s filters, backgroundFilters, and shadow related properties is undefined.

Default is NO.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

renderMode

Defines how particle cells are rendered into the layer.

@property(copy) NSString *renderMode

Discussion

The possible values for render modes are shown in “Emitter Modes.” The default value is kCAEmitterLayerUnordered.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

CAEmitterLayer.h

scale

Defines a multiplier applied to the cell-defined particle scale.

@property float scale

Discussion

Default value is 1.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

seed

Specifies the seed used to initialize the random number generator.

@property unsigned int seed

Discussion

Each layer has its own random number generator state. Emitter cell properties that are defined as a mean and a range, such as a cell’s speed, the value of the properties are uniformly distributed in the interval [M - R/2, M + R/2].

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

spin

Defines a multiplier applied to the cell-defined particle spin. Animatable.

@property float spin

Discussion

Default value is 1.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

velocity

Defines a multiplier applied to the cell-defined particle velocity. Animatable.

@property float velocity

Discussion

Default value is 1.0.

Availability

Available in OS X v10.6 and later.

Declared In

CAEmitterLayer.h

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.

NSString * const kCAEmitterLayerPoint;
NSString * const kCAEmitterLayerLine;
NSString * const kCAEmitterLayerRectangle;
NSString * const kCAEmitterLayerCuboid;
NSString * const kCAEmitterLayerCircle;
NSString * const kCAEmitterLayerSphere;

Constants

kCAEmitterLayerPoint

Particles are emitted from a single point at (emitterPosition.x, emitterPosition.y, emitterZPosition)

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerLine

Particles are emitted along a line from (emitterPosition.x - emitterSize.width/2, emitterPosition.y, emitterZPosition) to (emitterPosition.x + emitterSize.width/2, emitterPosition.y, emitterZPosition).

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerRectangle

Particles are emitted from a rectangle with opposite corners [emitterPosition.x - emitterSize.width/2, emitterPosition.y - emitterSize.height/2, emitterZPosition], [emitterPosition.x + emitterSize.width/2, emitterPosition.y + emitterSize.height/2, emitterZPosition].

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerCuboid

Particles are emitted from a cuboid (3D rectangle) with opposite corners: [emitterPosition.x - emitterSize.width/2, emitterPosition.y - emitterSize.height/2, emitterZPosition - emitterDepth/2], [emitterPosition.x + emitterSize.width/2, emitterPosition.y + emitterSize.height/2, emitterZPosition+emitterDepth/2].

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerCircle

Particles are emitted from a circle centered at (emitterPosition.x, emitterPosition.y, emitterZPosition) of radius emitterSize.width.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerSphere

Particles are emitted from a sphere centered at (emitterPosition.x, emitterPosition.y, emitterZPosition) of radius emitterSize.width.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

Emitter Modes

These constants specify the possible emitter modes. They are used by the emitterMode property.

NSString * const kCAEmitterLayerPoints;
NSString * const kCAEmitterLayerOutline;
NSString * const kCAEmitterLayerSurface;
NSString * const kCAEmitterLayerVolume;

Constants

kCAEmitterLayerPoints

Particles are emitted from points on the particle emitter.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerOutline

Particles are emitted from the outline of the particle emitter.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerSurface

Particles are emitted from the surface of the particle emitter.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerVolume

Particles are emitted from the a position within the particle emitter.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

Emitter Render Order

These constants specify the order that emitter cells are composited. They are used by the renderMode property.

NSString * const kCAEmitterLayerUnordered;
NSString * const kCAEmitterLayerOldestFirst;
NSString * const kCAEmitterLayerOldestLast;
NSString * const kCAEmitterLayerBackToFront;
NSString * const kCAEmitterLayerAdditive;

Constants

kCAEmitterLayerUnordered

Particles are rendered unordered. This mode uses source-over compositing.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerOldestFirst

Particles are rendered oldest first. This mode uses source-over compositing.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerOldestLast

Particles are rendered oldest last. This mode uses source-over compositing.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerBackToFront

Particles are rendered from back to front, sorted by z-position. This mode uses source-over compositing.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerAdditive

The particles are rendered using source-additive compositing.

Available in OS X v10.6 and later.

Declared in CAEmitterLayer.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.