DPSF<Particle, Vertex>
The Base Particle System Framework Class.
This class contains the methods and properties needed to keep track of, update, and draw Particles
Class to hold all of the Particle Events
Class to hold all of the Particle System Events and related info
The function prototype that the Particle Initialization Functions must follow
The function prototype that the Particle Events must follow
The function prototype that Particle System Events must follow
The function prototype that the Vertex Update Functions must follow
Get / Protected Set a Linked List whose Nodes point to the Active Particles.
NOTE: New particles are added to the start of the Active Particles list, so by default the oldest particles should be at the end.
NOTE: The Protected Set option is only provided to allow the order of the LinkedListNodes to be changed, changing the update and drawing
order of the Particles. Be sure that all of the original LinkedListNodes (and only the original LinkedListNodes, no more) obtained from the
Get are included; they may only be rearranged. If they are not, there may (and probably will) be unexpected results.
The Settings used to control the Automatic Memory Manager
Get the Name of the Class that this Particle System is using. This can be used to
check what type of Particle System this is at run-time.
Get / Set the Content Manager to use to load Textures and Effects
The path used to load the Effect when the InitializeNonSerializableProperties() function is called.
NOTE: This is automatically set when the SetEffectAndTechnique(string, string) function is called.
The Name of the Technique to use when the InitializeNonSerializableProperties() function is called.
NOTE: This is automatically set when the SetEffectAndTechnique() and SetTechnique() functions are called.
The path used to load the Texture when the InitializeNonSerializableProperties() function is called.
NOTE: This is automatically set when the SetTexture() function is called.
A custom effect provided by DPSF. In DPSF v2.1.0 and prior this effect was used as the default effect for all particle system types.
Each particle system type now uses one of the built-in XNA 4 effects as its default effect in order to make all of the particle system types
fully compatible with the Reach profile, and usable on the Windows Phone 7.
This effect may still be used for a particle system by calling the SetEffectAndTechnique() function from the particle system's overridden
InitializeRenderProperties() function.
This Effect has several techniques that may be used ( DPSFDefaultEffectTechniques).
The Order in which the Particle System should be Drawn relative to other
DPSF Particle Systems in the same Particle System Manager. Particle Systems
are Drawn in ascending order according to their Draw Order (i.e. lowest first).
NOTE: The Draw Order is one of the few properties that is not reset when
the particle system is initialized or destroyed.
public Effect Effect {
get;
set; }
Get / Set the Effect to use to draw the Particles
The Emitter is used to automatically generate new Particles.
NOTE: This is just a pointer to one of the ParticleEmitters in the Emitters ParticleEmitterCollection.
NOTE: If you set this to a ParticleEmitter that is not in the Emitters collection, it will be added to it.
During the particle system Update() this Emitter property is updated to point to the ParticleEmitter in the Emitters collection that is being updated.
This allows you to use this property to reference the ParticleEmitter that is actually being used to add particles to the particle system.
The Emitters used to automatically generate new Particles for this Particle System.
Each particle system Update() will loop through all Emitters in this collection and add their new particles to this particle system.
During the particle system Update() the Emitter property is updated to point to the ParticleEmitter in this collection that is being updated.
Get / Set if this Particle System should Update itself and its Particles or not.
NOTE: Setting this to false causes the Update() function to not update anything, including the
BeforeUpdate() and AfterUpdate() function not to be called.
public Game Game {
get; }
Get the Game object set in the constructor, if one was given.
Get / Set the Graphics Device to draw to
Get the unique ID of this Particle System.
NOTE: Each Particle System is automatically assigned a unique ID when it is instanciated.
Returns a Linked List whose Nodes point to the Inactive Particles
Get / Set the 32-bit Index Buffer values.
The Index Buffer is typically used when drawing Quads in the HiDef profile (except with MonoGame WinRT, which uses HiDef but only supports IndexBufferShort).
Get / Set the current position in the Index Buffer
Get / Set the 16-bit Index Buffer values.
The Index Buffer Short is typically used when drawing Quads in the Reach profile.
Get if the Particle System is inheriting from DrawableGameComponent or not.
If inheriting from DrawableGameComponent, the Particle Systems
are automatically added to the given Game object's Components and the
Update() and Draw() functions are automatically called by the
Game object when it updates and draws the rest of its Components.
If the Update() and Draw() functions are called by the user anyways,
they will exit without performing any operations, so it is suggested
to include them anyways to make switching between inheriting and
not inheriting from DrawableGameComponent seemless; just be aware
that the updates and draws are actually being performed when the
Game object is told to update and draw (i.e. when base.Update() and base.Draw()
are called), not when these functions are being called.
Get / Set how fast the Particle System Simulation should run to look "normal".
1.0 = normal speed, 0.5 = half speed, 2.0 = double speed.
This is provided as a way of speeding up / slowing down the simulation to have
it look as desired, without having to rescale all of the particle velocities, etc. This allows
you to use the exact same particle system class to create two particle systems, and then have one run
slower or faster than the other, creating two different effects. If you then wanted to speed up or slow down
both effects (i.e. particle systems), you could adjust the SimulationSpeed property on both particle systems
without having to worry about adjusting this property at all to get the effects back to normal speed; just reset
the SimulationSpeed property you changed back to 1.0.
NOTE: If a negative value is specified, the Internal Simulation Speed is set to zero
(pauses the simulation; has the same effect as Enabled = false).
Returns true if the Particle System is Initialized, false if not.
Get if we will be using the regular 32-bit Index Buffer (Integer) or the 16-bit Index Buffer (Short).
Get / Set the Max Number of Particles this Particle System is Allowed to contain at any given time.
NOTE: The Automatic Memory Manager will never allocate space for more Particles than this.
NOTE: This value must be greater than or equal to zero.
Get the number of Particles that are currently Active.
Get / Set the absolute Number of Particles to Allocate Memory for.
NOTE: This value must be greater than or equal to zero.
NOTE: Even if this many particles aren't used, the space for this many Particles
is still allocated in memory.
Get the number of Particles being Drawn. That is, how many Particles are both Active AND Visible.
Get the number of Particles that may still be added before reaching the
Max Number Of Particles Allowed. If the Max Number Of Particles Allowed is
greater than the Number Of Particles Allocated In Memory AND the Auto Memory Manager is
set to not increase the amount of Allocated Memory, than this returns the number
of Particles that may still be added before running out of Memory.
Particle Events may be used to update Particles
Returns the array of all Particle objects
Particle System Events may be used to update the Particle System
The Particle System Manager whose properties (SimulationSpeed and
UpdatesPerSecond) this particle system should follow. If null is not specified,
the Manager's properties will be copied into this particle system immediately.
NOTE: This Particle System's properties will only clone the Manager's properties
if the Manager's properties are Enabled. For example, the Manager's SimulationSpeed
will only be copied to this Particle System if the Manager's SimulationSpeedIsEnabled
property is true.
NOTE: This value is automatically set to the last Particle System Manager the
Particle System is added to.
Get the type of Particles that this Particle System should draw.
Get / Set if performance timings should be measured or not, such as how long it takes to perform updates and draws.
This should be disabled before building a release version of your application.
Note: Performance profiling is not available on the Reach profile, so this will always return False on the Reach profile.
Get how long (in milliseconds) it took to perform the last Draw() function call.
Returns 0 if Performance Profiling is not Enabled.
Get how long (in milliseconds) it took to perform the last Update() function call.
Returns 0 if Performance Profiling is not Enabled.
Get / Set the Projection Matrix to use for drawing 3D Particles
Get a RandomNumbers object used to generate Random Numbers
Get the render properties used to draw the particles.
Get / Set how fast the Particle System Simulation should run.
Example: 1.0 = normal speed, 0.5 = half speed, 2.0 = double speed.
NOTE: If a negative value is specified, the Speed Scale is set
to zero (pauses the simulation; has same effect as Enabled = false).
Returns the SpriteBatch used to draw the Sprite particles.
NOTE: If this is not a Sprite particle system, this will return null.
The Sprite Batch drawing Settings used in the Sprite Batch's Begin() function call.
NOTE: These settings are only available for Sprite particle systems, and only for
the Sprite particle systems using their own SpriteBatch (i.e. UsingExternalSpriteBatchToDrawParticles = false).
public EffectTechnique Technique {
get;
set; }
Get / Set which Technique of the current Effect to use to draw the Particles
public Texture2D Texture {
get;
set; }
Get / Set the Texture to use to draw the Particles
Get the number of particles that are currently Active, in both this particle system and any particle systems contained within this one.
NOTE: Because a particle system may contain other particle systems, this is a virtual function that may be overridden to return the
NumberOfActiveParticles for both this particle system and any child particle systems that are contained within this one.
NOTE: By default this just returns this particle system's NumberOfActiveParticles.
Get the number of particles that memory has been allocated for, for both this particle system and any particle systems contained within this one.
NOTE: Because a particle system may contain other particle systems, this is a virtual function that may be overridden to return the
NumberOfParticlesAllocatedInMemory for both this particle system and any child particle systems that are contained within this one.
NOTE: By default this just returns this particle system's NumberOfParticlesAllocatedInMemory.
Get the number of particles that are being Drawn, in both this particle system and any particle systems contained within this one.
NOTE: Because a particle system may contain other particle systems, this is a virtual function that may be overridden to return the
NumberOfParticlesBeingDrawn for both this particle system and any child particle systems that are contained within this one.
NOTE: By default this just returns this particle system's NumberOfParticlesBeingDrawn.
public int Type {
get;
set; }
Get / Set the Type of Particle System this is. This is a user provided value that you can use for whatever
purpose you want; it is not used by the built-in DPSF functionality in any way.
The Order in which the Particle System should be Updated relative to other
DPSF Particle Systems in the same Particle System Manager. Particle Systems
are Updated in ascending order according to their Update Order (i.e. lowest first).
NOTE: The Update Order is one of the few properties that is not reset when
the particle system is initialized or destroyed.
Specify how often the Particle System should be Updated.
NOTE: Specifying a value of zero (default) will cause the Particle
System to be Updated every time the Update() function is called
(i.e. as often as possible).
NOTE: If the Update() function is not called often enough to
keep up with this specified Update rate, the Update function
updates the Particle Systems as often as possible.
Returns if this particle system is dependent on an external Sprite Batch to draw its particles or not.
If false, the particle system will use its own SpriteBatch to draw its particles.
If true, then you must call SpriteBatch.Begin() before calling ParticleSystem.Draw() to
draw the particle system, and then call SpriteBatch.End() when done drawing the particle system, where
the SpriteBatch referred to here is the one you passed into the InitializeSpriteParticleSystem() function.
NOTE: This property only applies to Sprite particle systems.
public Matrix View {
get;
set; }
Get / Set the View Matrix to use for drawing 3D Particles
Get / Set if this Particle System should Draw its Particles or not.
NOTE: Setting this to false causes the Draw() function to not draw anything, including the
BeforeDraw() and AfterDraw() functions not to be called.
public Matrix World {
get;
set; }
Get / Set the World Matrix to use for drawing 3D Particles
Gets the result of multiplying the World, View, and Projection matrices.
Raised when the DrawOrder property changes
Raised when the Enabled property changes
Raised when the UpdateOrder property changes
Raised when the Visible property changes
Constructor
Adds a new Particle to the particle system, at the start of the Active Particle List.
This new Particle is initialized using the particle system's Particle Initialization Function
Adds a new Particle to the particle system, at the start of the Active Particle List. Returns true if
the Particle was added, false if there is not enough memory for another Particle.
Adds the specified number of new Particles to the particle system.
These new Particles are initialized using the particle system's Particle Initialization Function.
public int AddParticles(
int numberOfParticlesToAdd,
Particle particleToCopy)
Adds the specified number of new Particles to the particle system, copying the properties of the given Particle To Copy.
NOTE: The Particle Initialization Function is not called when copying from an existing particle.
Virtual function that is called at the end of the AddParticle() function.
This may be used to execute some code after a new Particle is initialized and added.
Virtual function that is called at the end of the Destroy() function.
This may be used to perform operations after the Particle System has been Destroyed, such as
to destroy other Particle Systems nested within this Particle System.
Virtual function that is called at the end of the Draw() function.
This may be used to perform operations after the Particle System has been drawn, such as
to Draw Particle Systems nested within this Particle System.
Virtual function that is called at the end of the Initialize() function.
This may be used to perform operations after the Particle System has been Initialized, such as
initializing other Particle Systems nested within this Particle System.
protected virtual void AfterUpdate(
float fElapsedTimeInSeconds)
Virtual function that is called at the end of the Update() function.
This may be used to perform operations after the Particle System has been updated, such as
to Update Particle Systems nested within this Particle System.
public virtual void AutoInitialize(
GraphicsDevice cGraphicsDevice,
ContentManager cContentManager,
SpriteBatch cSpriteBatch)
Virtual function to Initialize the Particle System with default values.
Particle system properties should not be set until after this is called, as
they are likely to be reset to their default values.
Virtual function that is called at the beginning of the AddParticle() function.
This may be used to execute some code before a new Particle is initialized and added.
Virtual function that is called at the beginning of the Destroy() function.
This may be used to perform operations before the Destroy() code is executed.
Virtual function that is called at the beginning of the Draw() function.
This may be used to perform operations before the Draw() code is executed.
protected virtual void BeforeUpdate(
float fElapsedTimeInSeconds)
Virtual function that is called at the beginning of the Update() function.
This may be used to perform operations before the Update() code is executed.
Release all resources used by the Particle System and reset all properties to their default values
Draws all of the Active Particles to the Graphics Device.
NOTE: This will only Draw the Particle System if it does not inherit from DrawableGameComponent,
since if it does it will be drawn automatically by the Game object.
Draws all of the Active Particles to the Graphics Device, even if the the Particle Systems inherits
from DrawableGameComponent.
NOTE: If inheriting from DrawableGameComponent and this is called, the Particle System will be drawn
twice per frame; once when it is called here, and again when automatically called by the Game object.
If not inheriting from DrawableGameComponent, this acts the same as calling Draw().
Virtual function to draw a Sprite Particle. This function should be used to draw the given
Particle with the provided SpriteBatch.
Initializes a new No Display Particle System. This type of Particle System does not allow any of the Particles
to be drawn to a Graphics Device (e.g. the screen).
This function should be called immediately after deserializing a particle system in order to reinitialize the properties
that could not be serialized.
NOTE: If this type of particle system requires a Texture, this function will attempt to load the Texture specified
by the DeserializationTexturePath property. If it is unable to load a texture, an DPSFArgumentNullException will be thrown, so
this function should be wrapped in a try block, and when an DPSFArgumentNullException is caught then the particle system's
texture should be manually set.
NOTE: This will attempt to load the Effect and Technique specified by the DeserializationEffectPath and
DeserializationTechniqueName properties. If either of these are null, the DPSFDefaultEffect will be used, and the default
Technique for this type of particle system will be loaded.
NOTE: Particle systems can only be serialized (and thus, deserialized) if not inheriting from DrawableGameComponent
(i.e. InheritsDrawableGameComponent == false. i.e. using the DPSF.dll, not DPSFAsDrawableGameComponent.dll).
Initialize the given Particle using the current Initialization Function
public void InitializeQuadParticleSystem(
GraphicsDevice cGraphicsDevice,
ContentManager cContentManager,
int iNumberOfParticlesToAllocateMemoryFor,
int iMaxNumberOfParticlesToAllow,
UpdateVertexDelegate<
Particle,
Vertex>
cVertexUpdateFunction)
Virtual function to setup the Render Properties (i.e. BlendState, DepthStencilState, RasterizerState, and SamplerState)
which will be applied to the Graphics Device before drawing the Particle System's Particles.
This function is only called once when initializing the particle system.
public void InitializeSpriteParticleSystem(
GraphicsDevice cGraphicsDevice,
ContentManager cContentManager,
int iNumberOfParticlesToAllocateMemoryFor,
int iMaxNumberOfParticlesToAllow,
string sTexture)
Initializes a new Sprite Particle System
public void InitializeSpriteParticleSystem(
GraphicsDevice cGraphicsDevice,
ContentManager cContentManager,
int iNumberOfParticlesToAllocateMemoryFor,
int iMaxNumberOfParticlesToAllow,
string sTexture,
SpriteBatch cSpriteBatchToDrawWith)
Initializes a new Sprite Particle System
public void InitializeSpriteParticleSystem(
GraphicsDevice cGraphicsDevice,
ContentManager cContentManager,
int iNumberOfParticlesToAllocateMemoryFor,
int iMaxNumberOfParticlesToAllow,
Texture2D cTexture)
Initializes a new Sprite Particle System
public void InitializeSpriteParticleSystem(
GraphicsDevice cGraphicsDevice,
ContentManager cContentManager,
int iNumberOfParticlesToAllocateMemoryFor,
int iMaxNumberOfParticlesToAllow,
Texture2D cTexture,
SpriteBatch cSpriteBatchToDrawWith)
Initializes a new Sprite Particle System
Moves the Active Particle's Linked List node to the Inactive Particle Linked List.
Removes all Active Particles from the Active Particle List and adds them
to the Inactive Particle List
Sets the Camera Position of the particle system, so that the particles know how to make themselves face the camera if needed.
This virtual function does not do anything unless overridden, and all it should do is set an internal Vector3 variable
(e.g. public Vector3 CameraPosition { get; set; }) to match the given Vector3.
Sets the Effect to be the default type for this type of particle system.
This is done automatically when the particle system is initialized.
Default effect for each particle type is:
NoDisplay and Sprite - null.Quad - BasicEffect.TexturedQuad - AlphaTestEffect.
Sets the Effect and Technique to use to draw the Particles.
NOTE: This will automatically set the DeserializationEffectPath property to the given sEffect.
NOTE: This will automatically set the DeserializationTechniqueName property to the given sTechnique.
Sets the Effect and Technique to use to draw the Particles.
NOTE: This will automatically set the DeserializationTechniqueName property to the given sTechnique.
Virtual function to Set the Effect's Parameters before drawing the Particles.
This is called every time before the particle system is drawn.
Sets the Graphics Device to use to the given graphics device.
NOTE: This only has an effect if the particle system does not inherit from DrawableGameComponent
(i.e. InheritsDrawableGameComponent == false. i.e. using the DPSF.dll, not DPSFAsDrawableGameComponent.dll), since
the Graphics Device is read-only when inheriting from DrawableGameComponent. The Game object's Graphics Device
is always used when inheriting from DrawableGameComponent.
Set which Technique of the current Effect to use to draw the Particles.
NOTE: This will automatically set the DeserializationTechniqueName property to the given sTechnique.
Set the Texture to use to draw the Particles
Set the World, View, and Projection matrices for this Particle System.
NOTE: Sprite particle systems are not affected by the World, View, and Projection matrices.
public void Update(
float fElapsedTimeInSeconds)
Updates the Particle System. This involves executing the Particle System
Events, updating all Active Particles according to the Particle Events, and
adding new Particles according to the Emitter settings.
NOTE: This will only Update the Particle System if it does not inherit from DrawableGameComponent,
since if it does it will be updated automatically by the Game object.
Updates the Particle System, even if the the Particle Systems inherits from DrawableGameComponent.
Updating the Particle System involves executing the Particle System Events, updating all Active
Particles according to the Particle Events, and adding new Particles according to the Emitter settings.
NOTE: If inheriting from DrawableGameComponent and this is called, the Particle System will be updated
twice per frame; once when it is called here, and again when automatically called by the Game object.
If not inheriting from DrawableGameComponent, this acts the same as calling Update().