Instance Methods | |
| (void) | - finalizeParticle |
| (NSString *) | - fullDescription |
| (id) | - init |
| (void) | - initializeParticle |
| (void) | - updateAfterTransform: |
| (void) | - updateBeforeTransform: |
 Instance Methods inherited from <CC3Object> | |
| (id) | - asWeakReference |
| (id) | - resolveWeakReference |
Properties | |
| CC3ParticleEmitter * | emitter |
| BOOL | isAlive |
Detailed Description
The protocol required by this particle navigator on the particles, in order for this navigator to configure the particles.
This implementation returns particles to be initialized. In a subclass, you may override to support more specific protocols, based on your needs for configuring particles. When doing so, your protocol must also conform to the base CC3ParticleProtocol protocol.
Because each configuration is unique, this library contains a number of building-block configuration protocols that may be applied to a particle. And you will often want to create your own particle configuration protocols. Since this property may contain only a single protocol, you can create a custom protocol that wraps all of the protocols that you want to use to configure your particle, and assign that custom protocol to this property.
For example, you may want to use both the CC3UniformlyFadingParticleProtocol and CC3MortalParticleProtocol protocols to configure a fading particle that has a finite life. To encompass both requirements, you should create another custom protocol that wraps (conforms to) both of those protocols, and assign it to this requiredParticleProtocol property.
Method Documentation
| - (void) finalizeParticle |
This template callback method is invoked automatically at the end of the particle's lifecycle, when this particle has expired and been removed from active use.
Since the emitter may hold onto the particle in an inactive state for future reuse, this method provides the particle with the opportunity to release any content that depends on the particle being alive and in use.
| - (NSString*) fullDescription |
Returns a string containing a more complete description of this particle.
Reimplemented from <CC3Object>.
| - (id) init |
The standard object initialization method that is invoked when this instance is instantiated.
In the interests of performance and memory conservation, expired particles may be cached and reused by the emitter. Your particle should not rely on any state set in this method. Most initialization should be performed in the initializeParticle method, which is invoked each time the particle is used or reused by the emitter.
| - (void) initializeParticle |
This template callback method is invoked automatically at the beginning of the particle's life-cycle, when this particle is added to the emitter manually by the application, or when the particle is emitted automatically by the emitter.
You should implement this method to establish any initial state of the particle.
During execution of this method, you can access and set the initial values of the particle properties. The emitter property can be used to access further information in the emitter or other aspects of the 3D scene.
This method is invoked after the the isAlive property has been set to YES, and after the emitter and its navigator have set any particle state that they want to initialize. In this method, you can change any of the particle state prior to it being emitted. You can also set the isAlive property of the particle to NO to cause the addition or 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 state of a particle. You should not rely on any state set in the init method of the particle.
If you have subclassed another class that implements the CC3ParticleProtocol protocol, you should be sure to invoke this method on the superclass as part of your implementation, to give the superclass an opportunity to initialize the state it manages. You should also check the state of the isAlive property as set by the superclass before performing further initialization.
| - (void) updateAfterTransform: | (CC3NodeUpdatingVisitor *) | visitor |
This template callback method is invoked automatically whenever the emitter is updated during a scheduled 3D scene update.
This method is invoked on the particles after the emitter and particles have been transformed, and before the updateAfterTransform: method is invoked on the emitter.
Because this method is invoked after the emitter has been transformed, you can access global transform properties of the particle and emitter from within this method.
The specified visitor includes a deltaTime property, which is the time interval since the last update, so that the particle can emulate realistic real-time behaviour
This method will only be invoked on the particles if the shouldUpdateParticlesAfterTransform property of the emitter is set to YES. As an optimization, for particles that do not need to be updated after they are transformed, that property can be set to NO to avoid an unnecessary iteration of the particles.
Although it is recommended that you determine whether a particle should expire in the updateBeforeTransform: method to avoid transforming a particle you no longer need, you can also set the isAlive property of the particle to NO in this method to cause the emitter to remove this particle (and set it aside for possible reuse). Expired particles are not drawn and do not receive further updateAfterTransform: method invocations.
| - (void) updateBeforeTransform: | (CC3NodeUpdatingVisitor *) | visitor |
This template callback method is invoked automatically whenever the emitter is updated during a scheduled 3D scene update.
This method is invoked on the particles after the updateBeforeTransform: method is invoked on the emitter, and before the emitter and particles are transformed.
This method will only be invoked on the particles if the shouldUpdateParticlesBeforeTransform property of the emitter is set to YES. As an optimization, for particles that do not need to be updated before they are transformed, that property can be set to NO to avoid an unnecessary iteration of the particles.
You can override this method to control the behaviour and motion of the particle during its lifetime.
The specified visitor includes a deltaTime property, which is the time interval since the last update, so that the particle can emulate realistic real-time behaviour
It is up to the particle to determine when it expires. Some particles may never expire. Particles that do have a finite lifespan will keep track of their lifecycle, and accumulate the deltaTime property of the specified visitor to keep track of the passing of time.
Once the particle has detemined that it has expired, you can set the isAlive property of the particle to NO in this method. When this method returns, if the isAlive property has been set to NO, the emitter will automatically remove this particle (and set it aside for possible reuse). Expired particles are not drawn and do not receive further updateBeforeTransform: method invocations.
During execution of this method, you can access and set the particle's properties. The emitter property can be used to access further information in the emitter or other aspects of the 3D scene.
Property Documentation
|
readwritenonatomicassign |
The emitter that emitted this particle.
This property is set automatically when the particle is added to the emitter, or emitted automatically by the emitter. The application should not set this property directly. Doing so will cause the particle to abort emission.
|
readwritenonatomicassign |
Indicates whether this particle is alive or not.
When a particle is added to the emitter, or emitted automatically by the emitter, the value of this property is automatically set to YES by the emitter before the initializeParticle method is invoked.
You can set this property to NO from within the updateBeforeTransform: or updateAfterTransform: method to indicate that this particle has expired. When either of those methods returns, the emitter will then automatically remove the particle (and set it aside for possible reuse). Expired particles are not drawn and do not receive further updateBeforeTransform: or updateAfterTransform: method invocations.
You can also set the isAlive property to NO in the initializeParticle method to cause the emission of the particle to be aborted.
The documentation for this protocol was generated from the following file:
