Public Member Functions | Protected Attributes | Properties

CC3MeshParticle Class Reference

CC3MeshParticle is a standard base implementation of the CC3MeshParticleProtocol. More...

#import <CC3MeshParticles.h>

Inheritance diagram for CC3MeshParticle:
Inheritance graph
[legend]
Collaboration diagram for CC3MeshParticle:
Collaboration graph
[legend]

List of all members.

Public Member Functions

(void) - markColorDirty
(void) - markTransformDirty
(void) - rotateBy:
(void) - rotateByAngle:aroundAxis:
(void) - rotateByQuaternion:
(void) - setTextureRectangle:forTextureUnit:
(void) - setVertexColor4B:at:
(void) - setVertexColor4F:at:
(void) - setVertexHomogeneousLocation:at:
(void) - setVertexIndex:at:
(void) - setVertexLocation:at:
(void) - setVertexNormal:at:
(void) - setVertexTexCoord2F:at:
(void) - setVertexTexCoord2F:forTextureUnit:at:
(void) - transformVertexColors
(void) - transformVertices
(void) - translateBy:
(ccColor4B) - vertexColor4BAt:
(ccColor4F) - vertexColor4FAt:
(CC3Vector4- vertexHomogeneousLocationAt:
(GLuint) - vertexIndexAt:
(CC3Vector- vertexLocationAt:
(CC3Vector- vertexNormalAt:
(ccTex2F) - vertexTexCoord2FAt:
(ccTex2F) - vertexTexCoord2FForTextureUnit:at:

Protected Attributes

GLuint firstVertexIndexOffset
GLuint firstVertexOffset
CC3VertexArrayMeshtemplateMesh

Properties

CC3MeshParticleEmitteremitter
CC3Vector forwardDirection
BOOL hasVertexColors
BOOL hasVertexLocations
BOOL hasVertexNormals
BOOL hasVertexTextureCoordinates
BOOL isColorDirty
BOOL isTransformDirty
CC3Vector location
CC3Quaternion quaternion
CC3Vector referenceUpDirection
CC3Vector rightDirection
CC3Vector rotation
GLfloat rotationAngle
CC3Vector rotationAxis
CC3Rotatorrotator
CGRect textureRectangle
CC3Vector upDirection

Detailed Description

CC3MeshParticle is a standard base implementation of the CC3MeshParticleProtocol.

CC3MeshParticle brings many of the capabilities of a CC3MeshNode to particles.

Like mesh nodes, particles of this type can be flexibly moved, rotated and scaled, and the vertices will be automatically transformed into the vertex arrays of the emitter.

Although all particles in a single emitter must be covered by the same material and texture, particles of this type may be assigned a textureRectangle, allowing each particle to use a separate section of the emitter's texture, effectively texturing each particle separately.

The individual vertices of each particle can be manipulated using the same family of vertex access methods available to mesh nodes.


Member Function Documentation

- (void) markColorDirty

Indicates that the color of the particle has been changed, and that the vertices need to be transformed accordingly prior to the next drawing frame.

This method is invoked automatically whenever any of the color properties (color, opacity, color4f, color4B) has been changed. Usually, the application never needs to invoke this method directly.

- (void) markTransformDirty

Indicates that the particle has been transformed in some way, and that the vertices need to be transformed accordingly prior to the next drawing frame.

This method is invoked automatically whenever any of the transform properties of this particle (location, rotation (including any type of rotation), or scale) has been changed. Usually, the application never needs to invoke this method directly.

- (void) rotateBy: (CC3Vector aRotation

Rotates this particle from its current rotational state by the specified Euler angles in degrees.

The incoming Euler angles specify the amount of change in rotation, not the final rotational state.

- (void) rotateByAngle: (GLfloat)  anAngle
aroundAxis: (CC3Vector anAxis 

Rotates this particle from its current rotational state by rotating around the specified axis by the specified angle in degrees.

The incoming axis and angle specify the amount of change in rotation, not the final rotational state.

Thanks to cocos3d user nt901 for contributing to the development of this feature

- (void) rotateByQuaternion: (CC3Quaternion aQuaternion

Rotates this particle from its current rotational state by the specified quaternion.

The incoming quaternion specifies the amount of change in rotation, not the final rotational state.

- (void) setTextureRectangle: (CGRect)  aRect
forTextureUnit: (GLuint)  texUnit 

Sets the texture rectangle of this particle, for the specified texture unit.

See the notes for the textureRectangle property of this class, for an explanation of the use of this property.

- (void) setVertexColor4B: (ccColor4B)  aColor
at: (GLuint)  index 

Sets the color element at the specified index in the vertex content to the specified value.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (void) setVertexColor4F: (ccColor4F)  aColor
at: (GLuint)  index 

Sets the color element at the specified index in the vertex content to the specified value.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (void) setVertexHomogeneousLocation: (CC3Vector4 aLocation
at: (GLuint)  index 

Sets the location element at the specified index in the underlying vertex content to the specified four-dimensional location in the 4D homogeneous coordinate space.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

This implementation takes into consideration the dimensionality of the underlying vertex content. If the dimensionality is 3, the W component of the specified vector will be ignored. If the dimensionality is 2, both the W and Z components of the specified vector will be ignored.

- (void) setVertexIndex: (GLuint)  vertexIndex
at: (GLuint)  index 

Sets the index element at the specified index in the vertex content to the specified value.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. Similarly, the vertexIndex is relative to the content of this particle, not the entire underlying mesh.

- (void) setVertexLocation: (CC3Vector aLocation
at: (GLuint)  index 

Sets the location element at the specified index in the vertex content to the specified value.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

This implementation takes into consideration the dimensionality of the underlying vertex content. If the dimensionality is 2, the Z component of the specified vector will be ignored. If the dimensionality is 4, the specified vector will be converted to a 4D vector, with the W component set to one, before storing.

- (void) setVertexNormal: (CC3Vector aNormal
at: (GLuint)  index 

Sets the normal element at the specified index in the vertex content to the specified value.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (void) setVertexTexCoord2F: (ccTex2F)  aTex2F
at: (GLuint)  index 

Sets the texture coordinate element at the specified index in the vertex content, at the commonly used texture unit zero, to the specified texture coordinate value.

This is a convenience method that delegates to the setVertexTexCoord2F:forTextureUnit:at: method, passing in zero for the texture unit index.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (void) setVertexTexCoord2F: (ccTex2F)  aTex2F
forTextureUnit: (GLuint)  texUnit
at: (GLuint)  index 

Sets the texture coordinate element at the specified index in the vertex content, at the specified texture unit index, to the specified texture coordinate value.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (void) transformVertexColors

Template method that transforms the color of each of the vertices of this particle.

This implementation checks the isColorDirty property to determine if this particle has been colored since the previous transform. If so, this method traverses the vertices in this particle, copying the color into each vertex.

This method is invoked automatically from the transformVertices method of any particle whose color has been updated by setting one of the color properties (color, opacity, color4f, color4B).

- (void) transformVertices

Transforms the vertices of this particle.

For an emitter, all particles are submitted to the GL engine in a single draw call. This means that all vertices for all particles from that emitter will use the same GL transform matrix, which is defined by the transformation properties of the emitter.

To allow each mesh particle to be transformed independently, the vertices for each particle must be transformed in memory by the CPU.

This method is invoked automatically on each particle when the emitter is transformed.

This implementation checks the isTransformDirty property to see if this particle has been moved, rotated, or scaled since the previous transform. If so, this method traverses the vertices in this particle, transforming each vertex according to the transformation properties (location, rotation and scale) of this particle.

If neither rotation or scaling has been applied to this particle, this implementation performs an optimized translation of the vertex locations only. If rotation has been applied to this particle as well, then the locations of the vertices are generally transformed using the location, rotation and scaling transformations that have been applied to this particle, and the normals of the vertices are rotated using the rotation applied to this particle.

After the vertex locations have been transformed, this method also invokes the transformVertexColors method to update the colors of the individual vertices of this particle if individual particle and vertex colors are supported by the emitter.

If your particles have specialized transformation requirements, or can be optimized in some other way, you can override this method to transform the vertices of this particle differently. You should check the value of the isTransformDirty property before doing any work, and you should set the value of that property to NO after the vertices have been transformed.

This method is invoked automatically on any particle that has been updated, when the emitter is transformed. Usually the application never needs to invoke this method directly.

Reimplemented from <CC3MeshParticleProtocol>.

- (void) translateBy: (CC3Vector aVector

Translates the location of this property by the specified vector.

The incoming vector specify the amount of change in location, not the final location.

- (ccColor4B) vertexColor4BAt: (GLuint)  index

Returns the color element at the specified index from the vertex content.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (ccColor4F) vertexColor4FAt: (GLuint)  index

Returns the color element at the specified index from the vertex content.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (CC3Vector4) vertexHomogeneousLocationAt: (GLuint)  index

Returns the location element at the specified index in the underlying vertex content, as a four-dimensional location in the 4D homogeneous coordinate space.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

This implementation takes into consideration the dimensionality of the underlying vertex content. If the dimensionality is 3, the returned vector will contain one in the W component. If the dimensionality is 2, the returned vector will contain zero in the Z component and one in the W component.

- (GLuint) vertexIndexAt: (GLuint)  index

Returns the index element at the specified index from the vertex content.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh.

Similarly, the returned vertex index is relative to the content of this particle, not the entire underlying mesh.

- (CC3Vector) vertexLocationAt: (GLuint)  index

Returns the location element at the specified index from the vertex content.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

This implementation takes into consideration the dimensionality of the underlying vertex content. If the dimensionality is 2, the returned vector will contain zero in the Z component.

- (CC3Vector) vertexNormalAt: (GLuint)  index

Returns the normal element at the specified index from the vertex content.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (ccTex2F) vertexTexCoord2FAt: (GLuint)  index

Returns the texture coordinate element at the specified index from the vertex content at the commonly used texture unit zero.

This is a convenience method that is equivalent to invoking the vertexTexCoord2FForTextureUnit:at: method, with zero as the texture unit index.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.

- (ccTex2F) vertexTexCoord2FForTextureUnit: (GLuint)  texUnit
at: (GLuint)  index 

Returns the texture coordinate element at the specified index from the vertex content at the specified texture unit index.

The index refers to vertices, not bytes, and is relative to the content of this particle, not the entire underlying mesh. The implementation takes into consideration whether the vertex content is interleaved to access the correct vertex data component.


Member Data Documentation

- (GLuint) firstVertexIndexOffset [protected]

Returns the index offset, in the underlying mesh vertex index array, of the first vertex index of this particle.

This offset can be used to access the vertex indices directly within the underlying mesh vertex index array.

If the underlying mesh is not using indexed vertices, this property will be set to the same value as the firstVertexOffset property.

Reimplemented from <CC3MeshParticleProtocol>.

- (GLuint) firstVertexOffset [protected]

Returns the index offset, in the underlying mesh vertex arrays, of the first vertex of this particle.

This offset can be used to access content directly within the underlying mesh vertex arrays.

Reimplemented from <CC3MeshParticleProtocol>.

- (CC3VertexArrayMesh*) templateMesh [protected]

The CC3VertexArrayMesh used as a template for the mesh of this particle.

This particle uses the vertices of this mesh as a starting point. The vertices for the particle are copied into the underlying common mesh that supports all particles emitted by a single emitter. The particle can then manipulate its own copy of the vertices, and can have its own locations, rotations, vertex colors and texture coordinates.

For particles created outside the emitter, and added to the emitter with the emitParticle: method, this property can be set directly by the application to define the mesh of this particle. For particles created within the emitter, and emitted automatically, or via the emitParticle method, this property will be assigned by the emitter, usually from a pre-defined template mesh.

Reimplemented from <CC3MeshParticleProtocol>.


Property Documentation

- (CC3MeshParticleEmitter*) emitter [read, write, assign]

The emitter that emitted this particle.

For CC3MeshParticle, the emitter must be of type CC3MeshParticleEmitter.

Implements CC3ParticleBase.

- (CC3Vector) forwardDirection [read, write, assign]

The direction in which this particle is pointing.

The value of this property is specified in the local coordinate system of this particle.

The initial value of this property is kCC3VectorUnitZPositive, pointing down the positive Z-axis in the local coordinate system of this particle. When this particle is rotated, the original positive-Z axis of the node's local coordinate system will point in this direction.

Pointing the particle in a particular direction does not fully define its rotation in 3D space, because the particle can be oriented in any rotation around the axis along the forwardDirection vector (think of pointing a camera at a scene, and then rotating the camera along the axis of its lens, landscape towards portrait).

The orientation around this axis is defined by specifying an additional 'up' direction, which fixes the rotation around the forwardDirection by specifying which direction is considered to be 'up'. The 'up' direction is specified by setting the referenceUpDirection property, which is independent of the tilt of the local axes, and does not need to be perpendicular to the forwardDirection.

The value returned for this property is of unit length. When setting this property, the value will be normalized to be a unit vector.

A valid direction vector is required. Attempting to set this property to the zero vector (kCC3VectorZero) will raise an assertion error.

- (BOOL) hasVertexColors [read, assign]

Indicates whether this particle contains vertex color content.

- (BOOL) hasVertexLocations [read, assign]

Indicates whether this particle contains vertex location content.

- (BOOL) hasVertexNormals [read, assign]

Indicates whether this particle contains vertex normal content.

- (BOOL) hasVertexTextureCoordinates [read, assign]

Indicates whether this particle contains vertex texture coordinate content.

- (BOOL) isColorDirty [read, assign]

Indicates whether the color of this particle has been changed, and so the vertices of this particle need to be updated with the new color.

This property is automatically set to YES when any of the color properties (color, opacity, color4f, color4B) has been changed, and is reset to NO once the particle vertices have been transformed.

Transformation of the vertices occurs automatically when the emitter is transformed.

- (BOOL) isTransformDirty [read, assign]

Indicates whether any of the transform properties, location, rotation, or scale have been changed, and so the vertices of this particle need to be transformed.

This property is automatically set to YES when one of those properties have been changed, and is reset to NO once the particle vertices have been transformed.

Transformation of the vertices occurs automatically when the emitter is transformed.

- (CC3Vector) location [read, write, assign]

The location of this particle in the local coordinate system of the emitter.

You can set this property in the initializeParticle and updateBeforeTransform: methods to move the particle around.

The initial value of this property, set prior to the invocation of the initializeParticle method, is kCC3VectorZero.

Implements CC3ParticleBase.

- (CC3Quaternion) quaternion [read, write, assign]

The rotation of the particle in 3D space, relative to the parent of this node, expressed as a quaternion.

Rotational transformation can also be specified using the rotation property (Euler angles), or the rotationAxis and rotationAngle properties. Subsequently, this property can be read to return the corresponding quaternion.

- (CC3Vector) referenceUpDirection [read, write, assign]

The direction that is considered to be 'up' when rotating to face in a particular direction, by using one of the directional properties forwardDirection, target, or targetLocation.

As explained in the note for the forwardDirection, specifying a forwardDirection alone is not sufficient to determine the rotation of a particle in 3D space. This property indicates which direction should be considered 'up' when orienting the rotation of the particle to face a direction, target, or target location.

The interpretation of whether the value of this property is specified in local or global coordinates depends on how the direction of pointing is being specified.

When using the forwardDirection property, the value of this property is taken to be specified in the local coordinate system. When using either the target or targetLocation properties, the interpretation of whether the value of this property is specified in the local or global coordinate system is determined by the value of the targettingConstraint property.

The initial value of this property is kCC3VectorUnitYPositive, pointing parallel to the positive Y-axis, and in most cases, this property can be left with that value.

The value returned is of unit length. When setting this property, the value will be normalized to be a unit vector.

When setting this property, a valid direction vector is required. Attempting to set this property to the zero vector (kCC3VectorZero) will raise an assertion error.

- (CC3Vector) rightDirection [read, assign]

The direction in the particle's coordinate system that would be considered to be "off to the right" when looking out from the particle, along the forwardDirection and with the upDirection defined.

The value returned by this property is in the local coordinate system of this particle.

The value returned is of unit length.

- (CC3Vector) rotation [read, write, assign]

The rotational orientation of the particle in 3D space, relative to the emitter.

The global rotation of the particle is therefore a combination of the global rotation of the emitter and the value of this rotation property. This value contains three Euler angles, defining a rotation of this nodearound the X, Y and Z axes. Each angle is specified in degrees.

Rotation is performed in Y-X-Z order, which is the OpenGL default. Depending on the nature of the object you are trying to control, you can think of this order as yaw, then pitch, then roll, or heading, then inclination, then tilt,

When setting this value, each component is converted to modulo +/-360 degrees.

Rotational transformation can also be specified using the rotationAxis and rotationAngle properties, or the quaternion property. Subsequently, this property can be read to return the corresponding Euler angles.

- (GLfloat) rotationAngle [read, write, assign]

The angular rotation around the axis specified in the rotationAxis property.

When setting this value, it is converted to modulo +/-360 degrees. When reading this value after making changes using rotateByAngle:aroundAxis:, or using another rotation property, the value of this property will be clamped to +/-180 degrees.

For example, if current rotation is 170 degrees around the rotationAxis, invoking the rotateByAngle:aroundAxis: method using the same rotation axis and 20 degrees, reading this property will return -170 degrees, not 190 degrees.

Rotational transformation can also be specified using the rotation property (Euler angles), or the quaternion property. Subsequently, this property can be read to return the corresponding angle of rotation.

- (CC3Vector) rotationAxis [read, write, assign]

The axis of rotation of the particle in 3D space, relative to the emitter, expressed as a directional vector.

This axis can be used in conjunction with the rotationAngle property to describe the rotation as a single angular rotation around an arbitrary axis.

Under the identity rotation (no rotation), the rotationAngle is zero and the rotationAxis is undefined. Under that condition, this property will return the zero vector kCC3VectorZero.

Rotational transformation can also be specified using the rotation property (Euler angles), or the quaternion property. Subsequently, this property can be read to return the corresponding axis of rotation.

- (CC3Rotator *) rotator [read, write, retain]

Returns the rotator that manages the local rotation of this particle.

CC3Rotator is the base class of a class cluster, of which different subclasses perform different types of rotation. The type of object returned by this property may change, depending on what rotational changes have been made to this particle.

For example, if no rotation is applied to this particle, this property will return a base CC3Rotator. After the rotation of this node has been changed, this property will return a CC3MutableRotator, and if directional properties, such as forwardDirection have been accessed or changed, this property will return a CC3DirectionalRotator. The creation of the type of rotator required to support the various rotations is automatic.

- (CGRect) textureRectangle [read, write, assign]

Sets the texture rectangle of this particle, for all texture units.

This property facilitates the use of sprite-sheets, where the mesh is covered by a small fraction of a larger texture.

Setting this property adjusts the texture coordinates of this particle so that they map to the specified texture rectangle within the bounds of the texture.

The texture rectangle applied here takes into consideration the textureRectangle property of the particleTemplateMesh, and the mapSize of the texture itself.

See the notes for this same property on CC3MeshNode and CC3Mesh for more information about applying texture rectangles to meshes.

Once applied, the value of this property is not retained, and reading this property returns a null rectangle. Subclasses may override to cache the value of this property.

- (CC3Vector) upDirection [read, assign]

The direction, in the particle's coordinate system, that is considered to be 'up'.

This corresponds to the referenceUpDirection, after it has been transformed by the rotations of this particle. For example, rotating the particle upwards to point towards an elevated target will move the upDirection of this particle away from the referenceUpDirection.

The value returned by this property is in the local coordinate system of this particle.

The value returned is of unit length.


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