DPSF 1.5.4 to 2.0.0

First off, DPSF versions prior to version 2.0.0.0 only work with XNA 3.1.  DPSF version 2.0.0.0 and higher use XNA 4.0.  This means that you can only use DPSF version 2.0.0.0 and higher in Visual Studio 2010 or greater.

1 - Point Sprite and Pixel particle system types are gone

XNA 4.0 removed Point Sprites and the PrimitiveType.PointList enumeration type, so DPSF can no longer support them either.  As such, the Point Sprite and Pixel particle system types have been removed from DPSF.  This means that the only particle types remaining in DPSF are Sprites (uses a SpriteBatch), Quads, Textured Quads, and No Display (not drawn to the screen).

1a - Converting a Point Sprite Particle System to a Textured Quad Particle System

If you were using a Point Sprite particle system, you will likely want to:

- change your particle systems from inheriting from the DefaultPointSpriteParticleSystem to instead inherit from the DefaultTexturedQuadParticleSystem.

- change the initialization function used to initialize the particle system class from InitializePointSpriteParticleSystem to InitializeTexturedQuadParticleSystem.

- change any instances of DefaultPointSpriteParticle to be DefaultTexturedQuadParticle.

- if you were using an event to trigger the UpdateParticleSizeUsingLerp function, change it to trigger the UpdateParticleWidthAndHeightUsingLerp function.

- if you were using particle rotation, you must change all of your previous float (i.e. scalar) rotation values to Vector3 rotation values.  To do this simply set the particle's rotation to be a new Vector3, supplying zero for the X and Y components, and the previous rotation float for the Z component (since rotations in 2D are always around the Z axis (i.e. roll rotations)).  The Orientation3D class also provides some 3D rotation helper functions if needed.

- add the following EveryTime event to your particle systems initialization:

ParticleEvents.AddEveryTimeEvent(UpdateParticleToFaceTheCamera, 200);

You may want to change the ExecutionOrder (i.e. 200) to something else if needed.  This event should fire after any events that affect the particles' rotation/orientation.

- coinciding with the above point, each time the particle system is updated you will want to let it know the Camera's new position so that it can rotate the particles to face the camera, giving the illusion that the quads are actually point sprites.  So before calling the ParticleSystem.Update() function, you will want to do:

mcParticleSystem.CameraPosition = sCameraPosition;

or if you are updating all of your particle systems at once using a Particle System Manager, then you will want to call the following function before calling the Particle System Manager's Update() function:

mcParticleSystemManager.SetCameraPositionForAllParticleSystems(sCameraPosition);

1b - Converting a Pixel Particle System to a Quad Particle System

If you were using a Pixel particle system, you will likely want to:

- change your particle systems from inheriting from the DefaultPixelParticleSystem to instead inherit from the DefaultQuadParticleSystem.

- change the initialization function used to initialize the particle system class from InitializePixelParticleSystem to InitializeQuadParticleSystem.

- change any instances of DefaultPixelParticle to be DefaultQuadParticle.

- set the particle Size in the Particle Initialization Function; this should likely be something small, such as 0.3f.

- add the following EveryTime event to your particle systems initialization:

ParticleEvents.AddEveryTimeEvent(UpdateParticleToFaceTheCamera, 200);

You may want to change the ExecutionOrder (i.e. 200) to something else if needed.  This event should fire after any events that affect the particles' rotation/orientation.

- coinciding with the above point, each time the particle system is updated you will want to let it know the Camera's new position so that it can rotate the particles to face the camera, giving the illusion that the quads are actually point sprites.  So before calling the ParticleSystem.Update() function, you will want to do:

mcParticleSystem.CameraPosition = sCameraPosition;

or if you are updating all of your particle systems at once using a Particle System Manager, then you will want to call the following function before calling the Particle System Manager's Update() function:

mcParticleSystemManager.SetCameraPositionForAllParticleSystems(sCameraPosition);

2 - Replaced InitializeRenderState() and ResetRenderState() virtual functions with InitializeRenderProperties()

XNA 4.0 drastically changed the way the rendering properties are setup, and DPSF changed as well to accommodate this.  The new philosophy in XNA 4.0 is that rather than changing the properties of the BlendState, DepthStencilState, RasterizerState, and SamplerState that the Graphics Device is using, you instead setup different instances of these objects and simply change the instance that the Graphics Device points to.  This means that each DPSF particle system now contains its own instance of each of these objects.  Before a DPSF particle system is drawn, it sets the Graphics Device to use its instances of the BlendState, DepthStencilState, RasterizerState, and SamplerState classes, which are all contained in the RenderProperties property of the DPSF particle system

Before drawing anything in XNA 4.0 it is also considered best practice to explicitly set the Graphics Device's render properties, so that you can be sure your objects will be drawn correctly.  Because of this, the ResetRenderState() function has been removed.  So it is your responsibility to reset the Graphics Device's render properties before drawing anything after a DPSF particle system has been drawn.

So in your code, what you need to change is:

- Replace the old overridden InitializeRenderState() function with the new overridden InitializeRenderProperties() function.  In the InitializeRenderProperties() function you will want to access the particle systems RenderProperties property and setup the render properties however you ned.

- The InitializeRenderProperties() function only gets called once; when initializing the particle system; whereas the old InitializeRenderState() function used to get called every time the DPSF particle system was drawn, so you may have code in the old InitializeRenderState() function that you need to move into a new EveryTimeEvent function.

- Remove the old ResetRenderState() function.

For an example of this you can take a look at just about any of the particle systems in the DPSF Demo, including the ExplosionFlash particle system.

3 - Wrap all [Serializable] attributes in "if (WINDOWS)" conditional compilation statements

While the Xbox 360 never supported the [Serializable] attribute in XNA 3.1, it didn't cause any compiler errors either.  In XNA 4.0 the [Serializable] attribute now causes compiler errors in Xbox 360 and Windows Phone projects.  So anywhere that you have [Serializable] you will either need to delete the attribute, or change it to the following code so that it only gets included in Windows projects, and not Xbox or Windows Phone projects:

#if (WINDOWS)

       [Serializable]

#endif

4 - Particles are not longer drawn in the correct order (depth sorting is not correct)

If you had a particle system using textures with both opaque and (semi)transparent portions, and were previously using alpha testing, you may notice that they are not drawn in the correct order anymore.  Since you cannot simply turn Alpha Testing on anymore in the XNA 4.0 BlendState, you have to either use the AlphaTest Effect (which DPSF doesn't by default), or sort the particles by depth before drawing them.  To sort the particles by depth, DPSF now provides 2 functions built into the Quad particle systems;

Particle EveryTimeEvent - UpdateParticleDistanceFromCameraSquared

Particle System EveryTimeEvent - UpdateParticleSystemToSortParticlesByDistanceFromCamera

Using the AlphaTest Effect is less expensive (and thus better to use), but it will only provide proper results for textures that are masks; that have only fully opaque and fully transparent portions (i.e. no semi-transparent parts).  If your textures have semi-transparent parts as well, you will want to use the depth sorting approach.

For an example of how to use the AlphaTest Effect to properly draw the particles, see the AnimatedQuadPS particle system in the DPSF Demo.  For examples of how to sort the particles using the distance from the camera in both Quad and Sprite particle systems, see the MultipleParticleImagesPS and AnimatedSpritePS particle systems respectively in the DPSF Demo.

5 - Now getting run-time errors when trying to draw Sprite particles, or color tinting is no longer applied to Sprite particles

Sprite particle systems no longer default to using the custom DPSF effect; this allows it to run on the Windows Phone 7 without any changes.  This means that your existing Sprite particle systems may encounter run-time errors when you try to draw them, as the default SpriteBatch effect has different parameters than the DPSF effect.  For example, the default SpriteBatch effect does not have a "xColorBlendAmount" parameter.  Also, if your Sprite particles were using the particle's Color attribute to change their color, then the color may no longer be the exact same as it was in prior versions, since the DPSF effect used the particle color in conjunction with the xColorBlendAmount parameter to determine the texture's final color.

The custom DPSF effect can still be applied though by calling the function "SetEffectAndTechnique(DPSFDefaultEffect, DPSFDefaultEffectTechniques.Sprites.ToString());".  The DPSF effect will only work however on Windows and the Xbox 360; the Windows Phone does not yet support custom shader effects.

For an example of how to apply the DPSF effect to your Sprite particle systems again, check out the AnimatedSpritePS particle system in the DPSF Demo.  To use the built-in SpriteBatch effect (so it will run on the Windows Phone), you should not need to do anything extra, and you should be able to remove the overridden SetEffectParameters() function.  For an example of using the built-in SpriteBatch effect, see the SpritePS particle system in the DPSF Demo.