Click or drag to resize
DigitalRuneParticleSystem Class
Represents a system of particles.
Inheritance Hierarchy
SystemObject
  DigitalRune.ParticlesParticleSystem

Namespace: DigitalRune.Particles
Assembly: DigitalRune.Particles (in DigitalRune.Particles.dll) Version: 1.4.0.0 (1.4.1.14427)
Syntax
public class ParticleSystem : IGeometricObject, 
	IAnimatableObject, INamedObject

The ParticleSystem type exposes the following members.

Constructors
  NameDescription
Public methodParticleSystem
Initializes a new instance of the ParticleSystem class.
Top
Methods
  NameDescription
Public methodAddParticles(Int32)
Creates a number of new particles.
Public methodAddParticles(Int32, Object)
Creates a number of new particles from the specified emitter.
Public methodClone
Creates a new ParticleSystem that is a clone of the current instance.
Protected methodCloneCore
Makes the instance a clone (deep copy) of the specified ParticleSystem.
Protected methodCreateInstanceCore
When implemented in a derived class, creates a new instance of the ParticleSystem derived class.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Protected methodOnPoseChanged
Raises the PoseChanged event.
Protected methodOnReset
Protected methodOnShapeChanged
Raises the ShapeChanged event.
Protected methodOnUpdate
Called when Update(TimeSpan) was called.
Public methodReset
Resets the particle system to its initial state. All particle states are cleared.
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodUpdate
Advances the state of the particle system.
Top
Extension Methods
  NameDescription
Public Extension MethodGetPoseWorld
Gets the world space pose of the particle system, which is obtained by concatenating the poses of the given and all parent particle systems.
(Defined by ParticleHelper.)
Public Extension MethodIsAlive
Determines whether the specified particle system is alive.
(Defined by ParticleHelper.)
Top
Properties
  NameDescription
Public propertyAabb
Gets the axis-aligned bounding box (AABB).
Public propertyChildren
Gets or sets the collection of child particle systems.
Public propertyCurrentDelay
Gets or sets the current delay.
Public propertyEffectors
Gets the particle effectors.
Public propertyEnabled
Gets or sets a value indicating whether this ParticleSystem is enabled.
Public propertyEnableMultithreading
Gets or sets a value indicating whether multithreading is enabled.
Public propertyInitialDelay
Gets or sets the initial delay.
Public propertyMaxNumberOfParticles
Gets the maximum number of particles.
Public propertyName
Gets the name of this particle system.
Public propertyNumberOfActiveParticles
Gets the number of active particles.
Public propertyNumberOfLivingParticles
Gets the number of living particles.
Public propertyParameters
Gets the particle parameters.
Public propertyParent
Gets the parent particle systems.
Public propertyParticleStartIndex
Gets index of the first active particle in the particle parameter arrays.
Public propertyPose
Gets or sets the pose (position and orientation) of the particle system relative to the Parent or the world.
Public propertyPreloadDeltaTime
Gets or sets the preload delta time.
Public propertyPreloadDuration
Gets or sets the preload duration.
Public propertyRandom
Gets or sets the random number generator used by the particle system.
Public propertyReferenceFrame
Gets or sets which 3D reference frame is used for particle parameters and particle effector properties.
Public propertyRenderData
Gets or sets the render data.
Public propertyService
Gets the particle system service.
Public propertyShape
Gets or sets the bounding shape of the particle system.
Public propertyTime
Gets the simulation time of the particle system.
Public propertyTimeScaling
Gets or sets the time scaling.
Public propertyUserData
Gets or sets the user data.
Top
Events
  NameDescription
Public eventPoseChanged
Occurs when the Pose was changed.
Public eventShapeChanged
Occurs when the Shape or Scale was changed.
Top
Explicit Interface Implementations
Remarks

For general information about particle systems, see http://en.wikipedia.org/wiki/Particle_system

Particle Parameters:
Normally, particle systems use a "Particle" class to store the state of a particle, and all "Particle" instances are stored in an array. This Array of Structures (AoS) approach has the disadvantages that the particle parameters are hard-coded as the properties of the Particle class. For example, the Particle class could contain the properties "Position", "Direction", "Speed", "Size". If a new particle effector wants to store the property "Mass" with the particle, an new "Particle" class has to be defined. And if all particles in a specific particle system should have the same size, then it is a waste of memory to store "Size" per particle.

The DigitalRune Particle System uses a different approach. Particle data is stored in a set of separate arrays. This is a Structure of Arrays (SoA) approach. Further, each particle system can decide if a specific particle parameter is constant for all particles (uniform particle parameters), or if each particle can have a different parameter value (varying particle parameters). For example: In a smoke particle system, the particle parameter "Color" will be uniform - all particles use the same color (e.g brown for a dirt cloud effect). In a fireworks particle system, the particle parameter "Color" will be varying to give each particle a unique color to create a colorful effect.

The ParticleSystem has a property Parameters which manages a collection of IParticleParameterT instances. Each particle parameter has a default value and an optional array. If the particle parameter is uniform, only the DefaultValue is used and the Values array is . If the particle parameter is varying, the Values is used and its length is equal to MaxNumberOfParticles. MaxNumberOfParticles defines the number of particles that can be alive at any given time in the particle system. The particle parameter arrays are used like a circular buffer. The ParticleStartIndex defines the array element that contains the first active particle. The current number of active particles is stored in NumberOfActiveParticles.

Particle Age and Lifetime:
The ParticleSystem itself defines and manages only one particle parameter: "NormalizedAge". (All other particle parameters, like "Position", "Color", "Size", "Alpha", etc., must be manually added when needed. ParticleEffectors must be used to initialize and update these particle parameters.)

This "NormalizedAge" parameter is varying and stores the relative lifetime of each particle. New particles have a normalized age of 0. If the normalized age is equal to or greater than 1, the particle is dead. Per default, all particles live 3 seconds, but you can add a uniform or varying particle parameter "Lifetime" to change the lifetime or to give each particle an individual lifetime (measured in seconds).

Killing Particles:
Particles can be killed by setting their "NormalizedAge" to 1 or higher. Dead particles are usually ignored by particle systems and their effectors. But the space is not immediately freed. Particles are created and removed in a first-in-first-out order. That means, in order to free up space for new particles the oldest particles need to be killed first.

Particle Effectors:
A particle system manages a set of ParticleEffectors (see property Effectors). These objects define the behavior of the particle system. A particle effector can manipulate the particle system, create particles, or change the particle parameters. See ParticleEffector for more information.

Child Particle Systems:
A particle system can own other particle systems (see property Children). This allows to create complex layered particle system. For instance, an explosion effect that combines smoke, fire and debris particle systems.

Creating a Particle System:
To create the particle system: Add the required particle parameters to the Parameters collection. Then add the particle effectors that define the behavior of particle system to the Effectors collection. - It is also possible to clone an existing particle system as described below.

Using a Particle System:
To use a configured particle system, you only have to call Update(TimeSpan) once per frame. Particle systems can be added to an IParticleSystemService, in which case the particle system service updates the particle system automatically. (Child particle systems, which are owned by another particle system, are also updated automatically.)

Rendering a Particle System:
The particle system does not draw itself because rendering functionality is application and graphics-engine specific. The particle system only manages the particle data.

IAnimatableObject:
The ParticleSystem implements IAnimatableObject. All uniform particle parameters of a particle system are IAnimatablePropertys. That means they can be animated using DigitalRune Animation.

Cloning:
The ParticleSystem can be cloned. When a clone is created using Clone, the whole particle system including the particle parameters, particle effectors and child particle systems is cloned. The returned particle system is in its initial state, which means the runtime state of particle system and the particle states are never copied - each clone starts at Time 0 with no particles.

The properties Random, RenderData and UserData are not copied.

IGeometricObject:
The ParticleSystem implements IGeometricObject, which means the particle system has a Pose, and a Shape. These properties are not used by the particle system class itself. The Pose can be used to position the particle system in a 3D world or relative to its parent system. The Shape can be used as the bounding shape for frustum culling. (Please note: The default shape is an InfiniteShape. A better shape should be chosen and updated manually.)

See Also