Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Ogre::ParticleSystemManager Class Reference

Manages particle systems, particle system scripts (templates) and the available emitter & affector factories. More...

#include <OgreParticleSystemManager.h>

Inheritance diagram for Ogre::ParticleSystemManager:

Inheritance graph
[legend]
List of all members.

Public Methods

 ParticleSystemManager ()
virtual ~ParticleSystemManager ()
void addEmitterFactory (ParticleEmitterFactory *factory)
 Adds a new 'factory' object for emitters to the list of available emitter types.

void addAffectorFactory (ParticleAffectorFactory *factory)
 Adds a new 'factory' object for affectors to the list of available affector types.

void addTemplate (const String &name, const ParticleSystem &sysTemplate)
 Adds a new particle system template to the list of available templates.

ParticleSystemcreateTemplate (const String &name)
 Create a new particle system template.

ParticleSystemgetTemplate (const String &name)
 Retrieves a particle system template for possible modification.

ParticleSystemcreateSystem (const String &name, unsigned int quota=500)
 Basic method for creating a blank particle system.

ParticleSystemcreateSystem (const String &name, const String &templateName)
 Creates a particle system based on a template.

void destroySystem (const String &name)
 Destroys a particle system, freeing it's memory and removing references to it in this class.

void destroySystem (ParticleSystem *sys)
 Destroys a particle system, freeing it's memory and removing references to it in this class.

ParticleSystemgetSystem (const String &name)
 Retrieves a pointer to a system already created.

ParticleEmitter_createEmitter (const String &emitterType)
 Internal method for creating a new emitter from a factory.

void _destroyEmitter (ParticleEmitter *emitter)
 Internal method for destroying an emitter.

ParticleAffector_createAffector (const String &affectorType)
 Internal method for creating a new affector from a factory.

void _destroyAffector (ParticleAffector *affector)
 Internal method for destroying an affector.

bool frameStarted (const FrameEvent &evt)
 Frame event.

bool frameEnded (const FrameEvent &evt)
 Frame event.

void _initialise (void)
 Init method to be called by OGRE system.

void parseScript (DataChunk &chunk)
 Parses a particle system script file passed as a chunk.

void parseAllSources (const String &extension=".particle")
 Parses all particle system script files in resource folders & archives.

Real getTimeFactor (void) const
 Return relative speed of time as perceived by particle systems.

void setTimeFactor (Real tf)
 Set the relative speed of time as perceived by particle systems.


Static Public Methods

ParticleSystemManager & getSingleton (void)
 Override standard Singleton retrieval.

ParticleSystemManager * getSingletonPtr (void)
 Override standard Singleton retrieval.


Protected Types

typedef std::map< String,
ParticleSystem
ParticleTemplateMap
typedef std::map< String,
ParticleSystem * > 
ParticleSystemMap
typedef std::map< String,
ParticleEmitterFactory * > 
ParticleEmitterFactoryMap
typedef std::map< String,
ParticleAffectorFactory * > 
ParticleAffectorFactoryMap

Protected Methods

void parseNewEmitter (const String &type, DataChunk &chunk, ParticleSystem *sys)
 Internal script parsing method.

void parseNewAffector (const String &type, DataChunk &chunk, ParticleSystem *sys)
 Internal script parsing method.

void parseAttrib (const String &line, ParticleSystem *sys)
 Internal script parsing method.

void parseEmitterAttrib (const String &line, ParticleEmitter *sys)
 Internal script parsing method.

void parseAffectorAttrib (const String &line, ParticleAffector *sys)
 Internal script parsing method.

void skipToNextCloseBrace (DataChunk &chunk)
 Internal script parsing method.

void skipToNextOpenBrace (DataChunk &chunk)
 Internal script parsing method.


Protected Attributes

ParticleTemplateMap mSystemTemplates
 Templates based on scripts.

ParticleSystemMap mSystems
 Actual instantiated particle systems (may be based on template, may be manual).

ParticleEmitterFactoryMap mEmitterFactories
 Factories for named emitter types (can be extended using plugins).

ParticleAffectorFactoryMap mAffectorFactories
 Factories for named affector types (can be extended using plugins).

Real mTimeFactor
 Controls time.


Static Protected Attributes

ParticleSystemManager * ms_Singleton = 0

Detailed Description

Manages particle systems, particle system scripts (templates) and the available emitter & affector factories.

Remarks:
This singleton class is responsible for creating and managing particle systems. All particle systems must be created and destroyed using this object. Remember that like all other MovableObject subclasses, ParticleSystems do not get rendered until they are attached to a SceneNode object.

This class also manages factories for ParticleEmitter and ParticleAffector classes. To enable easy extensions to the types of emitters (particle sources) and affectors (particle modifiers), the ParticleSystemManager lets plugins or applications register factory classes which submit new subclasses to ParticleEmitter and ParticleAffector. Ogre comes with a number of them already provided, such as cone, sphere and box-shaped emitters, and simple affectors such as constant directional force and colour faders. However using this registration process, a plugin can create any behaviour required.

This class also manages the loading and parsing of particle system scripts, which are text files describing named particle system templates. Instances of particle systems using these templates can then be created easily through the createParticleSystem method.

Definition at line 54 of file OgreParticleSystemManager.h.


Member Typedef Documentation

typedef std::map<String, ParticleAffectorFactory*> Ogre::ParticleSystemManager::ParticleAffectorFactoryMap [protected]
 

Definition at line 69 of file OgreParticleSystemManager.h.

typedef std::map<String, ParticleEmitterFactory*> Ogre::ParticleSystemManager::ParticleEmitterFactoryMap [protected]
 

Definition at line 65 of file OgreParticleSystemManager.h.

typedef std::map<String, ParticleSystem*> Ogre::ParticleSystemManager::ParticleSystemMap [protected]
 

Definition at line 61 of file OgreParticleSystemManager.h.

typedef std::map<String, ParticleSystem> Ogre::ParticleSystemManager::ParticleTemplateMap [protected]
 

Definition at line 57 of file OgreParticleSystemManager.h.


Constructor & Destructor Documentation

Ogre::ParticleSystemManager::ParticleSystemManager  
 

Definition at line 48 of file OgreParticleSystemManager.cpp.

References mTimeFactor.

Ogre::ParticleSystemManager::~ParticleSystemManager   [virtual]
 

Definition at line 53 of file OgreParticleSystemManager.cpp.

References mSystems, and mSystemTemplates.


Member Function Documentation

ParticleAffector * Ogre::ParticleSystemManager::_createAffector const String   affectorType
 

Internal method for creating a new affector from a factory.

Remarks:
Used internally by the engine to create new ParticleAffector instances from named factories. Applications should use the ParticleSystem::addAffector method instead, which calls this method to create an instance.
Parameters:
effectorType  String name of the affector type to be created. A factory of this type must have been registered.

Definition at line 293 of file OgreParticleSystemManager.cpp.

References Except, and mAffectorFactories.

ParticleEmitter * Ogre::ParticleSystemManager::_createEmitter const String   emitterType
 

Internal method for creating a new emitter from a factory.

Remarks:
Used internally by the engine to create new ParticleEmitter instances from named factories. Applications should use the ParticleSystem::addEmitter method instead, which calls this method to create an instance.
Parameters:
emitterType  String name of the emitter type to be created. A factory of this type must have been registered.

Definition at line 265 of file OgreParticleSystemManager.cpp.

References Except, and mEmitterFactories.

void Ogre::ParticleSystemManager::_destroyAffector ParticleAffector   affector
 

Internal method for destroying an affector.

Remarks:
Because affectors are created by factories which may allocate memory from separate heaps, the memory allocated must be freed from the same place. This method is used to ask the factory to destroy the instance passed in as a pointer.
Parameters:
affector  Pointer to affector to be destroyed. On return this pointer will point to invalid (freed) memory.

Definition at line 308 of file OgreParticleSystemManager.cpp.

References Except, Ogre::ParticleAffector::getType(), and mAffectorFactories.

void Ogre::ParticleSystemManager::_destroyEmitter ParticleEmitter   emitter
 

Internal method for destroying an emitter.

Remarks:
Because emitters are created by factories which may allocate memory from separate heaps, the memory allocated must be freed from the same place. This method is used to ask the factory to destroy the instance passed in as a pointer.
Parameters:
emitter  Pointer to emitter to be destroyed. On return this pointer will point to invalid (freed) memory.

Definition at line 279 of file OgreParticleSystemManager.cpp.

References Except, Ogre::ParticleEmitter::getType(), and mEmitterFactories.

void Ogre::ParticleSystemManager::_initialise void   
 

Init method to be called by OGRE system.

Remarks:
Due to dependencies between various objects certain initialisation tasks cannot be done on construction. OGRE will call this method when the rendering subsystem is initialised.

Definition at line 343 of file OgreParticleSystemManager.cpp.

References parseAllSources().

Referenced by Ogre::Root::oneTimePostWindowInit().

void Ogre::ParticleSystemManager::addAffectorFactory ParticleAffectorFactory   factory
 

Adds a new 'factory' object for affectors to the list of available affector types.

Remarks:
This method allows plugins etc to add new particle affector types to Ogre. Particle affectors modify the particles in a system a certain way such as affecting their direction or changing their colour, lifespan etc. Plugins would create new subclasses of ParticleAffector which affect particles a certain way, and register a subclass of ParticleAffectorFactory to create them.

All particle affector factories have an assigned name which is used to identify the affector type. This must be unique.

Note that the object passed to this function will not be destroyed by the ParticleSystemManager, since it may have been allocted on a different heap in the case of plugins. The caller must destroy the object later on, probably on plugin shutdown.

Parameters:
factory  Pointer to a ParticleAffectorFactory subclass created by the plugin or application code.

Definition at line 169 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleAffectorFactory::getName(), and mAffectorFactories.

void Ogre::ParticleSystemManager::addEmitterFactory ParticleEmitterFactory   factory
 

Adds a new 'factory' object for emitters to the list of available emitter types.

Remarks:
This method allows plugins etc to add new particle emitter types to Ogre. Particle emitters are sources of particles, and generate new particles with their start positions, colours and momentums appropriately. Plugins would create new subclasses of ParticleEmitter which emit particles a certain way, and register a subclass of ParticleEmitterFactory to create them (since multiple emitters can be created for different particle systems).

All particle emitter factories have an assigned name which is used to identify the emitter type. This must be unique.

Note that the object passed to this function will not be destroyed by the ParticleSystemManager, since it may have been allocted on a different heap in the case of plugins. The caller must destroy the object later on, probably on plugin shutdown.

Parameters:
factory  Pointer to a ParticleEmitterFactory subclass created by the plugin or application code.

Definition at line 162 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleEmitterFactory::getName(), and mEmitterFactories.

void Ogre::ParticleSystemManager::addTemplate const String   name,
const ParticleSystem   sysTemplate
 

Adds a new particle system template to the list of available templates.

Remarks:
Instances of particle systems in a scene are not normally unique - often you want to place the same effect in many places. This method allows you to register a ParticleSystem as a named template, which can subsequently be used to create instances using the createSystem method.

Note that particle system templates can either be created programmatically by an application and registered using this method, or they can be defined in a script file (*.particle) which is loaded by the engine at startup, very much like Material scripts.

Parameters:
name  The name of the template. Must be unique across all templates.
sysTemplate  A reference to a particle system to be used as a template. This instance will be copied to a template held in this class so the object passed in here may be destroyed independently.

Definition at line 176 of file OgreParticleSystemManager.cpp.

References mSystemTemplates.

Referenced by createTemplate().

ParticleSystem * Ogre::ParticleSystemManager::createSystem const String   name,
const String   templateName
 

Creates a particle system based on a template.

Remarks:
This method creates a new ParticleSystem instance based on the named template and returns a pointer to the caller. The caller should not delete this object, it will be freed at system shutdown, or can be released earlier using the destroySystem method.

Each system created from a template takes the template's settings at the time of creation, but is completely separate from the template from there on.

Creating a particle system does not make it a part of the scene. As with other MovableObject subclasses, a ParticleSystem is not rendered until it is attached to a SceneNode.

This is probably the more useful particle system creation method since it does not require manual setup of the system. Note that the initial quota is based on the template but may be changed later.

Parameters:
name  The name to give the new particle system instance.
templateName  The name of the template to base the new instance on.

Definition at line 209 of file OgreParticleSystemManager.cpp.

References createSystem(), Except, Ogre::ParticleSystem::getParticleQuota(), and getTemplate().

ParticleSystem * Ogre::ParticleSystemManager::createSystem const String   name,
unsigned int    quota = 500
 

Basic method for creating a blank particle system.

Remarks:
This method creates a new, blank ParticleSystem instance and returns a pointer to it. The caller should not delete this object, it will be freed at system shutdown, or can be released earlier using the destroySystem method.

The instance returned from this method won't actually do anything because on creation a particle system has no emitters. The caller should manipulate the instance through it's ParticleSystem methods to actually create a real particle effect.

Creating a particle system does not make it a part of the scene. As with other MovableObject subclasses, a ParticleSystem is not rendered until it is attached to a SceneNode.

Parameters:
name  The name to give the ParticleSystem.
quota  The maximum number of particles to allow in this system.

Definition at line 201 of file OgreParticleSystemManager.cpp.

References mSystems, and Ogre::ParticleSystem::setParticleQuota().

Referenced by createSystem().

ParticleSystem * Ogre::ParticleSystemManager::createTemplate const String   name
 

Create a new particle system template.

Remarks:
This method is similar to the addTemplate method, except this just creates a new template and returns a pointer to it to be populated. Use this when you don't already have a system to add as a template and just want to create a new template which you will build up in-place.
Parameters:
name  The name of the template. Must be unique across all templates.

Definition at line 181 of file OgreParticleSystemManager.cpp.

References addTemplate(), and getTemplate().

Referenced by parseScript().

void Ogre::ParticleSystemManager::destroySystem ParticleSystem   sys
 

Destroys a particle system, freeing it's memory and removing references to it in this class.

Remarks:
You should ensure that before calling this method, the particle system has been detached from any SceneNode objects, and that no other objects are referencing it.
Parameters:
sys  Pointer to the ParticleSystem to be destroyed.

Definition at line 235 of file OgreParticleSystemManager.cpp.

References mSystems.

void Ogre::ParticleSystemManager::destroySystem const String   name
 

Destroys a particle system, freeing it's memory and removing references to it in this class.

Remarks:
You should ensure that before calling this method, the particle system has been detached from any SceneNode objects, and that no other objects are referencing it.
Parameters:
name  The name of the ParticleSystem to destroy.

Definition at line 225 of file OgreParticleSystemManager.cpp.

References mSystems.

bool Ogre::ParticleSystemManager::frameEnded const FrameEvent   evt [virtual]
 

Frame event.

Reimplemented from Ogre::FrameListener.

Definition at line 338 of file OgreParticleSystemManager.cpp.

bool Ogre::ParticleSystemManager::frameStarted const FrameEvent   evt [virtual]
 

Frame event.

Reimplemented from Ogre::FrameListener.

Definition at line 322 of file OgreParticleSystemManager.cpp.

References mSystems, mTimeFactor, Ogre::Real, and Ogre::FrameEvent::timeSinceLastFrame.

ParticleSystemManager & Ogre::ParticleSystemManager::getSingleton void    [static]
 

Override standard Singleton retrieval.

Remarks:
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.

This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

Reimplemented from Ogre::Singleton< ParticleSystemManager >.

Definition at line 43 of file OgreParticleSystemManager.cpp.

References Ogre::Singleton< ParticleSystemManager >::ms_Singleton.

ParticleSystemManager * Ogre::ParticleSystemManager::getSingletonPtr void    [static]
 

Override standard Singleton retrieval.

Remarks:
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.

This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

Reimplemented from Ogre::Singleton< ParticleSystemManager >.

Definition at line 39 of file OgreParticleSystemManager.cpp.

References Ogre::Singleton< ParticleSystemManager >::ms_Singleton.

ParticleSystem * Ogre::ParticleSystemManager::getSystem const String   name
 

Retrieves a pointer to a system already created.

Definition at line 250 of file OgreParticleSystemManager.cpp.

References Except, and mSystems.

ParticleSystem * Ogre::ParticleSystemManager::getTemplate const String   name
 

Retrieves a particle system template for possible modification.

Remarks:
Modifying a template does not affect the settings on any ParticleSystems already created from this template.

Definition at line 188 of file OgreParticleSystemManager.cpp.

References mSystemTemplates.

Referenced by createSystem(), and createTemplate().

Real Ogre::ParticleSystemManager::getTimeFactor void    const
 

Return relative speed of time as perceived by particle systems.

Remarks:
See setTimeFactor for full information on the meaning of this value.

Definition at line 477 of file OgreParticleSystemManager.cpp.

References mTimeFactor, and Ogre::Real.

void Ogre::ParticleSystemManager::parseAffectorAttrib const String   line,
ParticleAffector   sys
[protected]
 

Internal script parsing method.

Definition at line 441 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleAffector::getType(), Ogre::StringInterface::setParameter(), and Ogre::String::split().

Referenced by parseNewAffector().

void Ogre::ParticleSystemManager::parseAllSources const String   extension = ".particle"
 

Parses all particle system script files in resource folders & archives.

Definition at line 145 of file OgreParticleSystemManager.cpp.

References parseScript().

Referenced by _initialise().

void Ogre::ParticleSystemManager::parseAttrib const String   line,
ParticleSystem   sys
[protected]
 

Internal script parsing method.

Definition at line 409 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleSystem::getName(), Ogre::StringInterface::setParameter(), and Ogre::String::split().

Referenced by parseScript().

void Ogre::ParticleSystemManager::parseEmitterAttrib const String   line,
ParticleEmitter   sys
[protected]
 

Internal script parsing method.

Definition at line 425 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleEmitter::getType(), Ogre::StringInterface::setParameter(), and Ogre::String::split().

Referenced by parseNewEmitter().

void Ogre::ParticleSystemManager::parseNewAffector const String   type,
DataChunk   chunk,
ParticleSystem   sys
[protected]
 

Internal script parsing method.

Definition at line 382 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleSystem::addAffector(), Ogre::DataChunk::getLine(), Ogre::DataChunk::isEOF(), parseAffectorAttrib(), and Ogre::String::toLowerCase().

Referenced by parseScript().

void Ogre::ParticleSystemManager::parseNewEmitter const String   type,
DataChunk   chunk,
ParticleSystem   sys
[protected]
 

Internal script parsing method.

Definition at line 352 of file OgreParticleSystemManager.cpp.

References Ogre::ParticleSystem::addEmitter(), Ogre::DataChunk::getLine(), Ogre::DataChunk::isEOF(), parseEmitterAttrib(), and Ogre::String::toLowerCase().

Referenced by parseScript().

void Ogre::ParticleSystemManager::parseScript DataChunk   chunk
 

Parses a particle system script file passed as a chunk.

Definition at line 66 of file OgreParticleSystemManager.cpp.

References createTemplate(), Ogre::DataChunk::getLine(), Ogre::ParticleSystem::getName(), Ogre::DataChunk::isEOF(), parseAttrib(), parseNewAffector(), parseNewEmitter(), skipToNextCloseBrace(), skipToNextOpenBrace(), and Ogre::String::split().

Referenced by parseAllSources().

void Ogre::ParticleSystemManager::setTimeFactor Real    tf
 

Set the relative speed of time as perceived by particle systems.

Remarks:
Normally particle systems are updated automatically in line with the real passage of time. This method allows you to change that, so that particle systems are told that the time is passing slower or faster than it actually is. Use this to globally speed up / slow down particle systems.
Parameters:
tf  The virtual speed of time (1.0 is real time).

Definition at line 481 of file OgreParticleSystemManager.cpp.

References mTimeFactor, and Ogre::Real.

void Ogre::ParticleSystemManager::skipToNextCloseBrace DataChunk   chunk [protected]
 

Internal script parsing method.

Definition at line 457 of file OgreParticleSystemManager.cpp.

References Ogre::DataChunk::getLine(), and Ogre::DataChunk::isEOF().

Referenced by parseScript().

void Ogre::ParticleSystemManager::skipToNextOpenBrace DataChunk   chunk [protected]
 

Internal script parsing method.

Definition at line 467 of file OgreParticleSystemManager.cpp.

References Ogre::DataChunk::getLine(), and Ogre::DataChunk::isEOF().

Referenced by parseScript().


Member Data Documentation

ParticleAffectorFactoryMap Ogre::ParticleSystemManager::mAffectorFactories [protected]
 

Factories for named affector types (can be extended using plugins).

Definition at line 71 of file OgreParticleSystemManager.h.

Referenced by _createAffector(), _destroyAffector(), and addAffectorFactory().

ParticleEmitterFactoryMap Ogre::ParticleSystemManager::mEmitterFactories [protected]
 

Factories for named emitter types (can be extended using plugins).

Definition at line 67 of file OgreParticleSystemManager.h.

Referenced by _createEmitter(), _destroyEmitter(), and addEmitterFactory().

ParticleSystemManager * Ogre::Singleton< ParticleSystemManager >::ms_Singleton = 0 [static, protected, inherited]
 

Definition at line 38 of file OgreParticleSystemManager.cpp.

Referenced by getSingleton(), and getSingletonPtr().

ParticleSystemMap Ogre::ParticleSystemManager::mSystems [protected]
 

Actual instantiated particle systems (may be based on template, may be manual).

Definition at line 63 of file OgreParticleSystemManager.h.

Referenced by createSystem(), destroySystem(), frameStarted(), getSystem(), and ~ParticleSystemManager().

ParticleTemplateMap Ogre::ParticleSystemManager::mSystemTemplates [protected]
 

Templates based on scripts.

Definition at line 59 of file OgreParticleSystemManager.h.

Referenced by addTemplate(), getTemplate(), and ~ParticleSystemManager().

Real Ogre::ParticleSystemManager::mTimeFactor [protected]
 

Controls time.

Definition at line 74 of file OgreParticleSystemManager.h.

Referenced by frameStarted(), getTimeFactor(), ParticleSystemManager(), and setTimeFactor().


The documentation for this class was generated from the following files:

Copyright © 2002-2003 by The OGRE Team
Last modified Fri May 14 23:26:50 2004