C# Class Axiom.ParticleSystems.ParticleEmitter

Abstract class defining the interface to be implemented by particle emitters.

Particle emitters are the sources of particles in a particle system. This class defines the ParticleEmitter interface, and provides a basic implementation for tasks which most emitters will do (these are of course overridable). Particle emitters can be grouped into types, e.g. 'point' emitters, 'box' emitters etc; each type will create particles with a different starting point, direction and velocity (although within the types you can configure the ranges of these parameters).

Because there are so many types of emitters you could use, the engine chooses not to dictate the available types. It comes with some in-built, but allows plugins or games to extend the emitter types available. This is done by subclassing ParticleEmitter to have the appropriate emission behavior you want, and also creating a subclass of ParticleEmitterFactory which is responsible for creating instances of your new emitter type. You register this factory with the ParticleSystemManager using AddEmitterFactory, and from then on emitters of this type can be created either from code or through XML particle scripts by naming the type.

This same approach is used for ParticleAffectors (which modify existing particles per frame). This means that the engine is particularly flexible when it comes to creating particle system effects, with literally infinite combinations of emitter and affector types, and parameters within those types.

Inheritance: IConfigurable

Show file Open project: WolfgangSt/axiom Class Usage Examples

Protected Properties

Property	Type	Description
angle	float
colorFixed	ColorEx
colorRangeEnd	ColorEx
colorRangeStart	ColorEx
commandTable	AxiomCollection
direction	Vector3
durationFixed	float
durationMax	float
durationMin	float
durationRemain	float
emissionRate	float
emitted	bool
emittedEmitter	string
fixedSpeed	float
fixedTTL	float
isEnabled	bool
maxSpeed	float
maxTTL	float
minSpeed	float
minTTL	float
position	Vector3
remainder	float
repeatDelayFixed	float
repeatDelayMax	float
repeatDelayMin	float
repeatDelayRemain	float
startTime	float
type	string
up	Vector3

Public Methods

Method	Description
CopyTo ( ParticleEmitter emitter ) : void
GenerateConstantEmissionCount ( float timeElapsed ) : ushort	Utility method for generating an emission count based on a constant emission rate.
GetEmissionCount ( float timeElapsed ) : ushort	Gets the number of particles which this emitter would like to emit based on the time elapsed. For efficiency the emitter does not actually create new Particle instances (these are reused by the ParticleSystem as existing particles 'die'). The implementation for this method must return the number of particles the emitter would like to emit given the number of seconds which have elapsed (passed in as a parameter). Based on the return value from this method, the ParticleSystem class will call InitParticle once for each particle it chooses to allow to be emitted by this emitter. The emitter should not track these InitParticle calls, it should assume all emissions requested were made (even if they could not be because of particle quotas).
InitParticle ( Particle particle ) : void	Initializes a particle based on the emitter's approach and parameters. See the GetEmissionCount method for details of why there is a separation between 'requested' emissions and actual initialized particles.
Move ( float x, float y, float z ) : void
MoveTo ( float x, float y, float z ) : void
ParticleEmitter ( ParticleSystem ps ) : System	Default constructor.
ScaleVelocity ( float velocityMultiplier ) : void	Scales the velocity of the emitters by the float argument
SetDuration ( float min, float max ) : void	Sets the min/max duration range for this emitter.
SetParam ( string name, string val ) : bool

Protected Methods

Method	Description
GenerateEmissionColor ( ColorEx &color ) : void	Internal method for generating a color for a particle.
GenerateEmissionDirection ( Vector3 &dest ) : void	Utility method for generating particle exit direction
GenerateEmissionTTL ( ) : float	Utility method for generating a time-to-live for a particle.
GenerateEmissionVelocity ( Vector3 &dest ) : void	Utility method to apply velocity to a particle direction.
InitDurationRepeat ( ) : void
RegisterCommands ( ) : void	Registers all attribute names with their respective parser. Methods meant to serve as attribute parsers should use a method attribute to

Method Details

CopyTo() public method

public CopyTo ( ParticleEmitter emitter ) : void
emitter	ParticleEmitter
return	void

GenerateConstantEmissionCount() public method

Utility method for generating an emission count based on a constant emission rate.

public GenerateConstantEmissionCount ( float timeElapsed ) : ushort
timeElapsed	float
return	ushort

GenerateEmissionColor() protected method

Internal method for generating a color for a particle.

protected GenerateEmissionColor ( ColorEx &color ) : void
color	ColorEx	/// The color object that will be altered depending on the method of generating the particle color. ///
return	void

GenerateEmissionDirection() protected method

Utility method for generating particle exit direction

protected GenerateEmissionDirection ( Vector3 &dest ) : void
dest	Vector3	Normalized vector dictating new direction.
return	void

GenerateEmissionTTL() protected method

Utility method for generating a time-to-live for a particle.

protected GenerateEmissionTTL ( ) : float
return	float

GenerateEmissionVelocity() protected method

Utility method to apply velocity to a particle direction.

protected GenerateEmissionVelocity ( Vector3 &dest ) : void
dest	Vector3	The normalized vector to scale by a randomly generated scale between min and max speed.
return	void

GetEmissionCount() public abstract method

Gets the number of particles which this emitter would like to emit based on the time elapsed.

For efficiency the emitter does not actually create new Particle instances (these are reused by the ParticleSystem as existing particles 'die'). The implementation for this method must return the number of particles the emitter would like to emit given the number of seconds which have elapsed (passed in as a parameter).

Based on the return value from this method, the ParticleSystem class will call InitParticle once for each particle it chooses to allow to be emitted by this emitter. The emitter should not track these InitParticle calls, it should assume all emissions requested were made (even if they could not be because of particle quotas).

public abstract GetEmissionCount ( float timeElapsed ) : ushort
timeElapsed	float
return	ushort

InitDurationRepeat() protected method

protected InitDurationRepeat ( ) : void
return	void

InitParticle() public method

Initializes a particle based on the emitter's approach and parameters.

See the GetEmissionCount method for details of why there is a separation between 'requested' emissions and actual initialized particles.

public InitParticle ( Particle particle ) : void
particle	Particle	Reference to a particle which must be initialized based on how this emitter starts particles
return	void

Move() public method

public Move ( float x, float y, float z ) : void
x	float
y	float
z	float
return	void

MoveTo() public method

public MoveTo ( float x, float y, float z ) : void
x	float
y	float
z	float
return	void

ParticleEmitter() public method

Default constructor.

public ParticleEmitter ( ParticleSystem ps ) : System
ps	ParticleSystem
return	System

RegisterCommands() protected method

Registers all attribute names with their respective parser.

Methods meant to serve as attribute parsers should use a method attribute to

protected RegisterCommands ( ) : void
return	void

ScaleVelocity() public method

Scales the velocity of the emitters by the float argument

public ScaleVelocity ( float velocityMultiplier ) : void
velocityMultiplier	float
return	void

SetDuration() public method

Sets the min/max duration range for this emitter.

public SetDuration ( float min, float max ) : void
min	float
max	float
return	void

SetParam() public method

public SetParam ( string name, string val ) : bool
name	string
val	string
return	bool

Property Details

angle protected property

Angle around direction which particles may be emitted, internally radians but degrees for interface.

protected float angle
return	float

colorFixed protected property

Initial color of particles (fixed).

protected ColorEx colorFixed
return	ColorEx

colorRangeEnd protected property

Initial color of particles (range end).

protected ColorEx colorRangeEnd
return	ColorEx

colorRangeStart protected property

Initial color of particles (range start).

protected ColorEx colorRangeStart
return	ColorEx

commandTable protected property

protected AxiomCollection commandTable
return	AxiomCollection

direction protected property

Base direction of the emitter, may not be used by some emitters.

protected Vector3 direction
return	Vector3

durationFixed protected property

Length of time emitter will run for (0 = forever).

protected float durationFixed
return	float

durationMax protected property

Maximum length of time the emitter will run for (0 = forever).

protected float durationMax
return	float

durationMin protected property

Minimum length of time emitter will run for (0 = forever).

protected float durationMin
return	float

durationRemain protected property

Current duration remainder.

protected float durationRemain
return	float

emissionRate protected property

Rate in particles per second at which this emitter wishes to emit particles.

protected float emissionRate
return	float

emitted protected property

If 'true', this emitter is emitted by another emitter. NB. That doesn´t imply that the emitter itself emits other emitters (that could or could not be the case)

protected bool emitted
return	bool

emittedEmitter protected property

The name of the emitter to be emitted (optional)

protected string emittedEmitter
return	string

fixedSpeed protected property

Fixed speed of particles.

protected float fixedSpeed
return	float

fixedTTL protected property

Initial time-to-live of particles (fixed).

protected float fixedTTL
return	float

isEnabled protected property

Whether this emitter is currently enabled (defaults to true).

protected bool isEnabled
return	bool

maxSpeed protected property

Max speed of particles.

protected float maxSpeed
return	float

maxTTL protected property

Initial time-to-live of particles (max).

protected float maxTTL
return	float

minSpeed protected property

Min speed of particles.

protected float minSpeed
return	float

minTTL protected property

Initial time-to-live of particles (min).

protected float minTTL
return	float

position protected property

Position relative to the center of the ParticleSystem.

protected Vector3 position
return	Vector3

remainder protected property

protected float remainder
return	float

repeatDelayFixed protected property

Fixed time between each repeat.

protected float repeatDelayFixed
return	float

repeatDelayMax protected property

Maximum time between each repeat.

protected float repeatDelayMax
return	float

repeatDelayMin protected property

Minimum time between each repeat.

protected float repeatDelayMin
return	float

repeatDelayRemain protected property

Repeat delay left.

protected float repeatDelayRemain
return	float

startTime protected property

Start time (in seconds from start of first call to ParticleSystem to update).

protected float startTime
return	float

type protected property

Name of the type of emitter, MUST be initialized by subclasses.

protected string type
return	string

up protected property

Notional up vector, just used to speed up generation of variant directions.

protected Vector3 up
return	Vector3