CAEmitterLayer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in iOS 5.0 and later.
Declared in
CAEmitterLayer.h
Companion guides

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 iOS 5.0 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 iOS 5.0 and later.
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 iOS 5.0 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 iOS 5.0 and later.
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 iOS 5.0 and later.
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 iOS 5.0 and later.
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 iOS 5.0 and later.
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 iOS 5.0 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 iOS 5.0 and later.
Declared In
CAEmitterLayer.h

preservesDepth

Defines whether the layer flattens 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 iOS 5.0 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 iOS 5.0 and later.
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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerOutline

Particles are emitted from the outline of the particle emitter.

Available in iOS 5.0 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerSurface

Particles are emitted from the surface of the particle emitter.

Available in iOS 5.0 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerVolume

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

Available in iOS 5.0 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 iOS 5.0 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerOldestFirst

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

Available in iOS 5.0 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerOldestLast

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

Available in iOS 5.0 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 iOS 5.0 and later.

Declared in CAEmitterLayer.h.

kCAEmitterLayerAdditive

The particles are rendered using source-additive compositing.

Available in iOS 5.0 and later.

Declared in CAEmitterLayer.h.