Ogre::ParticleSystem Class Reference

Class defining particle system based special effects. More...

#include <OgreParticleSystem.h>

Inheritance diagram for Ogre::ParticleSystem:

[legend]

List of all members.

Public Types
typedef std::vector < ShadowRenderable * >	ShadowRenderableList
typedef VectorIterator < ShadowRenderableList >	ShadowRenderableListIterator
Public Member Functions
	ParticleSystem ()
	Default constructor required for STL creation in manager.
	ParticleSystem (const String &name, const String &resourceGroupName)
	Creates a particle system with no emitters or affectors.
virtual	~ParticleSystem ()
void	setRenderer (const String &typeName)
	Sets the ParticleRenderer to be used to render this particle system.
ParticleSystemRenderer *	getRenderer (void) const
	Gets the ParticleRenderer to be used to render this particle system.
const String &	getRendererName (void) const
	Gets the name of the ParticleRenderer to be used to render this particle system.
ParticleEmitter *	addEmitter (const String &emitterType)
	Adds an emitter to this particle system.
ParticleEmitter *	getEmitter (unsigned short index) const
	Retrieves an emitter by it's index (zero-based).
unsigned short	getNumEmitters (void) const
	Returns the number of emitters for this particle system.
void	removeEmitter (unsigned short index)
	Removes an emitter from the system.
void	removeAllEmitters (void)
	Removes all the emitters from this system.
ParticleAffector *	addAffector (const String &affectorType)
	Adds an affector to this particle system.
ParticleAffector *	getAffector (unsigned short index) const
	Retrieves an affector by it's index (zero-based).
unsigned short	getNumAffectors (void) const
	Returns the number of affectors for this particle system.
void	removeAffector (unsigned short index)
	Removes an affector from the system.
void	removeAllAffectors (void)
	Removes all the affectors from this system.
void	clear ()
	Empties this set of all particles.
size_t	getNumParticles (void) const
	Gets the number of individual particles in the system right now.
Particle *	createParticle (void)
	Manually add a particle to the system.
Particle *	createEmitterParticle (const String &emitterName)
	Manually add an emitter particle to the system.
Particle *	getParticle (size_t index)
	Retrieve a particle from the system for manual tweaking.
size_t	getParticleQuota (void) const
	Returns the maximum number of particles this system is allowed to have active at once.
void	setParticleQuota (size_t quota)
	Sets the maximum number of particles this system is allowed to have active at once.
size_t	getEmittedEmitterQuota (void) const
	Returns the maximum number of emitted emitters this system is allowed to have active at once.
void	setEmittedEmitterQuota (size_t quota)
	Sets the maximum number of emitted emitters this system is allowed to have active at once.
ParticleSystem &	operator= (const ParticleSystem &rhs)
	Assignment operator for copying.
void	_update (Real timeElapsed)
	Updates the particles in the system based on time elapsed.
ParticleIterator	_getIterator (void)
	Returns an iterator for stepping through all particles in this system.
virtual void	setMaterialName (const String &name)
	Sets the name of the material to be used for this billboard set.
virtual const String &	getMaterialName (void) const
	Sets the name of the material to be used for this billboard set.
virtual void	_notifyCurrentCamera (Camera *cam)
	Overridden from MovableObject.
void	_notifyAttached (Node *parent, bool isTagPoint=false)
	Overridden from MovableObject.
virtual const AxisAlignedBox &	getBoundingBox (void) const
	Overridden from MovableObject.
virtual Real	getBoundingRadius (void) const
	Overridden from MovableObject.
virtual void	_updateRenderQueue (RenderQueue *queue)
	Overridden from MovableObject.
void	visitRenderables (Renderable::Visitor *visitor, bool debugRenderables=false)
	Method to allow a caller to abstractly iterate over the Renderable instances that this MovableObject will add to the render queue when asked, if any. Parameters: visitor  Pointer to a class implementing the Renderable::Visitor interface which will be called back for each Renderable which will be queued. Bear in mind that the state of the Renderable instances may not be finalised depending on when you call this. debugRenderables  If false, only regular renderables will be visited (those for normal display). If true, debug renderables will be included too.
void	fastForward (Real time, Real interval=0.1)
	Fast-forwards this system by the required number of seconds.
void	setSpeedFactor (Real speedFactor)
	Sets a 'speed factor' on this particle system, which means it scales the elapsed real time which has passed by this factor before passing it to the emitters, affectors, and the particle life calculation.
Real	getSpeedFactor (void) const
	Gets the 'speed factor' on this particle system.
void	setIterationInterval (Real iterationInterval)
	Sets a 'iteration interval' on this particle system.
Real	getIterationInterval (void) const
	Gets a 'iteration interval' on this particle system.
void	setNonVisibleUpdateTimeout (Real timeout)
	Sets when the particle system should stop updating after it hasn't been visible for a while.
Real	getNonVisibleUpdateTimeout (void) const
	Gets when the particle system should stop updating after it hasn't been visible for a while.
const String &	getMovableType (void) const
	Overridden from MovableObject.
virtual void	_notifyParticleResized (void)
	Internal callback used by Particles to notify their parent that they have been resized.
virtual void	_notifyParticleRotated (void)
	Internal callback used by Particles to notify their parent that they have been rotated.
virtual void	setDefaultDimensions (Real width, Real height)
	Sets the default dimensions of the particles in this set.
virtual void	setDefaultWidth (Real width)
	See setDefaultDimensions - this sets 1 component individually.
virtual Real	getDefaultWidth (void) const
	See setDefaultDimensions - this gets 1 component individually.
virtual void	setDefaultHeight (Real height)
	See setDefaultDimensions - this sets 1 component individually.
virtual Real	getDefaultHeight (void) const
	See setDefaultDimensions - this gets 1 component individually.
virtual bool	getCullIndividually (void) const
	Returns whether or not particles in this are tested individually for culling.
virtual void	setCullIndividually (bool cullIndividual)
	Sets whether culling tests particles in this individually as well as in a group.
virtual const String &	getResourceGroupName (void) const
	Return the resource group to be used to load dependent resources.
const String &	getOrigin (void) const
	Get the origin of this particle system, e.g.
void	_notifyOrigin (const String &origin)
	Notify this particle system of it's origin.
void	setRenderQueueGroup (uint8 queueID)
	Sets the render queue group this entity will be rendered through. Remarks: Render queues are grouped to allow you to more tightly control the ordering of rendered objects. If you do not call this method, all Entity objects default to the default queue (RenderQueue::getDefaultQueueGroup), which is fine for most objects. You may want to alter this if you want this entity to always appear in front of other objects, e.g. for a 3D menu system or such. See RenderQueue for more details. Parameters: queueID  Enumerated value of the queue group to use.
void	setSortingEnabled (bool enabled)
	Set whether or not particles are sorted according to the camera.
bool	getSortingEnabled (void) const
	Gets whether particles are sorted relative to the camera.
void	setBounds (const AxisAlignedBox &aabb)
	Set the (initial) bounds of the particle system manually.
void	setBoundsAutoUpdated (bool autoUpdate, Real stopIn=0.0f)
	Sets whether the bounds will be automatically updated for the life of the particle system.
void	setKeepParticlesInLocalSpace (bool keepLocal)
	Sets whether particles (and any affector effects) remain relative to the node the particle system is attached to.
bool	getKeepParticlesInLocalSpace (void) const
	Gets whether particles (and any affector effects) remain relative to the node the particle system is attached to.
void	_updateBounds (void)
	Internal method for updating the bounds of the particle system.
uint32	getTypeFlags (void) const
	Override to return specific type flag.
ParamDictionary *	getParamDictionary (void)
	Retrieves the parameter dictionary for this class.
const ParamDictionary *	getParamDictionary (void) const
const ParameterList &	getParameters (void) const
	Retrieves a list of parameters valid for this object.
virtual bool	setParameter (const String &name, const String &value)
	Generic parameter setting method.
virtual void	setParameterList (const NameValuePairList &paramList)
	Generic multiple parameter setting method.
virtual String	getParameter (const String &name) const
	Generic parameter retrieval method.
virtual void	copyParametersTo (StringInterface *dest) const
	Method for copying this object's parameters to another object.
virtual void	_notifyCreator (MovableObjectFactory *fact)
	Notify the object of it's creator (internal use only).
virtual MovableObjectFactory *	_getCreator (void) const
	Get the creator of this object, if any (internal use only).
virtual void	_notifyManager (SceneManager *man)
	Notify the object of it's manager (internal use only).
virtual SceneManager *	_getManager (void) const
	Get the manager of this object, if any (internal use only).
virtual const String &	getName (void) const
	Returns the name of this object.
virtual Node *	getParentNode (void) const
	Returns the node to which this object is attached.
virtual SceneNode *	getParentSceneNode (void) const
	Returns the scene node to which this object is attached.
virtual bool	isAttached (void) const
	Returns true if this object is attached to a SceneNode or TagPoint.
virtual void	detatchFromParent (void)
	Detaches an object from a parent SceneNode or TagPoint, if attached.
virtual bool	isInScene (void) const
	Returns true if this object is attached to a SceneNode or TagPoint, and this SceneNode / TagPoint is currently in an active part of the scene graph.
virtual void	_notifyMoved (void)
	Internal method called to notify the object that it has been moved.
virtual const AxisAlignedBox &	getWorldBoundingBox (bool derive=false) const
	Retrieves the axis-aligned bounding box for this object in world coordinates.
virtual const Sphere &	getWorldBoundingSphere (bool derive=false) const
	Retrieves the worldspace bounding sphere for this object.
virtual void	setVisible (bool visible)
	Tells this object whether to be visible or not, if it has a renderable component.
virtual bool	getVisible (void) const
	Gets this object whether to be visible or not, if it has a renderable component.
virtual bool	isVisible (void) const
	Returns whether or not this object is supposed to be visible or not.
virtual void	setRenderingDistance (Real dist)
	Sets the distance at which the object is no longer rendered.
virtual Real	getRenderingDistance (void) const
	Gets the distance at which batches are no longer rendered.
virtual void	setUserObject (UserDefinedObject *obj)
	Call this to associate your own custom user object instance with this MovableObject.
virtual UserDefinedObject *	getUserObject (void)
	Retrieves a pointer to a custom application object associated with this movable by an earlier call to setUserObject.
virtual void	setUserAny (const Any &anything)
	Sets any kind of user value on this object.
virtual const Any &	getUserAny (void) const
	Retrieves the custom user value associated with this object.
virtual uint8	getRenderQueueGroup (void) const
	Gets the queue group for this entity, see setRenderQueueGroup for full details.
virtual const Matrix4 &	_getParentNodeFullTransform (void) const
	return the full transformation of the parent sceneNode or the attachingPoint node
virtual void	setQueryFlags (uint32 flags)
	Sets the query flags for this object.
virtual void	addQueryFlags (uint32 flags)
	As setQueryFlags, except the flags passed as parameters are appended to the existing flags on this object.
virtual void	removeQueryFlags (unsigned long flags)
	As setQueryFlags, except the flags passed as parameters are removed from the existing flags on this object.
virtual uint32	getQueryFlags (void) const
	Returns the query flags relevant for this object.
virtual void	setVisibilityFlags (uint32 flags)
	Sets the visiblity flags for this object.
virtual void	addVisibilityFlags (uint32 flags)
	As setVisibilityFlags, except the flags passed as parameters are appended to the existing flags on this object.
virtual void	removeVisibilityFlags (uint32 flags)
	As setVisibilityFlags, except the flags passed as parameters are removed from the existing flags on this object.
virtual uint32	getVisibilityFlags (void) const
	Returns the visibility flags relevant for this object.
virtual void	setListener (Listener *listener)
	Sets a listener for this object.
virtual Listener *	getListener (void) const
	Gets the current listener for this object.
virtual const LightList &	queryLights (void) const
	Gets a list of lights, ordered relative to how close they are to this movable object.
virtual LightList *	_getLightList ()
	Returns a pointer to the current list of lights for this object.
EdgeData *	getEdgeList (void)
	Define a default implementation of method from ShadowCaster which implements no shadows.
bool	hasEdgeList (void)
	Define a default implementation of method from ShadowCaster which implements no shadows.
ShadowRenderableListIterator	getShadowVolumeRenderableIterator (ShadowTechnique shadowTechnique, const Light *light, HardwareIndexBufferSharedPtr *indexBuffer, bool extrudeVertices, Real extrusionDist, unsigned long flags=0)
	Define a default implementation of method from ShadowCaster which implements no shadows.
const AxisAlignedBox &	getLightCapBounds (void) const
	Overridden member from ShadowCaster.
const AxisAlignedBox &	getDarkCapBounds (const Light &light, Real dirLightExtrusionDist) const
	Overridden member from ShadowCaster.
void	setCastShadows (bool enabled)
	Sets whether or not this object will cast shadows.
bool	getCastShadows (void) const
	Returns whether shadow casting is enabled for this object.
Real	getPointExtrusionDistance (const Light *l) const
	Get the distance to extrude for a point/spot light.
virtual void	setDebugDisplayEnabled (bool enabled)
	Sets whether or not the debug display of this object is enabled.
virtual bool	isDebugDisplayEnabled (void) const
	Gets whether debug display of this object is enabled.
const StringVector &	getAnimableValueNames (void) const
	Gets a list of animable value names for this object.
virtual AnimableValuePtr	createAnimableValue (const String &valueName)
	Create a reference-counted AnimableValuePtr for the named value.
void *	operator new (size_t sz, const char *file, int line, const char *func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char *file, int line, const char *func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
void	operator delete (void *ptr)
void	operator delete (void *ptr, const char *, int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void *ptr, const char *, int, const char *)
Static Public Member Functions
static void	setDefaultIterationInterval (Real iterationInterval)
	Set the default iteration interval for all ParticleSystem instances.
static Real	getDefaultIterationInterval (void)
	Get the default iteration interval for all ParticleSystem instances.
static void	setDefaultNonVisibleUpdateTimeout (Real timeout)
	Set the default nonvisible timeout for all ParticleSystem instances.
static Real	getDefaultNonVisibleUpdateTimeout (void)
	Get the default nonvisible timeout for all ParticleSystem instances.
static void	cleanupDictionary ()
	Cleans up the static 'msDictionary' required to reset Ogre, otherwise the containers are left with invalid pointers, which will lead to a crash as soon as one of the ResourceManager implementers (e.g.
static void	setDefaultQueryFlags (uint32 flags)
	Set the default query flags for all future MovableObject instances.
static uint32	getDefaultQueryFlags ()
	Get the default query flags for all future MovableObject instances.
static void	setDefaultVisibilityFlags (uint32 flags)
	Set the default visibility flags for all future MovableObject instances.
static uint32	getDefaultVisibilityFlags ()
	Get the default visibility flags for all future MovableObject instances.
static void	extrudeVertices (const HardwareVertexBufferSharedPtr &vertexBuffer, size_t originalVertexCount, const Vector4 &lightPos, Real extrudeDist)
	Utility method for extruding vertices based on a light.
Protected Types
typedef std::list < Particle * >	ActiveParticleList
typedef std::list < Particle * >	FreeParticleList
typedef std::vector < Particle * >	ParticlePool
typedef std::list < ParticleEmitter * >	FreeEmittedEmitterList
typedef std::list < ParticleEmitter * >	ActiveEmittedEmitterList
typedef std::vector < ParticleEmitter * >	EmittedEmitterList
typedef std::map < String, FreeEmittedEmitterList >	FreeEmittedEmitterMap
typedef std::map < String, EmittedEmitterList >	EmittedEmitterPool
typedef std::vector < ParticleEmitter * >	ParticleEmitterList
typedef std::vector < ParticleAffector * >	ParticleAffectorList
typedef std::map < String, StringVector >	AnimableDictionaryMap
Protected Member Functions
void	_expire (Real timeElapsed)
	Internal method used to expire dead particles.
void	_triggerEmitters (Real timeElapsed)
	Spawn new particles based on free quota and emitter requirements.
void	_executeTriggerEmitters (ParticleEmitter *emitter, unsigned requested, Real timeElapsed)
	Helper function that actually performs the emission of particles.
void	_applyMotion (Real timeElapsed)
	Updates existing particle based on their momentum.
void	_triggerAffectors (Real timeElapsed)
	Applies the effects of affectors.
void	_sortParticles (Camera *cam)
	Sort the particles in the system.
void	increasePool (size_t size)
	Resize the internal pool of particles.
void	increaseEmittedEmitterPool (size_t size)
	Resize the internal pool of emitted emitters.
void	initParameters (void)
	Internal method for initialising string interface.
void	configureRenderer (void)
	Internal method to configure the renderer.
void	createVisualParticles (size_t poolstart, size_t poolend)
	Internal method for creating ParticleVisualData instances for the pool.
void	destroyVisualParticles (size_t poolstart, size_t poolend)
	Internal method for destroying ParticleVisualData instances for the pool.
void	initialiseEmittedEmitters (void)
	Create a pool of emitted emitters and assign them to the free emitter list.
void	initialiseEmittedEmitterPool (void)
	Determine which emitters in the Particle Systems main emitter become a template for creating an pool of emitters that can be emitted.
void	addFreeEmittedEmitters (void)
	Add emitters from the pool to the free emitted emitter queue.
void	removeAllEmittedEmitters (void)
	Removes all emitted emitters from this system.
FreeEmittedEmitterList *	findFreeEmittedEmitter (const String &name)
	Find the list with free emitted emitters.
void	removeFromActiveEmittedEmitters (ParticleEmitter *emitter)
	Removes an emitter from the active emitted emitter list.
void	addActiveEmittedEmittersToFreeList (void)
	Moves all emitted emitters from the active list to the free list.
void	_notifyReorganiseEmittedEmitterData (void)
	This function clears all data structures that are used in combination with emitted emitters and sets the flag to indicate that the emitted emitter pool must be initialised again.
bool	createParamDictionary (const String &className)
	Internal method for creating a parameter dictionary for the class, if it does not already exist.
Real	getExtrusionDistance (const Vector3 &objectPos, const Light *light) const
	Helper method for calculating extrusion distance.
virtual void	updateEdgeListLightFacing (EdgeData *edgeData, const Vector4 &lightPos)
	Tells the caster to perform the tasks necessary to update the edge data's light listing.
virtual void	generateShadowVolume (EdgeData *edgeData, const HardwareIndexBufferSharedPtr &indexBuffer, const Light *light, ShadowRenderableList &shadowRenderables, unsigned long flags)
	Generates the indexes required to render a shadow volume into the index buffer which is passed in, and updates shadow renderables to use it.
virtual void	extrudeBounds (AxisAlignedBox &box, const Vector4 &lightPos, Real extrudeDist) const
	Utility method for extruding a bounding box.
virtual const String &	getAnimableDictionaryName (void) const
	Get the name of the animable dictionary for this class.
void	createAnimableDictionary (void) const
	Internal method for creating a dictionary of animable value names for the class, if it does not already exist.
StringVector &	_getAnimableValueNames (void)
	Get an updateable reference to animable value list.
virtual void	initialiseAnimableDictionary (StringVector &) const
	Internal method for initialising dictionary; should be implemented by subclasses wanting to expose animable parameters.
Protected Attributes
AxisAlignedBox	mAABB
Real	mBoundingRadius
bool	mBoundsAutoUpdate
Real	mBoundsUpdateTime
Real	mUpdateRemainTime
AxisAlignedBox	mWorldAABB
	World AABB, only used to compare world-space positions to calc bounds.
String	mResourceGroupName
	Name of the resource group to use to load materials.
String	mMaterialName
	Name of the material to use.
bool	mIsRendererConfigured
	Have we set the material etc on the renderer?
MaterialPtr	mpMaterial
	Pointer to the material to use.
Real	mDefaultWidth
	Default width of each particle.
Real	mDefaultHeight
	Default height of each particle.
Real	mSpeedFactor
	Speed factor.
Real	mIterationInterval
	Iteration interval.
bool	mIterationIntervalSet
	Iteration interval set? Otherwise track default.
bool	mSorted
	Particles sorted according to camera?
bool	mLocalSpace
	Particles in local space?
Real	mNonvisibleTimeout
	Update timeout when nonvisible (0 for no timeout).
bool	mNonvisibleTimeoutSet
	Update timeout when nonvisible set? Otherwise track default.
Real	mTimeSinceLastVisible
	Amount of time non-visible so far.
unsigned long	mLastVisibleFrame
	Last frame in which known to be visible.
Controller< Real > *	mTimeController
	Controller for time update.
bool	mEmittedEmitterPoolInitialised
	Indication whether the emitted emitter pool (= pool with particle emitters that are emitted) is initialised.
ActiveParticleList	mActiveParticles
	Active particle list.
FreeParticleList	mFreeParticles
	Free particle queue.
ParticlePool	mParticlePool
	Pool of particle instances for use and reuse in the active particle list.
EmittedEmitterPool	mEmittedEmitterPool
	Pool of emitted emitters for use and reuse in the active emitted emitter list.
FreeEmittedEmitterMap	mFreeEmittedEmitters
	Free emitted emitter list.
ActiveEmittedEmitterList	mActiveEmittedEmitters
	Active emitted emitter list.
ParticleEmitterList	mEmitters
	List of particle emitters, ie sources of particles.
ParticleAffectorList	mAffectors
	List of particle affectors, ie modifiers of particles.
ParticleSystemRenderer *	mRenderer
	The renderer used to render this particle system.
bool	mCullIndividual
	Do we cull each particle individually?
String	mRendererType
	The name of the type of renderer used to render this system.
size_t	mPoolSize
	The number of particles in the pool.
size_t	mEmittedEmitterPoolSize
	The number of emitted emitters in the pool.
String	mOrigin
	Optional origin of this particle system (eg script name).
String	mParamDictName
	Class name for this instance to be used as a lookup (must be initialised by subclasses).
String	mName
	Name of this object.
MovableObjectFactory *	mCreator
	Creator of this object (if created by a factory).
SceneManager *	mManager
	SceneManager holding this object (if applicable).
Node *	mParentNode
	node to which this object is attached
bool	mParentIsTagPoint
bool	mVisible
	Is this object visible?
bool	mDebugDisplay
	Is debug display enabled?
Real	mUpperDistance
	Upper distance to still render.
Real	mSquaredUpperDistance
bool	mBeyondFarDistance
	Hidden because of distance?
Any	mUserAny
	User defined link to another object / value / whatever.
uint8	mRenderQueueID
	The render queue to use when rendering this object.
bool	mRenderQueueIDSet
	Flags whether the RenderQueue's default should be used.
uint32	mQueryFlags
	Flags determining whether this object is included / excluded from scene queries.
uint32	mVisibilityFlags
	Flags determining whether this object is visible (compared to SceneManager mask).
Sphere	mWorldBoundingSphere
AxisAlignedBox	mWorldDarkCapBounds
	World space AABB of this object's dark cap.
bool	mCastShadows
	Does this object cast shadows?
bool	mRenderingDisabled
	Does rendering this object disabled by listener?
Listener *	mListener
	MovableObject listener - only one allowed (no list) for size & performance reasons. */.
LightList	mLightList
	List of lights for this object.
ulong	mLightListUpdated
	The last frame that this light list was updated in.
Static Protected Attributes
static CmdCull	msCullCmd
	Command objects.
static CmdHeight	msHeightCmd
static CmdMaterial	msMaterialCmd
static CmdQuota	msQuotaCmd
static CmdEmittedEmitterQuota	msEmittedEmitterQuotaCmd
static CmdWidth	msWidthCmd
static CmdRenderer	msRendererCmd
static CmdSorted	msSortedCmd
static CmdLocalSpace	msLocalSpaceCmd
static CmdIterationInterval	msIterationIntervalCmd
static CmdNonvisibleTimeout	msNonvisibleTimeoutCmd
static RadixSort < ActiveParticleList, Particle *, float >	mRadixSorter
static