Instance Methods | Class Methods | Properties | List of all members
CC3ParticleNavigator Class Reference

#import <CC3Particles.h>

Inheritance diagram for CC3ParticleNavigator:
Inheritance graph

Instance Methods

(void) - initializeParticle:
(void) - populateFrom:

Class Methods

(id) + navigator



Detailed Description

A particle navigator is assigned to a single particle emitter, and is responsible for configuring the life cycle and emission path of the particle on behalf of the emitter.

When creating your own particle system, customization is accomplished primarily by creating your own implementation of the CC3ParticleProtocol, and your own CC3ParticleNavigator subclass. You are encouraged to create subclasses of CC3ParticleNavigator (perhaps starting from one of the existing provided subclasses).

During particle initialization, the emitter, the navigator, and the particle itself are given a chance to participate in the initialization of the particle. The navigator is distinct from the emitter itself in that the navigator is primarily designed to direct the shape of the emission, by setting particle properties such as the location, direction, and speed of the particle. This separation of responsibilities often means that a single navigator class can be used to direct any type of particle.

For example, a particle navigator designed to emit partiles in the the shape of a fountain could be used to create a fountain of point particles, a fountain of mesh particles, or a fountain of some other class of particles that supported the protocol required by the navigator.

Similarly, a navigator designed to lay particles out on a grid, or sprinkle stars across the sky could do so with point particles or mesh particles.

The particle navigator is only involved in the initialization of the particle. It does not interact with the particle once it has been emitted.

Different particle navigators will have different requirements for configuring particles. The requiredParticleProtocol property of this navigator indicates the protocol that the particles must support in order to be prepared by this navigator during initialization.

Method Documentation

- (void) initializeParticle: (id< CC3ParticleProtocol >)  aParticle

Template method that initializes the particle.

For particles that follow a planned life-cycle and trajectory, this navigator configures that life-cycle and trajectory for the particle prior to the particle being emitted.

This method is invoked automatically from the emitter after the emitter has initialized the particle and before the initializeParticle method is invoked on the particle itself.

Subclasses will override this method to configure the particle. Subclasses should always invoke the superclass implementation to ensure the superclass initialization behaviour is performed.

In this method, you can set the isAlive property of the particle to NO to cause the emission of the particle to be aborted.

When this method is invoked, the particle may have just been instantiated, or it may be an older expired particle that is being reused. With this in mind, this method should include all code that establishes the initial emitted state of a particle that is to be set by the navigator. You should not rely on any state set in the instance initializer of the particle class.

This method is invoked automatically by the emitter when a particle is emitted. Usually the application never has need to invoke this method directly.

+ (id) navigator

Allocates and initializes an autoreleased unnamed instance with an automatically generated unique tag value.

The tag value is generated using a call to nextTag.

- (void) populateFrom: (CC3ParticleNavigator *)  another

Template method that populates this instance from the specified other instance.

This method is invoked automatically during object copying via the copy or copyWithZone: method. In most situations, the application should use the copy method, and should never need to invoke this method directly.

Subclasses that add additional instance state (instance variables) should extend copying by overriding this method to copy that additional state. Superclass that override this method should be sure to invoke the superclass implementation to ensure that superclass state is copied as well.

Property Documentation

- (CC3ParticleEmitter*) emitter

The emitter whose particles are prepared by this navigator.

This property is set automatically when the navigator is attached to the emitter. Usually the application never needs to set this property directly.

The documentation for this class was generated from the following file: