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

#include <OgreParticleSystemManager.h>

Inheritance diagram for Ogre::ParticleSystemManager:

Public Types
typedef MapIterator< ParticleAffectorFactoryMap >	ParticleAffectorFactoryIterator

typedef std::map< String, ParticleAffectorFactory * >	ParticleAffectorFactoryMap

typedef MapIterator< ParticleEmitterFactoryMap >	ParticleEmitterFactoryIterator

typedef std::map< String, ParticleEmitterFactory * >	ParticleEmitterFactoryMap

typedef MapIterator< ParticleSystemRendererFactoryMap >	ParticleRendererFactoryIterator

typedef std::map< String, ParticleSystemRendererFactory * >	ParticleSystemRendererFactoryMap

typedef MapIterator< ParticleTemplateMap >	ParticleSystemTemplateIterator

typedef std::map< String, ParticleSystem * >	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...

ParticleSystem *	createTemplate (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 override
	Gets the loading order for scripts of this type. More...

ParticleRendererFactoryIterator	getRendererFactoryIterator (void)
	Return an iterator over the renderer factories currently registered. More...

const StringVector &	getScriptPatterns (void) const override
	Gets the file patterns which should be used to find scripts for this class. More...

ParticleSystem *	getTemplate (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	parseScript (DataStreamPtr &stream, const String &groupName) override
	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 specific Resource Group from the ParticleSystemManager. More...

Public Member Functions inherited from Ogre::Singleton< ParticleSystemManager >
	Singleton (void)

	~Singleton (void)

Public Member Functions inherited from Ogre::ScriptLoader
virtual	~ScriptLoader ()

Static Public Member Functions
static ParticleSystemManager &	getSingleton (void)
	Get the singleton instance. More...

static ParticleSystemManager *	getSingletonPtr (void)
	Get the singleton instance. More...

Static Public Member Functions inherited from Ogre::Singleton< ParticleSystemManager >
static ParticleSystemManager &	getSingleton (void)
	Get the singleton instance. More...

static ParticleSystemManager *	getSingletonPtr (void)
	Get the singleton instance. More...

Detailed Description

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

This singleton class is responsible for managing particle systems. 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. The actual implementations, such as cone, sphere and box-shaped emitters, and simple affectors such as constant directional force and colour faders are provided by the ParticleFX Plugin shipped with Ogre. However using this registration process, a custom 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 SceneManager::createParticleSystem method.

Member Typedef Documentation

◆ ParticleTemplateMap

typedef std::map<String, ParticleSystem*> Ogre::ParticleSystemManager::ParticleTemplateMap

◆ ParticleAffectorFactoryMap

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

◆ ParticleEmitterFactoryMap

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

◆ ParticleSystemRendererFactoryMap

typedef std::map<String, ParticleSystemRendererFactory*> Ogre::ParticleSystemManager::ParticleSystemRendererFactoryMap

◆ ParticleAffectorFactoryIterator

typedef MapIterator<ParticleAffectorFactoryMap> Ogre::ParticleSystemManager::ParticleAffectorFactoryIterator

◆ ParticleEmitterFactoryIterator

typedef MapIterator<ParticleEmitterFactoryMap> Ogre::ParticleSystemManager::ParticleEmitterFactoryIterator

◆ ParticleRendererFactoryIterator

typedef MapIterator<ParticleSystemRendererFactoryMap> Ogre::ParticleSystemManager::ParticleRendererFactoryIterator

◆ ParticleSystemTemplateIterator

typedef MapIterator<ParticleTemplateMap> Ogre::ParticleSystemManager::ParticleSystemTemplateIterator

Constructor & Destructor Documentation

◆ ParticleSystemManager()

Ogre::ParticleSystemManager::ParticleSystemManager ( )

◆ ~ParticleSystemManager()

virtual Ogre::ParticleSystemManager::~ParticleSystemManager ( )

virtual

Member Function Documentation

◆ addEmitterFactory()

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

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

◆ addAffectorFactory()

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

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

◆ addRendererFactory()

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

factory Pointer to a ParticleSystemRendererFactory subclass created by the plugin or application code.

◆ addTemplate()

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

name	The name of the template. Must be unique across all templates.
sysTemplate	A pointer to a particle system to be used as a template. The manager will take over ownership of this pointer.

◆ removeTemplate()

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

name	The name of the template to remove.
deleteTemplate	Whether or not to delete the template before removing it.

◆ removeAllTemplates()

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

Removes a specified template from the ParticleSystemManager.

Remarks: This method removes all templates from the ParticleSystemManager.

Parameters

deleteTemplate Whether or not to delete the templates before removing them.

◆ removeTemplatesByResourceGroup()

void Ogre::ParticleSystemManager::removeTemplatesByResourceGroup ( const String & resourceGroup )

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

Remarks: This method removes all templates that belong in a particular resource group from the ParticleSystemManager.

Parameters

resourceGroup Resource group to delete templates for

◆ createTemplate()

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

name	The name of the template. Must be unique across all templates.
resourceGroup	The name of the resource group which will be used to load any dependent resources.

◆ getTemplate()

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.

◆ _createEmitter()

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

emitterType	String name of the emitter type to be created. A factory of this type must have been registered.
psys	The particle system this is being created for

◆ _destroyEmitter()

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.

◆ _createAffector()

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

affectorType	String name of the affector type to be created. A factory of this type must have been registered.
psys	The particle system it is being created for

◆ _destroyAffector()

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.

◆ _createRenderer()

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

rendererType String name of the renderer type to be created. A factory of this type must have been registered.

◆ _destroyRenderer()

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

renderer Pointer to renderer to be destroyed. On return this pointer will point to invalid (freed) memory.

◆ _initialise()

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.

◆ getScriptPatterns()

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

overridevirtual

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

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.

◆ parseScript()

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

overridevirtual

Parse a script file.

Parameters

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

Implements Ogre::ScriptLoader.

◆ getLoadingOrder()

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

overridevirtual

Gets the loading order for scripts of this type.

There are dependencies between some kinds of scripts, and this value enumerates that. Higher values load later during bulk loading tasks.

Returns: The loading order

Implements Ogre::ScriptLoader.

◆ getAffectorFactoryIterator()

ParticleAffectorFactoryIterator Ogre::ParticleSystemManager::getAffectorFactoryIterator ( void )

Return an iterator over the affector factories currently registered.

◆ getEmitterFactoryIterator()

ParticleEmitterFactoryIterator Ogre::ParticleSystemManager::getEmitterFactoryIterator ( void )

Return an iterator over the emitter factories currently registered.

◆ getRendererFactoryIterator()

ParticleRendererFactoryIterator Ogre::ParticleSystemManager::getRendererFactoryIterator ( void )

Return an iterator over the renderer factories currently registered.

◆ getTemplateIterator()

ParticleSystemTemplateIterator Ogre::ParticleSystemManager::getTemplateIterator ( void )

inline

Gets an iterator over the list of particle system templates.

◆ _getFactory()

ParticleSystemFactory* Ogre::ParticleSystemManager::_getFactory ( void )

inline

Get an instance of ParticleSystemFactory (internal use).

◆ getSingleton()

static ParticleSystemManager& Ogre::ParticleSystemManager::getSingleton ( void )

static

Get the singleton instance.

◆ getSingletonPtr()

static ParticleSystemManager* Ogre::ParticleSystemManager::getSingletonPtr ( void )

static

Get the singleton instance.

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

OgreParticleSystemManager.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ParticleTemplateMap

◆ ParticleAffectorFactoryMap

◆ ParticleEmitterFactoryMap

◆ ParticleSystemRendererFactoryMap

◆ ParticleAffectorFactoryIterator

◆ ParticleEmitterFactoryIterator

◆ ParticleRendererFactoryIterator

◆ ParticleSystemTemplateIterator

Constructor & Destructor Documentation

◆ ParticleSystemManager()

◆ ~ParticleSystemManager()

Member Function Documentation

◆ addEmitterFactory()

◆ addAffectorFactory()

◆ addRendererFactory()

◆ addTemplate()

◆ removeTemplate()

◆ removeAllTemplates()

◆ removeTemplatesByResourceGroup()

◆ createTemplate()

◆ getTemplate()

◆ _createEmitter()

◆ _destroyEmitter()

◆ _createAffector()

◆ _destroyAffector()

◆ _createRenderer()

◆ _destroyRenderer()

◆ _initialise()

◆ getScriptPatterns()

◆ parseScript()

◆ getLoadingOrder()

◆ getAffectorFactoryIterator()

◆ getEmitterFactoryIterator()

◆ getRendererFactoryIterator()

◆ getTemplateIterator()

◆ _getFactory()

◆ getSingleton()

◆ getSingletonPtr()