OGRE  2.0
Object-Oriented Graphics Rendering Engine
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups 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:
+ Collaboration diagram for Ogre::ParticleSystemManager:

Public Types

typedef MapIterator
< ParticleAffectorFactoryMap
ParticleAffectorFactoryIterator
 
typedef map< String,
ParticleAffectorFactory * >
::type 
ParticleAffectorFactoryMap
 
typedef MapIterator
< ParticleEmitterFactoryMap
ParticleEmitterFactoryIterator
 
typedef map< String,
ParticleEmitterFactory * >
::type 
ParticleEmitterFactoryMap
 
typedef MapIterator
< ParticleSystemRendererFactoryMap
ParticleRendererFactoryIterator
 
typedef map< String,
ParticleSystemRendererFactory * >
::type 
ParticleSystemRendererFactoryMap
 
typedef MapIterator
< ParticleTemplateMap
ParticleSystemTemplateIterator
 
typedef map< String,
ParticleSystem * >::type 
ParticleTemplateMap
 

Public Member Functions

 ParticleSystemManager ()
 
virtual ~ParticleSystemManager ()
 
ParticleAffector_createAffector (const String &affectorType, ParticleSystem *psys)
 Internal method for creating a new affector from a factory. More...
 
ParticleEmitter_createEmitter (const String &emitterType, ParticleSystem *psys)
 Internal method for creating a new emitter from a factory. More...
 
ParticleSystemRenderer_createRenderer (const String &rendererType)
 Internal method for creating a new renderer from a factory. More...
 
void _destroyAffector (ParticleAffector *affector)
 Internal method for destroying an affector. More...
 
void _destroyEmitter (ParticleEmitter *emitter)
 Internal method for destroying an emitter. More...
 
void _destroyRenderer (ParticleSystemRenderer *renderer)
 Internal method for destroying a renderer. More...
 
ParticleSystemFactory_getFactory (void)
 Get an instance of ParticleSystemFactory (internal use). More...
 
void _initialise (void)
 Init method to be called by OGRE system. More...
 
void addAffectorFactory (ParticleAffectorFactory *factory)
 Adds a new 'factory' object for affectors to the list of available affector types. More...
 
void addEmitterFactory (ParticleEmitterFactory *factory)
 Adds a new 'factory' object for emitters to the list of available emitter types. More...
 
void addRendererFactory (ParticleSystemRendererFactory *factory)
 Registers a factory class for creating ParticleSystemRenderer instances. More...
 
void addTemplate (const String &name, ParticleSystem *sysTemplate)
 Adds a new particle system template to the list of available templates. More...
 
ParticleSystemcreateTemplate (const String &name, const String &resourceGroup)
 Create a new particle system template. More...
 
ParticleAffectorFactoryIterator getAffectorFactoryIterator (void)
 Return an iterator over the affector factories currently registered. More...
 
ParticleEmitterFactoryIterator getEmitterFactoryIterator (void)
 Return an iterator over the emitter factories currently registered. More...
 
Real getLoadingOrder (void) const
 Gets the relative loading order of scripts of this type. More...
 
ParticleRendererFactoryIterator getRendererFactoryIterator (void)
 Return an iterator over the renderer factories currently registered. More...
 
const StringVectorgetScriptPatterns (void) const
 Gets the file patterns which should be used to find scripts for this class. More...
 
ParticleSystemgetTemplate (const String &name)
 Retrieves a particle system template for possible modification. More...
 
ParticleSystemTemplateIterator getTemplateIterator (void)
 Gets an iterator over the list of particle system templates. More...
 
void operator delete (void *ptr)
 
void operator delete (void *ptr, void *)
 
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 *)
 
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info More...
 
void * operator new (size_t sz)
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info More...
 
void * operator new[] (size_t sz)
 
void parseScript (DataStreamPtr &stream, const String &groupName)
 Parse a script file. More...
 
void removeAllTemplates (bool deleteTemplate=true)
 Removes a specified template from the ParticleSystemManager. More...
 
void removeTemplate (const String &name, bool deleteTemplate=true)
 Removes a specified template from the ParticleSystemManager. More...
 
void removeTemplatesByResourceGroup (const String &resourceGroup)
 Removes all templates that belong to a secific Resource Group from the ParticleSystemManager. More...
 

Static Public Member Functions

static ParticleSystemManagergetSingleton (void)
 Override standard Singleton retrieval. More...
 
static ParticleSystemManagergetSingletonPtr (void)
 Override standard Singleton retrieval. More...
 

Protected Member Functions

ParticleSystemcreateSystemImpl (IdType id, ObjectMemoryManager *objectMemoryManager, size_t quota, const String &resourceGroup)
 Internal implementation of createSystem. More...
 
ParticleSystemcreateSystemImpl (IdType id, ObjectMemoryManager *objectMemoryManager, const String &templateName)
 Internal implementation of createSystem. More...
 
void destroySystemImpl (ParticleSystem *sys)
 Internal implementation of destroySystem. More...
 
void parseAffectorAttrib (const String &line, ParticleAffector *sys)
 Internal script parsing method. More...
 
void parseAttrib (const String &line, ParticleSystem *sys)
 Internal script parsing method. More...
 
void parseEmitterAttrib (const String &line, ParticleEmitter *sys)
 Internal script parsing method. More...
 
void parseNewAffector (const String &type, DataStreamPtr &chunk, ParticleSystem *sys)
 Internal script parsing method. More...
 
void parseNewEmitter (const String &type, DataStreamPtr &chunk, ParticleSystem *sys)
 Internal script parsing method. More...
 
void skipToNextCloseBrace (DataStreamPtr &chunk)
 Internal script parsing method. More...
 
void skipToNextOpenBrace (DataStreamPtr &chunk)
 Internal script parsing method. More...
 

Protected Attributes

ParticleAffectorFactoryMap mAffectorFactories
 Factories for named affector types (can be extended using plugins) More...
 
ParticleEmitterFactoryMap mEmitterFactories
 Factories for named emitter types (can be extended using plugins) More...
 
ParticleSystemFactorymFactory
 
ParticleSystemRendererFactoryMap mRendererFactories
 Map of renderer types to factories. More...
 
StringVector mScriptPatterns
 
ParticleTemplateMap mSystemTemplates
 Templates based on scripts. More...
 
ObjectMemoryManager mTemplatesObjectMemMgr
 
 OGRE_AUTO_MUTEX
 

Static Protected Attributes

static ParticleSystemManagermsSingleton
 

Friends

class ParticleSystemFactory
 

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, although the user interface to creating them is via SceneManager. 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 74 of file OgreParticleSystemManager.h.

Member Typedef Documentation

Constructor & Destructor Documentation

Ogre::ParticleSystemManager::ParticleSystemManager ( )
virtual Ogre::ParticleSystemManager::~ParticleSystemManager ( )
virtual

Member Function Documentation

ParticleAffector* Ogre::ParticleSystemManager::_createAffector ( const String affectorType,
ParticleSystem psys 
)

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
affectorTypeString name of the affector type to be created. A factory of this type must have been registered.
psysThe particle system it is being created for
ParticleEmitter* Ogre::ParticleSystemManager::_createEmitter ( const String emitterType,
ParticleSystem psys 
)

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
emitterTypeString name of the emitter type to be created. A factory of this type must have been registered.
psysThe particle system this is being created for
ParticleSystemRenderer* Ogre::ParticleSystemManager::_createRenderer ( const String rendererType)

Internal method for creating a new renderer from a factory.

Remarks
Used internally by the engine to create new ParticleSystemRenderer instances from named factories. Applications should use the ParticleSystem::setRenderer method instead, which calls this method to create an instance.
Parameters
rendererTypeString name of the renderer type to be created. A factory of this type must have been registered.
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
affectorPointer to affector to be destroyed. On return this pointer will point to invalid (freed) memory.
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
emitterPointer to emitter to be destroyed. On return this pointer will point to invalid (freed) memory.
void Ogre::ParticleSystemManager::_destroyRenderer ( ParticleSystemRenderer renderer)

Internal method for destroying a renderer.

Remarks
Because renderer 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
rendererPointer to renderer to be destroyed. On return this pointer will point to invalid (freed) memory.
ParticleSystemFactory* Ogre::ParticleSystemManager::_getFactory ( void  )
inline

Get an instance of ParticleSystemFactory (internal use).

Definition at line 349 of file OgreParticleSystemManager.h.

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.
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 allocated on a different heap in the case of plugins. The caller must destroy the object later on, probably on plugin shutdown.
Parameters
factoryPointer to a ParticleAffectorFactory subclass created by the plugin or application code.
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 allocated on a different heap in the case of plugins. The caller must destroy the object later on, probably on plugin shutdown.
Parameters
factoryPointer to a ParticleEmitterFactory subclass created by the plugin or application code.
void Ogre::ParticleSystemManager::addRendererFactory ( ParticleSystemRendererFactory factory)

Registers a factory class for creating ParticleSystemRenderer instances.

Note that the object passed to this function will not be destroyed by the ParticleSystemManager, since it may have been allocated on a different heap in the case of plugins. The caller must destroy the object later on, probably on plugin shutdown.
Parameters
factoryPointer to a ParticleSystemRendererFactory subclass created by the plugin or application code.
void Ogre::ParticleSystemManager::addTemplate ( const String name,
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
nameThe name of the template. Must be unique across all templates.
sysTemplateA pointer to a particle system to be used as a template. The manager will take over ownership of this pointer.
ParticleSystem* Ogre::ParticleSystemManager::createSystemImpl ( IdType  id,
ObjectMemoryManager objectMemoryManager,
size_t  quota,
const String resourceGroup 
)
protected

Internal implementation of createSystem.

ParticleSystem* Ogre::ParticleSystemManager::createSystemImpl ( IdType  id,
ObjectMemoryManager objectMemoryManager,
const String templateName 
)
protected

Internal implementation of createSystem.

ParticleSystem* Ogre::ParticleSystemManager::createTemplate ( const String name,
const String resourceGroup 
)

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
nameThe name of the template. Must be unique across all templates.
resourceGroupThe name of the resource group which will be used to load any dependent resources.
void Ogre::ParticleSystemManager::destroySystemImpl ( ParticleSystem sys)
protected

Internal implementation of destroySystem.

ParticleAffectorFactoryIterator Ogre::ParticleSystemManager::getAffectorFactoryIterator ( void  )

Return an iterator over the affector factories currently registered.

ParticleEmitterFactoryIterator Ogre::ParticleSystemManager::getEmitterFactoryIterator ( void  )

Return an iterator over the emitter factories currently registered.

Real Ogre::ParticleSystemManager::getLoadingOrder ( void  ) const
virtual

Gets the relative loading order of scripts of this type.

Remarks
There are dependencies between some kinds of scripts, and to enforce this all implementors of this interface must define a loading order.
Returns
A value representing the relative loading order of these scripts compared to other script users, where higher values load later.

Implements Ogre::ScriptLoader.

ParticleRendererFactoryIterator Ogre::ParticleSystemManager::getRendererFactoryIterator ( void  )

Return an iterator over the renderer factories currently registered.

const StringVector& Ogre::ParticleSystemManager::getScriptPatterns ( void  ) const
virtual

Gets the file patterns which should be used to find scripts for this class.

Remarks
This method is called when a resource group is loaded if you use ResourceGroupManager::_registerScriptLoader.
Returns
A list of file patterns, in the order they should be searched in.

Implements Ogre::ScriptLoader.

static 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.
static 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.
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.
ParticleSystemTemplateIterator Ogre::ParticleSystemManager::getTemplateIterator ( void  )
inline

Gets an iterator over the list of particle system templates.

Definition at line 342 of file OgreParticleSystemManager.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr)
inlineinherited

Definition at line 96 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
)
inlineinherited

Definition at line 102 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 108 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr)
inlineinherited

Definition at line 113 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 119 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz)
inlineinherited

Definition at line 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
)
inlineinherited

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz)
inlineinherited

Definition at line 91 of file OgreMemoryAllocatedObject.h.

void Ogre::ParticleSystemManager::parseAffectorAttrib ( const String line,
ParticleAffector sys 
)
protected

Internal script parsing method.

void Ogre::ParticleSystemManager::parseAttrib ( const String line,
ParticleSystem sys 
)
protected

Internal script parsing method.

void Ogre::ParticleSystemManager::parseEmitterAttrib ( const String line,
ParticleEmitter sys 
)
protected

Internal script parsing method.

void Ogre::ParticleSystemManager::parseNewAffector ( const String type,
DataStreamPtr chunk,
ParticleSystem sys 
)
protected

Internal script parsing method.

void Ogre::ParticleSystemManager::parseNewEmitter ( const String type,
DataStreamPtr chunk,
ParticleSystem sys 
)
protected

Internal script parsing method.

void Ogre::ParticleSystemManager::parseScript ( DataStreamPtr stream,
const String groupName 
)
virtual

Parse a script file.

Parameters
streamWeak reference to a data stream which is the source of the script
groupNameThe name of a resource group which should be used if any resources are created during the parse of this script.

Implements Ogre::ScriptLoader.

void Ogre::ParticleSystemManager::removeAllTemplates ( bool  deleteTemplate = true)

Removes a specified template from the ParticleSystemManager.

Remarks
This method removes all templates from the ParticleSystemManager.
Parameters
deleteTemplateWhether or not to delete the templates before removing them.
void Ogre::ParticleSystemManager::removeTemplate ( const String name,
bool  deleteTemplate = true 
)

Removes a specified template from the ParticleSystemManager.

Remarks
This method removes a given template from the particle system manager, optionally deleting the template if the deleteTemplate method is called. Throws an exception if the template could not be found.
Parameters
nameThe name of the template to remove.
deleteTemplateWhether or not to delete the template before removing it.
void Ogre::ParticleSystemManager::removeTemplatesByResourceGroup ( const String resourceGroup)

Removes all templates that belong to a secific Resource Group from the ParticleSystemManager.

Remarks
This method removes all templates that belong in a particular resource group from the ParticleSystemManager.
Parameters
resourceGroupResource group to delete templates for
void Ogre::ParticleSystemManager::skipToNextCloseBrace ( DataStreamPtr chunk)
protected

Internal script parsing method.

void Ogre::ParticleSystemManager::skipToNextOpenBrace ( DataStreamPtr chunk)
protected

Internal script parsing method.

Friends And Related Function Documentation

friend class ParticleSystemFactory
friend

Definition at line 77 of file OgreParticleSystemManager.h.

Member Data Documentation

ParticleAffectorFactoryMap Ogre::ParticleSystemManager::mAffectorFactories
protected

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

Definition at line 93 of file OgreParticleSystemManager.h.

ParticleEmitterFactoryMap Ogre::ParticleSystemManager::mEmitterFactories
protected

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

Definition at line 90 of file OgreParticleSystemManager.h.

ParticleSystemFactory* Ogre::ParticleSystemManager::mFactory
protected

Definition at line 101 of file OgreParticleSystemManager.h.

ParticleSystemRendererFactoryMap Ogre::ParticleSystemManager::mRendererFactories
protected

Map of renderer types to factories.

Definition at line 96 of file OgreParticleSystemManager.h.

StringVector Ogre::ParticleSystemManager::mScriptPatterns
protected

Definition at line 98 of file OgreParticleSystemManager.h.

ParticleSystemManager * Ogre::Singleton< ParticleSystemManager >::msSingleton
staticprotectedinherited

Definition at line 75 of file OgreSingleton.h.

ParticleTemplateMap Ogre::ParticleSystemManager::mSystemTemplates
protected

Templates based on scripts.

Definition at line 87 of file OgreParticleSystemManager.h.

ObjectMemoryManager Ogre::ParticleSystemManager::mTemplatesObjectMemMgr
protected

Definition at line 103 of file OgreParticleSystemManager.h.

Ogre::ParticleSystemManager::OGRE_AUTO_MUTEX
protected

Definition at line 84 of file OgreParticleSystemManager.h.


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