ParticleSystemNode Class

SystemObject
DigitalRune.Graphics.SceneGraphSceneNode
DigitalRune.Graphics.SceneGraphParticleSystemNode

public class ParticleSystemNode : SceneNode

Public Class ParticleSystemNode
	Inherits SceneNode

public ref class ParticleSystemNode : public SceneNode

type ParticleSystemNode =  
    class
        inherit SceneNode
    end

	Name	Description
	ParticleSystemNode	Initializes a new instance of the ParticleSystemNode class.

Top

	Name	Description
	Clone	Creates a new SceneNode that is a clone of the current instance (incl. all children).
	CloneCore	Makes the instance a clone (deep copy) of the specified SceneNode. (Overrides SceneNodeCloneCore(SceneNode).)
	CreateInstanceCore	When implemented in a derived class, creates a new instance of the SceneNode derived class. (Overrides SceneNodeCreateInstanceCore.)
	Dispose(Boolean)	Releases all resources used by the scene node and all descendant nodes. (Inherited from SceneNode.)
	Dispose(Boolean, Boolean)	Releases the unmanaged resources used by an instance of the SceneNode class and optionally releases the managed resources. (Inherited from SceneNode.)
	Equals	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	Invalidate	Invalidates this scene node and all children. (Inherited from SceneNode.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	OnParentChanged	Called when Parent was changed. (Inherited from SceneNode.)
	OnPoseChanged	Raises the PoseChanged event. (Inherited from SceneNode.)
	OnSceneChanged	Raises the SceneChanged event. (Inherited from SceneNode.)
	OnShapeChanged	Raises the ShapeChanged event. (Inherited from SceneNode.)
	Synchronize	Synchronizes the graphics data with the particle system data. (Needs to be called once per frame!)
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

	Name	Description
	ClearLastPose	Clears the LastPoseWorld property of the current scene node (and its descendants). (Defined by SceneHelper.)
	ClearLastScale	Clears the LastScaleWorld property of the current scene node (and its descendants). (Defined by SceneHelper.)
	Contains	Determines whether whether a scene node contains another scene node in its subtree. (Defined by SceneHelper.)
	GetAncestors	Gets the ancestors of the given scene node. (Defined by SceneHelper.)
	GetChildren	Gets the children of the given scene node. (Defined by SceneHelper.)
	GetDescendants	Overloaded. Gets the descendants of the given scene node using a depth-first search. (Defined by SceneHelper.)
	GetDescendants(Boolean)	Overloaded. Gets the descendants of the given scene node using a depth-first or a breadth-first search. (Defined by SceneHelper.)
	GetLeaves	Gets the leaves of the scene node. (Defined by SceneHelper.)
	GetRoot	Gets the root node. (Defined by SceneHelper.)
	GetSceneNode	Gets a scene node by name from the subtree of the specified scene node. (Defined by SceneHelper.)
	GetSelfAndAncestors	Gets the scene node and its ancestors scene. (Defined by SceneHelper.)
	GetSubtree	Overloaded. Gets the subtree (the given scene node and all of its descendants) using a depth-first search. (Defined by SceneHelper.)
	GetSubtree(Boolean)	Overloaded. Gets the subtree (the given scene node and all of its descendants) using a depth-first or a breadth-first search. (Defined by SceneHelper.)
	GetSubtreeAabb	Gets the AABB of the current subtree. (Defined by SceneHelper.)
	LookAt(Vector3F, Vector3F)	Overloaded. Rotates the scene node so that it faces a certain direction (in world space). (Defined by SceneHelper.)
	LookAt(Vector3F, Vector3F, Vector3F)	Overloaded. Moves and rotates the scene node so that it faces a certain direction (in world space). (Defined by SceneHelper.)
	SetInstanceAlpha	Sets the opacity (alpha) of a scene node - see remarks. (Defined by SceneHelper.)
	SetLastPose	Sets LastPoseWorld to the current PoseWorld. (Defined by SceneHelper.)
	SetLastScale	Sets LastScaleWorld to the current ScaleWorld. (Defined by SceneHelper.)
	SupportsInstanceAlpha	Determines whether the opacity of the scene node can be changed using SetInstanceAlpha(SceneNode, Single). (Defined by SceneHelper.)

Top

	Name	Description
	Aabb	Gets the axis-aligned bounding box (AABB) in world space. (Inherited from SceneNode.)
	ActualIsEnabled	Gets a value indicating whether this scene node is actually enabled. (The method checks the current scene node and its ancestors.) (Inherited from SceneNode.)
	Alpha	Gets or sets the opacity (alpha) of the particle system instance.
	AngleOffset	Gets or sets the rotation offset which is added to all particles.
	CastsShadows	Gets or sets a value indicating whether this scene node blocks the light and casts shadows. (Inherited from SceneNode.)
	Children	Gets or sets the children of this scene node. (Inherited from SceneNode.)
	Color	Gets or sets the tint color of the particle system instance.
	IsDisposed	Gets a value indicating whether this scene node has been disposed of. (Inherited from SceneNode.)
	IsEnabled	Gets or sets a value indicating whether this scene node is enabled. (May override children - see remarks.) (Inherited from SceneNode.)
	IsRenderable	Gets or sets a value indicating whether this scene node can be rendered with a SceneNodeRenderer. (Inherited from SceneNode.)
	IsShadowCasterCulled	Gets or sets a value indicating whether the occlusion culling determined that this scene node does not need to be rendered into the shadow map of the directional light. (Inherited from SceneNode.)
	IsStatic	Gets or sets a value indicating whether this scene node is static (immobile). (Inherited from SceneNode.)
	LastFrame	Gets or sets the number of the last frame in which the scene node was rendered. (Inherited from SceneNode.)
	LastPoseWorld	Gets or sets the PoseWorld of the last frame. (Inherited from SceneNode.)
	LastScaleWorld	Gets or sets the ScaleWorld of the last frame. (Inherited from SceneNode.)
	MaxDistance	Gets or sets the maximum distance up to which the scene node is rendered. (Needs to be normalized - see remarks.) (Inherited from SceneNode.)
	Name	Gets or sets the name of this scene node. (Inherited from SceneNode.)
	Parent	Gets the parent scene node. (Inherited from SceneNode.)
	ParticleSystem	Gets or sets the particle system.
	PoseLocal	Gets or sets the pose (position and orientation) relative to the parent scene node. (Inherited from SceneNode.)
	PoseWorld	Gets or sets the pose (position and orientation) in world space. (Inherited from SceneNode.)
	Proxy	Gets or sets the proxy node. (Inherited from SceneNode.)
	RenderData	Gets or sets the cached renderer data. (Inherited from SceneNode.)
	ScaleLocal	Gets or sets the scale relative to the parent scene node. (Inherited from SceneNode.)
	ScaleWorld	Gets the total effective scale (which incorporates the scale factors of parent scene nodes). (Inherited from SceneNode.)
	SceneData	Gets or sets scene data. (Inherited from SceneNode.)
	Shape	Gets (or sets) the bounding shape of this scene node. (Inherited from SceneNode.)
	SortTag	Gets or sets the sort tag. (Inherited from SceneNode.)
	UserData	Gets or sets user-defined data. (Inherited from SceneNode.)
	UserFlags	Gets or sets a 16-bit value which can be used to store user-defined information or flags. (Inherited from SceneNode.)

Top

	Name	Description
	SceneChanged	Occurs when the local subtree changed. (Inherited from SceneNode.)
	ShapeChanged	Occurs when the Shape or ScaleWorld was changed. (Inherited from SceneNode.)

Top

	Name	Description
	IDisposableDispose	Releases all resources used by the scene node and all descendant nodes. (Inherited from SceneNode.)
	IGeometricObjectClone	Creates a new IGeometricObject that is a clone (deep copy) of the current instance. (Inherited from SceneNode.)
	IGeometricObjectPose	Gets the pose (position and orientation) in world space. (Inherited from SceneNode.)
	IGeometricObjectPoseChanged	Occurs when the pose was changed. (Inherited from SceneNode.)
	IGeometricObjectScale	Gets the total effective scale (which incorporates the scale factors of parent scene nodes). (Inherited from SceneNode.)

Top

The ParticleSystemNode positions a ParticleSystem in a 3D scene. Particles can be rendered using the BillboardRenderer. Only particle system that have the required particle parameters are rendered. See list below.

Important
Synchronization: The particle system service (which simulates the particle motion) and the graphics service (which draws particles) may be run in sequence or in parallel. In every frame the particle information needs to be copied from the ParticleSystem to the ParticleSystemNode. This is done by calling Synchronize(IGraphicsService). This method needs to be called by the application logic for each ParticleSystemNode! (It needs to be called at a point where the particle system service and the graphics service are idle - usually when the game objects are updated.)

Important

Synchronization: The particle system service (which simulates the particle motion) and the graphics service (which draws particles) may be run in sequence or in parallel. In every frame the particle information needs to be copied from the ParticleSystem to the ParticleSystemNode. This is done by calling Synchronize(IGraphicsService). This method needs to be called by the application logic for each ParticleSystemNode! (It needs to be called at a point where the particle system service and the graphics service are idle - usually when the game objects are updated.)

Note that both the particle system and the scene node have an "Enabled" flag. The ParticleSystem's Enabled flag determines whether the particle system is simulated by the particle system manager. If the particle system is disabled, particles are no longer emitted or updated. The ParticleSystemNode's IsEnabled flag determines whether the scene node is rendered.

Particle Reference Frame and Instancing:
The ReferenceFrame defines the reference frame of the particles.

World means that the particles are positioned directly in world space. In this case the pose (position and orientation) of the particle system controls the pose of the scene node. In Synchronize(IGraphicsService) the Pose of the ParticleSystem is copied to PoseWorld of the ParticleSystemNode.

Local means that the particles are relative to the scene node. Multiple instance of the same particle system may be positioned and rendered within the scene. Particles can be scaled, rotated, or moved by changing the ScaleLocal or PoseLocal of the ParticleSystemNode. The properties ScaleLocal, Color, Alpha, and AngleOffset can be used to add variety to the instances of a particle system.

Bounding Shape:
The Shape of the ParticleSystem is used for frustum culling. The Shape is not currently not updated automatically. It is recommended to set a shape which is large enough to hold all particles. The Shape must not be changed while the graphics service is rendering the scene!

Nested Particle Systems:
A particle system may include other particle systems. Only the root particle system needs to be added to the scene using a ParticleSystemNode. The BillboardRenderer automatically renders all nested particle systems that have the required particle parameters. The Shape needs to be large enough to include all nested particle systems.

Particle Parameters
The following particle parameters are read by the BillboardRenderer.

Parameter Name	Description
Alpha	The particle opacity (0 = transparent, 1 = opaque). Parameter type: varying or uniform, value type: Single This parameter is optional.
Angle	The rotation angle in radians. Parameter type: varying or uniform, value type: Single This parameter is optional.
AlphaTest	The reference value used in the alpha test. The reference value is a value in the range [0, 1]. If the alpha of a pixel is less than the reference alpha, the pixel is discarded. (Requires HiDef profile, not supported in Reach profile) Parameter type: uniform, value type: Single This parameter is optional.
AnimationTime	The normalized animation time where 0 marks the start of the animation and 1 marks the end of the animation. Only relevant if the particle texture contains multiple animation frames. The normalized animation time determines the current frame. Parameter type: varying or uniform, value type: Single This parameter is optional.
Axis	The axis vector of a particle. Parameter type: varying or uniform, value type: Vector3F This parameter is optional.
BillboardOrientation	The billboard orientation of the particles. Parameter type: uniform, value type: BillboardOrientation This parameter is optional.
BlendMode	The blend mode of the particles where 0 = additive blending, 1 = alpha blending. Intermediate values between 0 and 1 are allowed. Parameter type: varying or uniform, value type: Single This parameter is optional.
Color	The particle tint color. Parameter type: varying or uniform, value type: Vector3F This parameter is optional.
DrawOrder	A value that defines the draw order for particle systems on the same world space position. Particle systems with higher draw order are drawn on top of particle systems with lower draw order. Parameter type: uniform, value type: Int32 This parameter is optional.
IsDepthSorted	A parameter that defines if particles should be drawn back to front or oldest to newest. If this parameter is or absent, the particles are drawn from oldest to newest. Parameter type: uniform, value type: Boolean This parameter is optional.
Normal	The normal vector of a particle. Parameter type: varying or uniform, value type: Vector3F This parameter is optional.
NormalizedAge	The normalized age in the range [0, 1]. This parameter is automatically created and managed by the ParticleSystem class. Parameter type: varying, value type: Single This parameter is optional.
Position	The particle position. Parameter type: varying, value type: Vector3F This parameter is optional.
Size, SizeX, SizeY	The particle size. The size can be defined using a single parameter (Size), or using different parameters for width (SizeX) and height (SizeY). Parameter type: varying or uniform, value type: Single This parameter is optional.
Softness	The softness for rendering soft particles: Regular particles are rendered as flat billboards, which create hard edges when they intersect with other geometry in the scene. Soft particles have a volume and create soft transitions when they intersect with other geometry. Parameter type: varying, value type: Single 0 ... Disabled: The particles are rendered with hard edges. -1 or NaN ... Automatic: The thickness of the particle is determined automatically. >1 ... Manual: The value defines the thickness of the particle (= soft particle distance threshold). This parameter is optional.
Texture	The particle texture (using premultiplied alpha). Parameter type: uniform, value type: PackedTexture or Texture2D This parameter is required!
TextureTiling	For ribbons: Defines how a texture is applied to a particle ribbon ("tiling distance"). Parameter type: uniform, value type: Int32 0 ... No tiling: The texture is stretched along the ribbon. 1 ... Tiling: The texture is repeated every particle. n ... Tiling with lower frequency: The texture is repeated every n particles. This parameter is optional.
Type	The type of the particles, which determines whether particles are rendered as individual billboards or connected quad strips ("ribbons"). Parameter type: uniform, value type: ParticleType This parameter is optional.

Particle Ribbons (a.k.a. "Beams", "Lines", "Trails"):
When the particle system has a uniform particle parameter "Type" set to Ribbon then subsequent living particles are connected and rendered as ribbons (quad strips). At least two living particles are required to create a ribbon. Dead particles ("NormalizedAge" ≥ 1) can be used as delimiters to terminate one ribbon and start the next ribbon.

The "Position" parameter defines the points along the ribbon curve. The "Axis" parameter can be set to define the orientation of the ribbon. The axis needs to be normal to the ribbon curve (i.e. the axis does not point into the ribbon direction).

The uniform "TextureTiling" parameter defines how the texture is applied to the ribbon. If the value is 0 the texture is stretched along the ribbon curve where the texture coordinate u = 0 is mapped to the start and u = 1 is mapped to the end of the ribbon. If the "TextureTiling" value is 1 the texture is repeated at every particle (= point along the ribbon curve). If the "TextureTiling" is n, where n > 1, then the texture is repeated every n particles.

Cloning:
When a ParticleSystemNode is cloned the ParticleSystem is not duplicated. The ParticleSystem is copied by reference (shallow copy). The original ParticleSystemNode and the cloned instance will reference the same ParticleSystem object.

Reference

DigitalRune.Graphics.SceneGraph Namespace