 |
#include <ParticleEmitter.h>
Classes | |
| class | Particle |
Public Types | |
| enum | BlendMode { BLEND_NONE, BLEND_ALPHA, BLEND_ADDITIVE, BLEND_MULTIPLIED } |
Public Member Functions | |
| void | setTexture (const char *texturePath, BlendMode blendMode) |
| void | setTexture (Texture *texture, BlendMode blendMode) |
| Texture * | getTexture () const |
| void | setParticleCountMax (unsigned int max) |
| unsigned int | getParticleCountMax () const |
| void | setEmissionRate (unsigned int rate) |
| unsigned int | getEmissionRate () const |
| void | start () |
| void | stop () |
| bool | isStarted () const |
| bool | isActive () const |
| void | emitOnce (unsigned int particleCount) |
| unsigned int | getParticlesCount () const |
| void | setEllipsoid (bool ellipsoid) |
| bool | isEllipsoid () const |
| void | setSize (float startMin, float startMax, float endMin, float endMax) |
| float | getSizeStartMin () const |
| float | getSizeStartMax () const |
| float | getSizeEndMin () const |
| float | getSizeEndMax () const |
| void | setColor (const Vector4 &start, const Vector4 &startVariance, const Vector4 &end, const Vector4 &endVariance) |
| const Vector4 & | getColorStart () const |
| const Vector4 & | getColorStartVariance () const |
| const Vector4 & | getColorEnd () const |
| const Vector4 & | getColorEndVariance () const |
| void | setEnergy (long energyMin, long energyMax) |
| long | getEnergyMin () const |
| long | getEnergyMax () const |
| void | setPosition (const Vector3 &position, const Vector3 &positionVariance) |
| const Vector3 & | getPosition () const |
| const Vector3 & | getPositionVariance () const |
| void | setVelocity (const Vector3 &velocity, const Vector3 &velocityVariance) |
| const Vector3 & | getVelocity () const |
| const Vector3 & | getVelocityVariance () const |
| const Vector3 & | getAcceleration () const |
| void | setAcceleration (const Vector3 &acceleration, const Vector3 &accelerationVariance) |
| const Vector3 & | getAccelerationVariance () const |
| void | setRotationPerParticle (float speedMin, float speedMax) |
| float | getRotationPerParticleSpeedMin () const |
| float | getRotationPerParticleSpeedMax () const |
| void | setRotation (float speedMin, float speedMax, const Vector3 &axis, const Vector3 &axisVariance) |
| float | getRotationSpeedMin () const |
| float | getRotationSpeedMax () const |
| const Vector3 & | getRotationAxis () const |
| const Vector3 & | getRotationAxisVariance () const |
| void | setSpriteAnimated (bool animated) |
| bool | isSpriteAnimated () const |
| void | setSpriteLooped (bool looped) |
| bool | isSpriteLooped () const |
| void | setSpriteFrameRandomOffset (int maxOffset) |
| int | getSpriteFrameRandomOffset () const |
| void | setSpriteFrameDuration (long duration) |
| long | getSpriteFrameDuration () const |
| unsigned int | getSpriteWidth () const |
| unsigned int | getSpriteHeight () const |
| void | setSpriteTexCoords (unsigned int frameCount, float *texCoords) |
| void | setSpriteFrameCoords (unsigned int frameCount, Rectangle *frameCoords) |
| void | setSpriteFrameCoords (unsigned int frameCount, int width, int height) |
| unsigned int | getSpriteFrameCount () const |
| void | setOrbit (bool orbitPosition, bool orbitVelocity, bool orbitAcceleration) |
| bool | getOrbitPosition () const |
| bool | getOrbitVelocity () const |
| bool | getOrbitAcceleration () const |
| void | setBlendMode (BlendMode blendMode) |
| BlendMode | getBlendMode () const |
| void | update (float elapsedTime) |
| unsigned int | draw (bool wireframe=false) |
Static Public Member Functions | |
| static ParticleEmitter * | create (const char *url) |
| static ParticleEmitter * | create (Properties *properties) |
| static ParticleEmitter * | create (const char *texturePath, BlendMode blendMode, unsigned int particleCountMax) |
Defines a particle emitter that can be made to simulate and render a particle system.
Once created, the emitter can be set on a node in order to follow an object or be placed within a scene.
A ParticleEmitter has a texture and a maximum number of particles that can be alive at once, both of which are set when the ParticleEmitter is created and cannot be changed from then on. Particles are rendered as camera-facing billboards using the emitter's texture. The ParticleEmitter's texture properties determine whether the texture is treated as a single image, a texture atlas or an animated sprite.
A ParticleEmitter also has a number of properties that determine values assigned to individual particles it emits. Scalar properties such as particle begin- and end-size are assigned within a minimum and maximum value; vector properties are assigned within the domain defined by a base vector and a variance vector as follows: The variance vector is multiplied by a random scalar between 1 and -1, and the base vector is added to this result. This allows a ParticleEmitter to be created which emits particles with properties that are randomized, yet fit within a well-defined range. To make a property deterministic, simply set the minimum to the same value as the maximum for that property or set its variance to the zero vector.
Begin-Size:
The size of a newly emitted particle.
End-Size:
The size of a particle at the end of its lifetime. A particle's size will interpolate linearly between its begin-size and end-size over its lifetime.
Energy:
The length of time a particle will remain alive for.
RotationSpeedPerParticle:
The speed and direction a particle will spin. Since particles are rendered as billboards, no axis of rotation can be specified per particle. Each particles rotates around their center points, around the z-axis in screen space.
RotationSpeed:
The speed a particle will spin around its RotationAxis in world space. (See RotationAxis under "Vector properties" below.)
Initial Position:
The position of a new particle at the moment it is emitted, relative to the node its ParticleEmitter is set on. This property is unique in that the initial positions of new particles can be restricted to fit within an ellipsoidal domain; see setEllipsoid().
Initial Velocity:
The velocity of a new particle at the moment it is emitted. This property is measured in world coordinates per second and modifies a particle's current position each time ParticleEmitter::update() is called.
Acceleration:
The particle's change in velocity, measured in world coordinates per second. This property modifies a particle's current position each time ParticleEmitter::update() is called.
Color:
The color of a particle at the end of its lifetime. A particle's color will interpolate linearly between its begin-color and end-color over its lifetime.
RotationAxis:
An axis in world space around which all particles will spin, allowing for tornado and spiral effects.
The vector properties Initial Position, Initial Velocity and Acceleration can be set to orbit around the origin of a node a ParticleEmitter is set on by that node's rotation matrix. This allows the rotation of a node, and not just its position, to affect these properties of newly emitted particles. An example of where this would be useful would be a water-fountain emitter attached to the nozzle of a hose. The initial position and initial velocity would be set to orbit around the node's origin so that the water would always spray out in the direction the nozzle was facing. However, acceleration would not be set to orbit the node's origin in order for gravity to continue to act in the same direction on water particles, no matter what direction they were originally aimed.
Particles are rendered as screen-facing billboards -- that is, the ParticleEmitter's texture is used to render particles as images that always face the camera. For the simplest case, where the entire texture is used for every particle, the default texture settings can be used. However, a ParticleEmitter can also be configured to select one of several frames at random for each particle, or to render each particle as a sprite that animates through the frames over the course of its lifetime.
Frame Count:
The number of individual images / frames contained in the texture.
Texture Coordinates:
The coordinates within the texture used to render a specific frame. Using a texture that places the frames together, without padding, in left-to-right top-to-bottom order is recommended, as there is a utility method for generating the texture coordinates for such a texture atlas / sprite-map. See setSpriteFrameCoords().
Sprite Animating:
Set this to enable sprite animation.
Sprite Looped:
If sprites are set to loop, each frame will last for the emitter's frameDuration. If sprites are set not to loop, the animation will be timed so that the last frame finishes just as a particle dies. This setting has no effect if the sprite is not animating.
Sprite Random Offset:
New particles are created with one of the sprite frames in the emitter's texture. If a maximum offset is set, a random frame from 0 to maxOffset will be selected. If sprite animation is disabled and this offset is set to Frame Count, each particle will use one of the sprite frames for its entire lifetime.
Blend Mode:
Sets the blend mode used by this particle emitter. The given blend factors will be set before rendering the particle system and then will be reset to their original values. Accepts the same symbolic constants as glBlendFunc().
Defines the types of blend modes
| static ParticleEmitter* gameplay::ParticleEmitter::create | ( | const char * | url | ) | [static] |
Creates a particle emitter using the data from the Properties object defined at the specified URL, where the URL is of the format "<file-path>.<extension>#<namespace-id>/<namespace-id>/.../<namespace-id>" (and "#<namespace-id>/<namespace-id>/.../<namespace-id>" is optional).
| url | The URL pointing to the Properties object defining the particle emitter. |
| static ParticleEmitter* gameplay::ParticleEmitter::create | ( | Properties * | properties | ) | [static] |
Creates a particle emitter from the specified properties object.
| properties | The properties object defining the particle emitter (must have namespace equal to 'particle'). |
NULL if the particle emitter failed to load. | static ParticleEmitter* gameplay::ParticleEmitter::create | ( | const char * | texturePath, |
| BlendMode | blendMode, | ||
| unsigned int | particleCountMax | ||
| ) | [static] |
Creates an uninitialized ParticleEmitter.
| texturePath | A path to the image to use as this ParticleEmitter's texture. |
| blendMode | The blend mode to be used for the particles emitted. |
| particleCountMax | The maximum number of particles that can be alive at one time in this ParticleEmitter's system. |
| unsigned int gameplay::ParticleEmitter::draw | ( | bool | wireframe = false | ) | [virtual] |
| void gameplay::ParticleEmitter::emitOnce | ( | unsigned int | particleCount | ) |
Generates an arbitrary number of particles all at once. Each newly emitted particle has its properties assigned within the ranges defined by its ParticleEmitter.
Note that the maximum number of particles that can be alive at once in a particle system is defined when a ParticleEmitter is created and cannot be changed. A call to emit() cannot cause the particle system to exceed this maximum, so fewer or zero particles will be emitted if the maximum is or has been reached.
| particleCount | The number of particles to emit immediately. |
| const Vector3& gameplay::ParticleEmitter::getAcceleration | ( | ) | const |
Gets the base acceleration vector of particles.
| const Vector3& gameplay::ParticleEmitter::getAccelerationVariance | ( | ) | const |
Gets the variance of acceleration of particles.
Gets the current texture blend mode for this particle emitter.
| const Vector4& gameplay::ParticleEmitter::getColorEnd | ( | ) | const |
Gets the base end color of emitted particles.
| const Vector4& gameplay::ParticleEmitter::getColorEndVariance | ( | ) | const |
Gets the variance of end color of emitted particles.
| const Vector4& gameplay::ParticleEmitter::getColorStart | ( | ) | const |
Gets the base start color of emitted particles.
| const Vector4& gameplay::ParticleEmitter::getColorStartVariance | ( | ) | const |
Gets the variance of start color of emitted particles.
| unsigned int gameplay::ParticleEmitter::getEmissionRate | ( | ) | const |
Gets the emission rate, measured in particles per second.
| long gameplay::ParticleEmitter::getEnergyMax | ( | ) | const |
Gets the maximum lifetime of each particle, measured in milliseconds.
| long gameplay::ParticleEmitter::getEnergyMin | ( | ) | const |
Gets the minimum lifetime of each particle, measured in milliseconds.
| bool gameplay::ParticleEmitter::getOrbitAcceleration | ( | ) | const |
Whether new particle accelerations are rotated by the node's rotation matrix.
| bool gameplay::ParticleEmitter::getOrbitPosition | ( | ) | const |
Whether new particle positions are rotated by the node's rotation matrix.
| bool gameplay::ParticleEmitter::getOrbitVelocity | ( | ) | const |
Whether new particle velocities are rotated by the node's rotation matrix.
| unsigned int gameplay::ParticleEmitter::getParticleCountMax | ( | ) | const |
Returns the maximum number of particles that can be emitted.
| unsigned int gameplay::ParticleEmitter::getParticlesCount | ( | ) | const |
Gets the current number of particles.
| const Vector3& gameplay::ParticleEmitter::getPosition | ( | ) | const |
Gets the position of new particles, relative to the emitter's transform.
| const Vector3& gameplay::ParticleEmitter::getPositionVariance | ( | ) | const |
Gets the position variance of new particles.
| const Vector3& gameplay::ParticleEmitter::getRotationAxis | ( | ) | const |
Gets the base rotation axis of emitted particles.
| const Vector3& gameplay::ParticleEmitter::getRotationAxisVariance | ( | ) | const |
Gets the variance of the rotation axis of emitted particles.
| float gameplay::ParticleEmitter::getRotationPerParticleSpeedMax | ( | ) | const |
Gets the maximum rotation speed of each emitted particle.
| float gameplay::ParticleEmitter::getRotationPerParticleSpeedMin | ( | ) | const |
Gets the minimum rotation speed of each emitted particle.
| float gameplay::ParticleEmitter::getRotationSpeedMax | ( | ) | const |
Gets the maximum rotation speed of emitted particles.
| float gameplay::ParticleEmitter::getRotationSpeedMin | ( | ) | const |
Gets the minimum rotation speed of emitted particles.
| float gameplay::ParticleEmitter::getSizeEndMax | ( | ) | const |
Gets the maximum size that each particle can be at the end of its lifetime.
| float gameplay::ParticleEmitter::getSizeEndMin | ( | ) | const |
Gets the minimum size that each particle can be at the end of its lifetime.
| float gameplay::ParticleEmitter::getSizeStartMax | ( | ) | const |
Gets the maximum size that each particle can be at the time when it is started.
| float gameplay::ParticleEmitter::getSizeStartMin | ( | ) | const |
Gets the minimum size that each particle can be at the time when it is started.
| unsigned int gameplay::ParticleEmitter::getSpriteFrameCount | ( | ) | const |
Returns the current number of frames for the particle emitter's sprite.
| long gameplay::ParticleEmitter::getSpriteFrameDuration | ( | ) | const |
Gets the animated sprites frame duration.
| int gameplay::ParticleEmitter::getSpriteFrameRandomOffset | ( | ) | const |
Gets the maximum offset that a random frame from 0 to maxOffset will be selected.
| unsigned int gameplay::ParticleEmitter::getSpriteHeight | ( | ) | const |
Returns the height of the first frame this particle emitter's sprite.
| unsigned int gameplay::ParticleEmitter::getSpriteWidth | ( | ) | const |
Returns the width of the first frame this particle emitter's sprite.
| Texture* gameplay::ParticleEmitter::getTexture | ( | ) | const |
Returns the texture currently set for this particle emitter.
| const Vector3& gameplay::ParticleEmitter::getVelocity | ( | ) | const |
Gets the initial velocity of new particles.
| const Vector3& gameplay::ParticleEmitter::getVelocityVariance | ( | ) | const |
Gets the initial velocity variance of new particles.
| bool gameplay::ParticleEmitter::isActive | ( | ) | const |
Gets whether this ParticleEmitter is currently active (i.e. if any of its particles are alive).
| bool gameplay::ParticleEmitter::isEllipsoid | ( | ) | const |
Determines whether the positions of newly emitted particles are generated within an ellipsoidal domain.
| bool gameplay::ParticleEmitter::isSpriteAnimated | ( | ) | const |
Whether particles cycle through the sprite frames.
| bool gameplay::ParticleEmitter::isSpriteLooped | ( | ) | const |
Whether sprites are set to loop, each frame will last for the emitter's frameDuration.
| bool gameplay::ParticleEmitter::isStarted | ( | ) | const |
Gets whether this ParticleEmitter is currently started.
| void gameplay::ParticleEmitter::setAcceleration | ( | const Vector3 & | acceleration, |
| const Vector3 & | accelerationVariance | ||
| ) |
Sets the base acceleration vector and its allowed variance for this ParticleEmitter.
| acceleration | The base acceleration vector of emitted particles. |
| accelerationVariance | The variance allowed in the acceleration of emitted particles. |
| void gameplay::ParticleEmitter::setBlendMode | ( | BlendMode | blendMode | ) |
Sets the texture blend mode for this particle emitter.
| blendMode | The new blend mode. |
| void gameplay::ParticleEmitter::setColor | ( | const Vector4 & | start, |
| const Vector4 & | startVariance, | ||
| const Vector4 & | end, | ||
| const Vector4 & | endVariance | ||
| ) |
Set the start and end colors, and their variances, of particles in this emitter's system.
| start | The base start color of emitted particles. |
| startVariance | The variance of start color of emitted particles. |
| end | The base end color of emitted particles. |
| endVariance | The variance of end color of emitted particles. |
| void gameplay::ParticleEmitter::setEllipsoid | ( | bool | ellipsoid | ) |
Sets whether the positions of newly emitted particles are generated within an ellipsoidal domain.
Each vector property is generated such as to fall within the domain defined by a base vector and a variance vector. If that domain is ellipsoidal, vectors are generated within an ellipsoid centered at the base vector and scaled by the variance vector. If that domain is not ellipsoidal, vectors are generated by multiplying the variance vector by a random floating-point number between -1 and 1, then adding this result to the base vector.
Ellipsoidal domains are somewhat less efficient and only necessary when determining the positions of newly emitted particles. Call this method with 'true' to make initial position an ellipsoidal domain. The default setting is 'false'.
| ellipsoid | Whether initial particle positions are generated within an ellipsoidal domain. |
| void gameplay::ParticleEmitter::setEmissionRate | ( | unsigned int | rate | ) |
Sets the emission rate, measured in particles per second.
| rate | The emission rate, measured in particles per second. |
| void gameplay::ParticleEmitter::setEnergy | ( | long | energyMin, |
| long | energyMax | ||
| ) |
Sets the minimum and maximum lifetime of emitted particles, measured in milliseconds.
| energyMin | The minimum lifetime of each particle, measured in milliseconds. |
| energyMax | The maximum lifetime of each particle, measured in milliseconds. |
| void gameplay::ParticleEmitter::setOrbit | ( | bool | orbitPosition, |
| bool | orbitVelocity, | ||
| bool | orbitAcceleration | ||
| ) |
Sets whether the vector properties of newly emitted particles are rotated around the node's position by the node's rotation matrix.
| orbitPosition | Whether to rotate initial particle positions by the node's rotation matrix. |
| orbitVelocity | Whether to rotate initial particle velocity vectors by the node's rotation matrix. |
| orbitAcceleration | Whether to rotate initial particle acceleration vectors by the node's rotation matrix. |
| void gameplay::ParticleEmitter::setParticleCountMax | ( | unsigned int | max | ) |
Sets the maximum number of particles that can be emitted.
| max | The maximum number of particles that can be emitted. |
| void gameplay::ParticleEmitter::setPosition | ( | const Vector3 & | position, |
| const Vector3 & | positionVariance | ||
| ) |
Sets the initial position and position variance of new particles.
| position | The initial position of new particles. |
| positionVariance | The amount of variance allowed in the initial position of new particles. |
| void gameplay::ParticleEmitter::setRotation | ( | float | speedMin, |
| float | speedMax, | ||
| const Vector3 & | axis, | ||
| const Vector3 & | axisVariance | ||
| ) |
Sets a rotation axis in world space around which all particles will spin, as well as the minimum and maximum rotation speed around this axis. This should not be confused with rotation speed per particle.
| axis | The base rotation axis of emitted particles. |
| axisVariance | The variance of the rotation axis of emitted particles. |
| speedMin | The minimum rotation speed of emitted particles. |
| speedMax | The maximum rotation speed of emitted particles. |
| void gameplay::ParticleEmitter::setRotationPerParticle | ( | float | speedMin, |
| float | speedMax | ||
| ) |
Gets the maximum rotation speed of each emitted particle. This determines the speed of rotation of each particle's screen-facing billboard.
| speedMin | The minimum rotation speed (per particle). |
| speedMax | The maximum rotation speed (per particle). |
| void gameplay::ParticleEmitter::setSize | ( | float | startMin, |
| float | startMax, | ||
| float | endMin, | ||
| float | endMax | ||
| ) |
Sets the minimum and maximum size that each particle can be at the time when it is spawned, as well as the minimum and maximum size for particles to be at the end of their lifetimes.
| startMin | The minimum size that each particle can be at the time when it is started. |
| startMax | The maximum size that each particle can be at the time when it is started. |
| endMin | The minimum size that each particle can be at the end of its lifetime. |
| endMax | The maximum size that each particle can be at the end of its lifetime. |
| void gameplay::ParticleEmitter::setSpriteAnimated | ( | bool | animated | ) |
Sets whether particles cycle through the sprite frames.
| animated | Whether to animate particles through the sprite frames. |
| void gameplay::ParticleEmitter::setSpriteFrameCoords | ( | unsigned int | frameCount, |
| Rectangle * | frameCoords | ||
| ) |
Sets the sprite's texture coordinates in image space (pixels).
| frameCount | The number of frames to set texture coordinates for. |
| frameCoords | A rectangle for each frame representing its position and size within the texture image, measured in pixels. |
| void gameplay::ParticleEmitter::setSpriteFrameCoords | ( | unsigned int | frameCount, |
| int | width, | ||
| int | height | ||
| ) |
Calculates and sets the sprite's texture coordinates based on the width and height of a single frame, measured in pixels. This method assumes that there is no padding between sprite frames and that the first frame is in the top-left corner of the image. Frames are ordered in the image from left to right, top to bottom.
| frameCount | The number of frames to set texture coordinates for. |
| width | The width of a single frame, in pixels. |
| height | The height of a single frame, in pixels. |
| void gameplay::ParticleEmitter::setSpriteFrameDuration | ( | long | duration | ) |
Set the animated sprites frame duration.
| duration | The duration of a single sprite frame, in milliseconds. |
| void gameplay::ParticleEmitter::setSpriteFrameRandomOffset | ( | int | maxOffset | ) |
Sets the maximum offset that a random frame from 0 to maxOffset will be selected. Set maxOffset to 0 (the default) for all particles to start on the first frame. maxOffset will be clamped to frameCount.
| maxOffset | The maximum sprite frame offset. |
| void gameplay::ParticleEmitter::setSpriteLooped | ( | bool | looped | ) |
If sprites are set to loop, each frame will last for the emitter's frameDuration. If sprites are set not to loop, the animation will be timed so that the last frame finishes just as a particle dies. Note: This timing is calculated based on a spriteRandomOffset of 0. For other offsets, the final frame may be reached earlier. If sprites are not set to animate, this setting has no effect.
| looped | Whether to loop animated sprites. |
| void gameplay::ParticleEmitter::setSpriteTexCoords | ( | unsigned int | frameCount, |
| float * | texCoords | ||
| ) |
Sets the sprite's texture coordinates in texture space.
| frameCount | The number of frames to set texture coordinates for. |
| texCoords | The texture coordinates for all frames, in texture space. |
| void gameplay::ParticleEmitter::setTexture | ( | const char * | texturePath, |
| BlendMode | blendMode | ||
| ) |
Sets a new texture for this particle emitter.
The current texture's reference count is decreased.
| texturePath | Path to the new texture to set. |
| blendMode | Blend mode for the new texture. |
| void gameplay::ParticleEmitter::setTexture | ( | Texture * | texture, |
| BlendMode | blendMode | ||
| ) |
Sets a new texture for this particle emitter.
The reference count of the specified texture is increased, and the current texture's reference count is decreased.
| texture | The new texture to set. |
| blendMode | Blend mode for the new texture. |
| void gameplay::ParticleEmitter::setVelocity | ( | const Vector3 & | velocity, |
| const Vector3 & | velocityVariance | ||
| ) |
Sets the base velocity of new particles and its variance.
| velocity | The initial velocity of new particles. |
| velocityVariance | The amount of variance allowed in the initial velocity of new particles. |
| void gameplay::ParticleEmitter::start | ( | ) |
Starts emitting particles over time at this ParticleEmitter's emission rate.
| void gameplay::ParticleEmitter::stop | ( | ) |
Stops emitting particles over time.
| void gameplay::ParticleEmitter::update | ( | float | elapsedTime | ) |
Updates the particles currently being emitted.
| elapsedTime | The amount of time that has passed since the last call to update(), in milliseconds. |
1.7.6.1