H3D::ParticleSystem Class Reference
[X3D node classes.]

The ParticleSystem node specifies a complete particle system. More...

#include <H3D/ParticleSystem.h>

Inheritance diagram for H3D::ParticleSystem:

Inheritance graph

List of all members.

Public Member Functions

 ParticleSystem (Inst< SFAppearanceNode > _appearance=0, Inst< SFGeometryNode > _geometry=0, Inst< SFHapticGeometry > _hapticGeometry=0, Inst< SFNode > _metadata=0, Inst< SFBound > _bound=0, Inst< SFVec3f > _bboxCenter=0, Inst< SFVec3f > _bboxSize=0, Inst< DisplayList > _displayList=0, Inst< SFBool > _createParticles=0, Inst< SFBool > _enabled=0, Inst< SFFloat > _lifetimeVariation=0, Inst< SFInt32 > _maxParticles=0, Inst< SFFloat > _particleLifetime=0, Inst< SFVec2f > _particleSize=0, Inst< SFBool > _isActive=0, Inst< SFColorNode > _colorRamp=0, Inst< MFFloat > _colorKey=0, Inst< SFEmitterNode > _emitter=0, Inst< SFString > _geometryType=0, Inst< MFPhysicsModelNode > _physics=0, Inst< SFTextureCoordinate > _texCoordRamp=0, Inst< MFFloat > _texCoordKey=0)
 Constructor.
virtual void initialize ()
 Sets up the bound field using the bboxCenter and bboxSize fields.
virtual void render ()
 Render the shape using OpenGL.
virtual void traverseSG (TraverseInfo &ti)
 Traverse the scenegraph. Calls traverseSG on appeance and geometry.
X3DParticleEmitterNode::Particle::ParticleType getCurrentParticleType ()
 Returns the enum equivalent to the particle type specified with the geometryType field.

Static Public Member Functions

static H3DFloat getVariationValue (H3DFloat main_value, H3DFloat variation)
 Returns a random value in the range main_value +- (variation * main_value ).
static H3DFloat getRandomValue (H3DFloat min, H3DFloat max)
 Returns a random value in the given range.
static Vec3f getRandomPointOnUnitSphere ()
 Returns a random point on the unit sphere.
static const ParticleSystemList & getAllParticleSystems ()
 Returns a list of all current ParticleSystem instances.

Public Attributes

auto_ptr< SFBoolcreateParticles
 The createParticles field is used to control whether any further new particles should be created.
auto_ptr< SFBoolenabled
 The enabled field controls whether this ParticleSystem is currently active and rendering particles this frame.
auto_ptr< SFFloatlifetimeVariation
 The lifetimeVariation field controls the variation in a particles lifetime.
auto_ptr< SFInt32maxParticles
 The maximum number of particles to be generated.
auto_ptr< SFFloatparticleLifetime
 The particleLifetime field controls the lifetime of a particle i.e.
auto_ptr< SFVec2fparticleSize
 The particleSize field describes the dimensions in metres of the width and height of each particle.
auto_ptr< SFBoolisActive
 The isActive field indicates whether the particle system is currently running, based on the setup of the node.
auto_ptr< SFColorNodecolorRamp
 The colorRamp field holds a series of colour values to be used at the given colorKey points in time for the particle over its lifetime.
auto_ptr< MFFloatcolorKey
 The colorKey field represents the time of the particle in seconds and are the keys to use for the colorRamp field.
auto_ptr< SFEmitterNodeemitter
 The emitter field specifies the type of emitter geometry and properties that the particles are given for their initial positions.
auto_ptr< SFStringgeometryType
 The geometryType field specifies the type of geometry that should be used to represent individual particles.
auto_ptr< MFPhysicsModelNodephysics
 The physics field contains the physics models that should affect the particles after they have been created, e.g.
auto_ptr< SFTextureCoordinatetexCoordRamp
 The texCoordRamp fields control the texture coordinates of the provided texture(s) in the Appearance node, over time.
auto_ptr< MFFloattexCoordKey
 The colorKey field represents the time of the particle in seconds and are the keys to use for the texCoordRamp field.

Static Public Attributes

static H3DNodeDatabase database
 The H3DNodeDatabase for this node.


Detailed Description

The ParticleSystem node specifies a complete particle system.

The geometryType field specifies the type of geometry that should be used to represent individual particles. Typically, a particle is calculated as a point in space at which the geometry is placed and then rendered using the appearance attributes.

The types of geometry are defined to render in the following way:

The geometry field specifies the geometry to be used for each particle when the geometryType field has value "GEOMETRY".

The appearance field holds information that is used for the geometry. All effects, such as material colours and/or multi-textures, are applied to each particle. If a texture coordinate ramp and key is supplied with this geometry, it shall be used in preference to any automatic texture coordinate generation. If automatic texture coordinate generation is used, results shall be based on the entire volume that the particles consume, not locally applied to each particle.

Procedural shaders may also be supplied. The particle system shall manage the position of all particles each frame. This position becomes the initial geometry input to the shader.

The emitter field specifies the type of emitter geometry and properties that the particles are given for their initial positions. After being created, the individual particles are then manipulated according to the physics model(s) specified in the physics field.

The colorRamp and colorKey fields specify how to change the base colour of the particle over the lifetime of an individual particle. The colorKey field represents the time of the particle in seconds, while the colorRamp field holds a series of colour values to be used at the given key points in time. Between keys, colour values are interpreted in a linear HSV space, using the same rules defined for the ColorInterpolator node. The colour values are defined as per-vertex colour values. Consequently, if an appearance node with material is provided, the material properties will override the colour ramp.

The isActive outputOnly field indicates whether the particle system is currently running, based on the setup of the node.

The isActive field sends a value of FALSE when activity has stopped occurring. A particle system without an emitter set can never be active. If the emitter is defined by an EXTERNPROTO that has not yet resolved, isActive shall initially be FALSE, until the point the EXTERNPROTO has loaded and is verified as being a correct node type. If these validity checks pass, isActive is set to TRUE and this defines the local time zero to start the particle effects.

The enabled field controls whether this ParticleSystem is currently active and rendering particles this frame. Setting this value to FALSE will immediately remove all visible particles from the scene from the next frame onwards. Setting the field to TRUE will start the system again from a local time zero. It does not start off from where it was previously. In doing so, it will issue another value of TRUE for isActive. If a value of FALSE is set for enabled, isActive will also be set to FALSE.

The createParticles field is used to control whether any further new particles should be created. This allows the user to stop production of new particles, but keep those already existing in the scene to continue to animate. This differs from the enabled field that would immediately remove all particles. The createParticles field keeps the existing particles in existence until the end of their lifetimes. If there are no particles left in the scene, the system is still considered both active and enabled.

The particleSize field describes the dimensions in metres of the width and height of each particle. Changing this value dynamically will only change new particles created after the change. Particles created before this timestamp will remain at the old size. This field only effects particles using "LINE", "QUAD", "SPRITE", and "TRIANGLE" geometry types.

The texCoordRamp and texCoordKey fields control the texture coordinates of the provided texture(s) in the Appearance node, over time. Particle systems frequently like to change the texture on a particle as it ages, yet there is no good way of accomplishing this through standard interpolators because interpolators have no concept of particle time. This pair of fields hold time-dependent values for the texture coordinates to be applied to the particle. When a particle reaches the next time stamp it moves to the next set of texture coordinates. There is no interpolation of the texture coordinates, just sequenced according to the times defined by texCoordKey.

The node placed in texCoordRamp shall have enough values to work with the numbers required by geometryType. The following numbers and rules for mapping texture coordinates to the quad shall be used:

Internal routes:
ParticleSystem.dot

Member Function Documentation

X3DParticleEmitterNode::Particle::ParticleType ParticleSystem::getCurrentParticleType (  ) 

Returns the enum equivalent to the particle type specified with the geometryType field.

References geometryType.

void ParticleSystem::initialize (  )  [virtual]

Sets up the bound field using the bboxCenter and bboxSize fields.

If bboxSize is (-1, -1, -1) the bound will be the bound of the geometry field. Otherwise it will be a BoxBound with center and origin determined by the bboxCenter and bboxOrigin fields.

Reimplemented from H3D::X3DShapeNode.

References H3D::X3DBoundedObject::bboxCenter, H3D::X3DBoundedObject::bboxSize, H3D::H3DBoundedObject::bound, H3D::BoxBound::center, and H3D::BoxBound::size.


Member Data Documentation

The colorKey field represents the time of the particle in seconds and are the keys to use for the colorRamp field.

Access type: inputOutput

ParticleSystem_colorKey.dot

The colorRamp field holds a series of colour values to be used at the given colorKey points in time for the particle over its lifetime.

Between keys, colour values are interpreted in a linear HSV space, using the same rules defined for the ColorInterpolator node. The colour values are defined as per-vertex colour values. Consequently, if an appearance node with material is provided, the material properties will override the colour ramp.

Access type: inputOutput

ParticleSystem_colorRamp.dot

The createParticles field is used to control whether any further new particles should be created.

This allows the user to stop production of new particles, but keep those already existing in the scene to continue to animate. This differs from the enabled field that would immediately remove all particles.

Access type: inputOutput

Default value: TRUE

ParticleSystem_createParticles.dot

Referenced by ParticleSystem(), and traverseSG().

The emitter field specifies the type of emitter geometry and properties that the particles are given for their initial positions.

After being created, the individual particles are then manipulated according to the physics model(s) specified in the physics field.

Access type: inputOutput

ParticleSystem_emitter.dot

Referenced by traverseSG().

The enabled field controls whether this ParticleSystem is currently active and rendering particles this frame.

Setting this value to FALSE will immediately remove all visible particles from the scene from the next frame onwards. Setting the field to TRUE will start the system again from a local time zero. It does not start off from where it was previously. In doing so, it will issue another value of TRUE for isActive. If a value of FALSE is set for enabled, isActive will also be set to FALSE.

Access type: inputOutput

Default value: TRUE

ParticleSystem_enabled.dot

Referenced by ParticleSystem(), and traverseSG().

The geometryType field specifies the type of geometry that should be used to represent individual particles.

Typically, a particle is calculated as a point in space at which the geometry is placed and then rendered using the appearance attributes.

Access type: inputOutput Default value: "QUAD" Allowed values: "LINE", "POINT", "QUAD", "SPRITE", "TRIANGLE", "GEOMETRY"

ParticleSystem_geometryType.dot

Referenced by getCurrentParticleType(), ParticleSystem(), and traverseSG().

The isActive field indicates whether the particle system is currently running, based on the setup of the node.

Access type: outputOnly

ParticleSystem_isActive.dot

The lifetimeVariation field controls the variation in a particles lifetime.

It describes the allowed deviation in particle liftime from the value in particleLifetime. The variation is the maximum bound of that value, described as a proportion of the original value. A variation value of zero does not allow any randomness.

Access type: inputOutput Default value: 0.25

ParticleSystem_lifetimeVariation.dot

Referenced by ParticleSystem().

The maximum number of particles to be generated.

Access type: inputOutput Default value: 200

ParticleSystem_maxParticles.dot

Referenced by ParticleSystem().

The particleLifetime field controls the lifetime of a particle i.e.

the time in seconds the particle exists from the point it is being emitted. See also the lifetimeVariation field.

Access type: inputOutput Default value: 5

ParticleSystem_particleLifetime.dot

Referenced by ParticleSystem().

The particleSize field describes the dimensions in metres of the width and height of each particle.

Changing this value dynamically will only change new particles created after the change. Particles created before this timestamp will remain at the old size. This field only effects particles using "LINE", "QUAD", "SPRITE", and "TRIANGLE" geometry types.

Access type: inputOutput Default value: 0.02 0.02

ParticleSystem_particleSize.dot

Referenced by ParticleSystem(), and traverseSG().

The physics field contains the physics models that should affect the particles after they have been created, e.g.

gravity and wind effects.

Access type: inputOutput

ParticleSystem_physics.dot

Referenced by traverseSG().

The colorKey field represents the time of the particle in seconds and are the keys to use for the texCoordRamp field.

Access type: inputOutput

ParticleSystem_texCoordKey.dot

The texCoordRamp fields control the texture coordinates of the provided texture(s) in the Appearance node, over time.

Access type: inputOutput

ParticleSystem_texCoordRamp.dot


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

Generated on Fri Nov 7 10:30:43 2008 for H3D API by  doxygen 1.5.7