CC3PointParticle is an abstract class that represents a single particle emitted by a CC3PointParticleEmitter. More...
#import <CC3PointParticles.h>
Public Member Functions | |
| (NSString *) | - fullDescription |
| (id) | - initFromEmitter: |
| (void) | - initializeParticle |
| (void) | - update: |
Static Public Member Functions | |
| (id) | + particleFromEmitter: |
Properties | |
| ccColor4B | color4B |
| ccColor4F | color4F |
| CC3PointParticleEmitter * | emitter |
| BOOL | hasColor |
| BOOL | hasNormal |
| BOOL | hasSize |
| GLuint | index |
| BOOL | isAlive |
| CC3Vector | location |
| CC3Vector | normal |
| GLfloat | size |
Detailed Description
CC3PointParticle is an abstract class that represents a single particle emitted by a CC3PointParticleEmitter.
When creating a particle system, you write application-specific subclasses of CC3PointParticle to embody the state and life-cycle behaviour of each particle. You do not typically need to create a customized subclass of CC3PointParticleEmitter.
To implement a specific particle system, create a subclass of CC3PointParticle, and override the initializeParticle and update: methods to define the initial state, and life-cycle behaviour of the particle.
It is enough to customize your CC3PointParticle class. You do not typically need to create a customized subclass of CC3PointParticleEmitter itself.
Particles are emitted automatically by the CC3PointParticleEmitter. The emitter will automatically invoke the initializeParticle callback method on each particle as it is emitted.
Be aware that, in the interests of performance and memory conservation, expired particles may be cached and reused, and particle emission may not always involve instantiating a new instance of your CC3PointParticle class.
With this in mind, you should not depend on initFromEmitter: method being invoked during particle emission. All code that establishes the initial emitted state of a particle should be included in the initializeParticle method.
During the life-cycle of a particle, the emitter will automatically periodically update the particle by invoking the update: callback method. This method invocation includes the time interval since the last update, so that the particle can emulate realistic real-time behaviour.
From within the initializeParticle and update: methods, the parrticle has access to the emitter (and the node hierarchy and world it sits in) through the emitter property. In addition, the particle can read and manipulate drawable content through the location, normal, color4F/color4B, and size properties. For example, a particle may change its location by changing the location property, or its color by changing the color4F property.
The normal property indicates the vertex normal that the particle uses to interact with light sources. This property is automatically and dynamically adjusted by the emitter, based on the particle's orientation with respect to the camera. Unless you have specific reason to do so, and know what you are doing, you should leave the value of this property alone.
The value of the location property always has meaning, but the normal, color4B, color4F and size properties are only active if the emitter was configured so that particles will have normal, color and size content. If the emitter was not configured for any of these particle content, then the reading the resulting property will simply return zeros, and setting the property will have no effect. It is, however, safe to read and write these properties, they just won't have any effect. So, you can safely write a CC3PointParticle subclass that blindly manipulates its own color, and it simply won't have any effect when used with an emitter that has been configured not to include color content in the particles.
Beyond these basic drawable content properties, when you create a subclass of CC3PointParticle, you should add any other content that is needed to determine the behaviour of your particle. For example, you might include a velocity property for particle that are following a path (or even a path object to define that path more explicitly), and a timeToLive property, for particle that have a finite lifespan.
It is up to the particle to determine when it expires. Some particles may never expire. For those that do, you might typically define a lifeSpan or timeToLive property within the particle that the particle decrements in the update: method.
Once the particle has detemined that it has expired, in the update: method, you can set the isAlive property of the particle to NO. When the update: method 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 update: 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.
Member Function Documentation
| - (NSString*) fullDescription |
Returns a string containing a more complete description of this particle.
| - (id) initFromEmitter: | (CC3PointParticleEmitter *) | anEmitter |
Initializes this instance for the specified emitter.
When overriding this method, be aware that, in the interests of performance and memory conservation, expired particles can and will be cached and reused, and particle emission may not always involve instantiating a new instance of your CC3PointParticle class.
With this in mind, you should not depend on this method being invoked during particle emission. All code that establishes the initial emitted state of a particle should be included in the initializeParticle method.
| - (void) initializeParticle |
This template callback method is invoked automatically when this particle is emitted.
You should override this method to establish the initial state of the particle.
During execution of this method, you can access and set the initial values of the location, normal, color and size properties. The emitter property can be used to access further information in the emitter or other aspects of the 3D world.
The isAlive property is set to YES prior to the invocation of this method. You can set the isAlive property to NO in this method 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. You should not rely on any state set in the initFromEmitter: method, (with the exception of the emitter property).
This implementation does nothing. You do not need to invoke this superclass implementation from your overridden method implementation.
| + (id) particleFromEmitter: | (CC3PointParticleEmitter *) | anEmitter |
Allocates and initializes an autoreleased instance for the specified emitter.
| - (void) update: | (ccTime) | dt |
This template callback method is invoked automatically whenever the emitter is updated during a scheduled 3D world update.
You should override this method to control the behaviour of the particle during its lifetime.
During execution of this method, you can access and set the values of the location, normal, color and size properties. The emitter property can be used to access further information in the emitter or other aspects of the 3D world.
It is up to the particle to determine when it expires. Some particles may never expire. For those that do, you might typically define a lifeSpan or timeToLive property within the particle that the particle decrements in this method.
Once the particle has detemined that it has expired, in this method, you can set the isAlive property of the particle to NO. When this method 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 update: method invocations.
This implementation does nothing. You do not need to invoke this superclass implementation from your overridden method implementation.
Property Documentation
- (ccColor4B) color4B [read, write, assign] |
If this particle has individual color content, (which can be checked with the hasColor property), this property indicates the color in which this particle will appear.
If this particle has individual color content, you can set this property at any time to define the color of the particle.
If this particle does not have individual color content, this property will always return the value of the diffuseColor property of the emitter. In this condition, it is safe to set this property, but changes will have no effect.
The initial value of this property, set prior to the invocation of the initializeParticle method, the value of the diffuseColor property of the emitter.
- (ccColor4F) color4F [read, write, assign] |
If this particle has individual color content, (which can be checked with the hasColor property), this property indicates the color in which this particle will appear.
If this particle has individual color content, you can set this property at any time to define the color of the particle.
If this particle does not have individual color content, this property will always return the value of the diffuseColor property of the emitter. In this condition, it is safe to set this property, but changes will have no effect.
The initial value of this property, set prior to the invocation of the initializeParticle method, the value of the diffuseColor property of the emitter.
- (CC3PointParticleEmitter *) emitter [read, assign] |
The emitter that emitted this particle.
- (BOOL) hasColor [read, assign] |
Indicates whether this particle has individual color content.
This is determined by the configuration of the emitter. Within an emitter, either all particles have this content, or none do.
When this property returns YES, each particle can be set to a different color. When this property returns NO, all particles will have the color specified by the diffuseColor property of the emitter.
- (BOOL) hasNormal [read, assign] |
Indicates whether this particle has vertex normal content.
This is determined by the configuration of the emitter. Within an emitter, either all particles have this content, or none do.
When this property returns YES, each particle will have a normal vector and will interact with light sources. When this property returns NO, each particle will ignore lighting conditions.
- (BOOL) hasSize [read, assign] |
Indicates whether this particle has individual size content.
This is determined by the configuration of the emitter. Within an emitter, either all particles have this content, or none do.
When this property returns YES, each particle can be set to a different size. When this property returns NO, all particles will have the size specified by the particleSize property of the emitter.
- (GLuint) index [read, assign] |
The index of this particle within the collection of particles managed by the emitter.
You should not assume that this property will be consistent during the lifetime of the particle. It can and will change spontaneously as other particles expire and the emitter manages the sequence of particles.
At any time, this value is unique across all current living particles managed by the emitter.
- (BOOL) isAlive [read, write, assign] |
Indicates whether this particle is alive or not.
When a particle is emitted, 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 update: method to indicate that this particle has expired. When the update: method 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 update: 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.
- (CC3Vector) location [read, write, assign] |
The location of this particle in the local coordinate system of the emitter.
You can set this particle in the initializeParticle and update: methods to move the particle around.
The initial value of this property, set prior to the invocation of the initializeParticle method, is kCC3VectorZero.
- (CC3Vector) normal [read, write, assign] |
If this particle has vertex normal content, (which can be checked with the hasNormal property), this property indicates the vertex normal that the particle uses to interact with light sources.
This property is automatically and dynamically adjusted by the emitter, based on the particle's orientation with respect to the camera. Unless you have specific reason to change this property, and know what you are doing, you should leave the value of this property alone.
If this particle does not have vertex normal content, this property will always return kCC3VectorZero. In this condition, it is safe to set this property, but changes will have no effect.
The initial value of this property, set prior to the invocation of the initializeParticle method, is kCC3VectorZero.
- (GLfloat) size [read, write, assign] |
If this particle has individual size content, (which can be checked with the hasSize property), this property indicates the size at which this particle will appear.
If this particle has individual size content, you can set this property at any time to define the size of the particle.
If this particle does not have individual size content, this property will always return the value of the particleSize property of the emitter. In this condition, it is safe to set this property, but changes will have no effect.
The initial value of this property, set prior to the invocation of the initializeParticle method, is the value of the particleSize property of the emitter.
The documentation for this class was generated from the following file:
