Extensible 3D (X3D)
Part 1: Architecture and base components

40 Particle systems component

--- X3D separator bar ---

cube 40.1 Introduction

40.1.1 Name

The name of this component is "ParticleSystems". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

40.1.2 Overview

This component specifies how to model particles and their interactions through the application of basic physics principles to affect motion. Table 40.1 provides links to the major topics in this clause.

Table 40.1 — Topics

cube 40.2 Concepts

40.2.1 Overview

A particle system specifies a process for rendering such effects as fire, smoke, and snow. Although various physics models are available, it is not meant to be used as a simulation engine for testing particle behaviour models. Thus, particle systems are designed for visual effects, not rigid analysis systems.

A particle system is a shape node type as both appearance and texturing need to be controlled in order to create realistic particle system effects. A particle system in and of itself is not geometry because it dynamically creates and destroys geometry on the fly. A particle system also has other factors feeding into the visual output different from a typical geometry node.

EXAMPLE  Time-varying colour values

The geometry node of a shape node is not used at the first support level. If a node supports both levels of the specification, the geometry node takes preference over the geometryType field.

Particles are generated using the current geometry, allowing particle geometry to be changed over time. Old particles that are still current when the specified geometry changes continue to use the original geometry.

40.2.2 Physics models

To allow aggregating a collection of nodes with a particular physics model,  an X3DParticlePhysicsModelNode abstract node type is provided that is used to derive nodes in which all children nodes of that group are bound by the specified physics model. This can be used to support simple effects such as gravity. The physics models are designed to be composable.

EXAMPLE  The BoundedPhysicsModel node can be used with an extrusion as the geometry and then a WindPhysicsModel node can be used with the geometry to produce smoke tunneling effects.

40.2.3 Colour ramps

A colour ramp is used to specify the colour cycle over time. A colour ramp is a variation on the normal use of a colour interpolator. The key represents relative time values from the start of the lifetime of the particle. There should be the same number of colours in the node as there are key values. If not, the smaller number of the two values will be used. For particles that last longer than the last time value, the colour associated with the last time value will be continued for the rest of the lifetime of the particle.

40.2.4 Randomness and variation

Many nodes describe emission as using a random pattern. The random generation model shall use a linear distribution of equal probability across the defined output spectrum.

Nodes that describe a variation field allow for deviation from the described main field value. 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.

EXAMPLE  If field has a value of 10, a variation of 0.25 will allow values to be randomly generated in the range of 7.5 to 12.5. The same field with a value of 1 will only allow a range of randomly generated values between 0.75 and 1.25.

40.2.5 Event model interaction

Evaluation of emission and interactions of particles are performed as specified in 4.4.8.3 Execution model. All changes made during current event cascade are first applied. Then, the particles are generated, particle system physics are applied, and rendering of the particles takes place.

Particle systems interact with navigation, pointing device sensors, collision detection and picking according to the underlying geometry type. Point particles, point sprite particles and line particles cannot be picked; other types of particles can be picked.

40.2.6 Interaction with other components

There are many different ways to implement particle systems. This specification does not require any particular technology or means of implementation. However, a popular implementation is to use programmable shaders to perform the per-frame evaluation of the particles. While it is not advised, it is possible and legal to supply programmable shaders as part of the particle system's appearance field. If the user supplies a programmable shader, the implementation shall use a CPU-generated model for this case.

The physics model nodes in this component are independent of the physics evaluation defined in 37 Rigid body physics component. This part of ISO/IEC 19775 does not explicitly prohibit interaction between the two models, but does not cater for direct implementation of one by the other ( e.g., use of hardware accelerated physics cards to implement particle systems).

cube 40.3 Abstract types

40.3.1 X3DParticleEmitterNode

X3DParticleEmitterNode : X3DNode {
  SFNode  [in,out] metadata    NULL [X3DMetadataObject]
  SFFloat [in,out] speed       0    [0,∞)
  SFFloat [in,out] variation   0.25 [0,∞)
  SFFloat []       mass        0    [0,∞)
  SFFloat []       surfaceArea 0    [0,∞)
}

The X3DParticleEmitterNode abstract type represents any node that is an emitter of particles. The shape and distribution of particles is dependent on the type of the concrete node.

The speed field specifies an initial linear speed that will be imparted to all particles. It does not signify the direction of the particles. The directional component of the velocity is specified by the concrete node representation.

The variation field specifies a multiplier for the randomness that is used to control the range of possible output values. The bigger the value, the more random the output and the bigger the range of possible initial values possible. A variation of zero does not allow any randomness.

The mass field specifies the basic mass of each particle in mass base units. Mass is needed if gravity or other force-related calculations are to be performed per-particle.

The surfaceArea field specifies the surface area of the particle in area base units. Surface area is used for calculations such as wind effects per particle. The surfaceArea field value represents an average frontal area that would be presented to the wind, assuming a spherical model for each particle ( i.e., the surface area is the same regardless of direction).

40.3.2 X3DParticlePhysicsModelNode

X3DParticlePhysicsModelNode : X3DNode { 
  SFBool [in,out] enabled  TRUE
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

The X3DParticlePhysicsModelNode abstract type represents any node that applies a form of constraints on the particles after they have been generated.

The enabled field specifies whether this physics model is currently being applied to the particles.

cube 40.4 Node reference

40.4.1 BoundedPhysicsModel

BoundedPhysicsModel : X3DParticlePhysicsModelNode { 
  SFBool [in,out] enabled  TRUE
  SFNode [in,out] geometry NULL [X3DGeometryNode]
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

The BoundedPhysicsModel node specifies a physics model that applies a user-defined set of geometrical bounds to the particles.

The geometry field specifies a piece of geometry that models the bounds that constrain the location of the particles. When a particle touches the surface of the bounds, it is reflected. The particles may be restricted to an inside location or an outside location. All geometry defined by the bounds are considered to be non-solid, regardless of the setting of the solid field. It does not matter whether the particle impacts the front or back side of the geometry. Particles are reflected at the same angle to the normal of the surface to which they impact, continuing in the same direction. The calculation of the correct normal is determined by the rules of the geometry that forms the bounds.

EXAMPLE  A particle can be made to bounce off an elevation grid representing terrain.

40.4.2 ConeEmitter

ConeEmitter : X3DParticleEmitterNode { 
  SFFloat [in,out] angle       π/4   [0,π]
  SFVec3f [in,out] direction   0 1 0 
  SFNode  [in,out] metadata    NULL  [X3DMetadataObject]
  SFVec3f [in,out] position    0 0 0
  SFFloat [in,out] speed       0     [0,∞)
  SFFloat [in,out] variation   0.25  [0,∞)
  SFFloat []       mass        0     [0,∞)
  SFFloat []       surfaceArea 0     [0,∞)
}

The ConeEmitter node is an emitter that generates all the available particles from a specific point in space. Particles are emitted from the single point specified by the position field emanating in a direction randomly distributed within the cone specified by the angle and direction fields at the speed specified by the speed field.

40.4.3 ExplosionEmitter

ExplosionEmitter : X3DParticleEmitterNode { 
  SFNode  [in,out] metadata    NULL  [X3DMetadataObject]
  SFVec3f [in,out] position    0 0 0
  SFFloat [in,out] speed       0     [0,∞)
  SFFloat [in,out] variation   0.25  [0,∞)
  SFFloat []       mass        0     [0,∞)
  SFFloat []       surfaceArea 0     [0,∞)
}

The ExplosionEmitter node is an emitter that generates all the available particles from a specific point in space at the initial time. Particles are emitted from the single point specified by the position field in all directions at the speed specified by the speed field.

40.4.4 ForcePhysicsModel

ForcePhysicsModel : X3DParticlePhysicsModelNode { 
  SFBool  [in,out] enabled  TRUE
  SFVec3f [in,out] force    0 -9.8 0 (∞,∞)
  SFNode  [in,out] metadata NULL     [X3DMetadataObject]
}

The ForcePhysicsModel node specifies a physics model that applies a constant force value to the particles. Force may act in any given direction vector at any strength.

The force field is used to indicate the strength and direction of the force ( e.g., gravity) that should be applied. Force is specified in force base units. If the particles are defined to have zero mass by the emitter, the ForcePhysicsModel node has no effect.

40.4.5 ParticleSystem

ParticleSystem : X3DShapeNode { 
  SFNode   [in,out] appearance        NULL      [X3DAppearanceNode]
  SFBool   [in,out] createParticles   TRUE
  SFNode   [in,out] geometry          NULL      [X3DGeometryNode]
  SFBool   [in,out] enabled           TRUE
  SFFloat  [in,out] lifetimeVariation 0.25      [0,1]
  SFInt32  [in,out] maxParticles      200       [0,∞)
  SFNode   [in,out] metadata          NULL      [X3DMetadataObject]
  SFFloat  [in,out] particleLifetime  5         [0,∞)
  SFVec2f  [in,out] particleSize      0.02 0.02 [0,∞)
  SFBool   [out]    isActive
  SFVec3f  []       bboxCenter        0 0 0
  SFVec3f  []       bboxSize          -1 -1 -1  (0,∞) or -1 -1 -1
  
  SFNode   []       color             NULL      [X3DColorNode]
  MFFloat  []       colorKey          []        [0,∞)
  SFNode   []       emitter           NULL      [X3DParticleEmitterNode]
  SFString []       geometryType      "QUAD"    ["LINE"|"POINT"|"QUAD"|"SPRITE"|"TRIANGLE"|"GEOMETRY"|...]
  MFNode   []       physics           []        [X3DParticlePhysicsModelNode]
  
  SFNode   []       texCoord          NULL      [TextureCoordinate|TextureCoordinateGenerator]
  MFFloat  []       texCoordKey       []        [0,∞)
}

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 color 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 color 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.

NOTE  the original name for the ParticleSystem color field in X3D version 3 is colorRamp.

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

EXAMPLE  Using an explosion emitter that generates all of its particles at the first time and has them all die at a fixed time later, the particle system will only run for a short amount of time. After that, nothing is visible on-screen or the particle geometry does not need updating any more.

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 maxParticles field specifies the maximum number of particles to be generated at one time (subject to player limitations). Support for at least 10,000 particles is required.

The particleLifetime field specifies the nominal duration in seconds of any particle.

The lifetimeVariation field specifies the proportion of the total lifetime that is the amount of allowed linear random variation from the value specified by the particleLifetime field.

The particleSize field describes the dimensions in length base units 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 texCoord 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 texCoord 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:

NOTE  the original name for the ParticleSystem texCoord field in X3D version 3 is texCoordRamp.

40.4.6 PointEmitter

PointEmitter : X3DParticleEmitterNode { 
  SFVec3f [in,out] direction   0 1 0
  SFNode  [in,out] metadata    NULL  [X3DMetadataObject]
  SFVec3f [in,out] position    0 0 0
  SFFloat [in,out] speed       0     [0,∞)
  SFFloat [in,out] variation   0.25  [0,∞)
  SFFloat []       mass        0     [0,∞)
  SFFloat []       surfaceArea 0     [0,∞)
}

The PointEmitter node is an emitter that generates particles from a specific point in space. Particles are emitted from a single point in the specified direction and speed.

The direction field specifies a direction along which the particles are to be emitted. If the vector is zero length (a value of (0,0,0), particles are emitted in random directions from this point in space.

40.4.7 PolylineEmitter

PolylineEmitter : X3DParticleEmitterNode { 
  MFInt32 [in]     set_coordIndex
  SFNode  [in,out] coord          NULL  [X3DCoordinateNode]
  SFVec3f [in,out] direction      0 1 0 [-1,1]
  SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
  SFFloat [in,out] speed          0     [0,∞)
  SFFloat [in,out] variation      0.25  [0,∞)
  MFInt32 []       coordIndex     -1    [0,∞) or -1
  SFFloat []       mass           0     [0,∞)
  SFFloat []       surfaceArea    0     [0,∞)
}

The PolylineEmitter node emits particles along a single polyline. The coordinates for the line along which particles should be randomly generated are taken from a combination of the coord and coordIndex fields. The starting point for generating particles is randomly distributed along this line and given the initial speed and direction. If no coordinates are available, the PolylineEmitter node shall act like a point source located at the local origin.

40.4.8 SurfaceEmitter

SurfaceEmitter : X3DParticleEmitterNode { 
  MFInt32 [in]     set_coordIndex
  SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
  SFFloat [in,out] speed          0     [0,∞)
  SFFloat [in,out] variation      0.25  [0,∞)
  MFInt32 []       coordIndex     -1    [0,∞) or -1
  SFFloat []       mass           0     [0,∞)
  SFNode  []       surface        NULL  [X3DGeometryNode]
  SFFloat []       surfaceArea    0     [0,∞)
}

The SurfaceEmitter node is an emitter that generates particles from the surface of an object. New particles are generated by first randomly choosing a face on the tessellated geometry and then a random position on that face. Particles are generated with an initial direction of the normal to that point (including any normal averaging due to normalPerVertex and creaseAngle field settings). If the surface is indicated as not being solid ( solid field set to FALSE), randomly choose from which side of the surface to emit, negating the normal direction when generating from the back side. Only valid geometry shall be used.

The surface field specifies the geometry to be used as the emitting surface.

EXAMPLE  A cylinder with both end caps turned off would only generate particles along the side of the cylinder. It would be an error to generate a particle with an initial direction that is not perpendicular to the axis.

40.4.9 VolumeEmitter

VolumeEmitter : X3DParticleEmitterNode { 
  MFInt32 [in]     set_coordIndex
  SFNode  [in,out] coord          NULL  [X3DCoordinateNode]
  SFVec3f [in,out] direction      0 1 0 [-1,1]
  SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
  SFFloat [in,out] speed          0     [0,∞)
  SFFloat [in,out] variation      0.25  [0,∞)
  MFInt32 []       coordIndex     -1    [0,∞) or -1
  SFBool  []       internal       TRUE
  SFFloat []       mass           0     [0,∞)
  SFFloat []       surfaceArea    0     [0,∞)
}

A VolumeEmitter node emits particles from a random position confined within the given closed geometry volume. Otherwise, a VolumeEmitter node acts like a PolylineEmitter node.

40.4.10 WindPhysicsModel

WindPhysicsModel : X3DParticlePhysicsModelNode { 
  SFVec3f [in,out] direction  01 0 0 (∞,∞)
  SFBool  [in,out] enabled    TRUE
  SFFloat [in,out] gustiness  0.1   [0,∞)
  SFNode  [in,out] metadata   NULL  [X3DMetadataObject]
  SFFloat [in,out] speed      0.1   [0,∞)
  SFFloat [in,out] turbulence 0     [0,1]
}

The WindPhysicsModel node specifies a physics model that applies a wind effect to the particles. The wind has a random variation factor that allows for the gustiness of the wind to be modelled.

The direction field specifies the direction in which the wind is travelling in the form of a  normalized, unit vector.

The speed field specifies the current wind speed in length base units. From the wind speed, the force applied per unit-area on the particle is calculated using the following formula:

pressure = 10(2 × log(speed)) × 0.64615

The gustiness specifies how much the wind speed varies from the average value defined by the speed field. The wind speed variation is calculated once per frame and applied equally to all particles.

The turbulence field specifies how much the wind acts directly in line with the direction, and how much variation is applied in directions other than the wind direction. This is determined per-particle to model how the particle is affected by turbulence.

cube 40.5 Support levels

The Particle Systems component provides two levels of support as specified in Table 40.2.

Table 40.2 — Particle systems component support levels

Level Prerequisites Nodes/Features Support
1 Core 1
Grouping 1
Shape 1
Rendering 1
X3DParticleEmitterNode n/a
X3DParticlePhysicsModelNode n/a
    ConeEmitter All fields fully supported.
ExplosionEmitter All fields fully supported.
GravityPhysicsModel All fields fully supported.
ParticleSystem All fields fully supported, except "SPRITE" and "GEOMETRY" geometry types and the geometry field.
    PointEmitter All fields fully supported.
    PolylineEmitter All fields fully supported.
    WindPhysicsModel All fields fully supported.
2 Core 1
Grouping 1
Shape 1
Rendering 1
Texturing 1
   
    All Level 1 nodes All fields supported as specified for Level 1 except as specified below.
    BoundedPhysicsModel All fields fully supported.
    ParticleSystem All fields fully supported, except  "GEOMETRY" geometry type and the geometry field.
    SurfaceEmitter All fields fully supported.
    VolumeEmitter All fields fully supported.
3 Core 1
Grouping 1
Shape 1
Rendering 1
Texturing 1
   
    All Level 2 nodes All fields fully supported.
    ParticleSystem All fields fully supported.
--- X3D separator bar ---