OgreHaptics::ForceEffectManager Class Reference

Manages force effects, force effect scripts (templates) and the available algorithm factories. More...

#include <OgreHapticsForceEffectManager.h>

List of all members.

Public Types

typedef ConstMapIterator
< ForceEffectMap > ForceEffectIterator

typedef ConstMapIterator
< ForceEffectAlgorithmFactoryMap > ForceEffectAlgorithmFactoryIterator

Public Member Functions

ForceEffectManager ()

Standard constructor.

virtual ~ForceEffectManager ()

Virtual destructor.

const StringVector & getScriptPatterns (void) const

Implements Ogre::ScriptLoader::getScriptPatterns.

void parseScript (DataStreamPtr &stream, const String &groupName)

Implements Ogre::ScriptLoader::parseScript.

Real getLoadingOrder (void) const

Implements Ogre::ScriptLoader::getLoadingOrder.

ForceEffect * createTemplate (const String &name)

Creates a new force effect template.

void addTemplate (const String &name, ForceEffect *effect)

Adds a new force effect template to the list of available templates.

ForceEffect * getTemplate (const String &name)

Retrieves a force effect template for possible modification.

ForceEffectIterator getTemplateIterator (void)

Returns an specialised Ogre::ConstMapIterator over the list of force effect templates.

void removeTemplate (const String &name, bool deleteTemplate=true)

Removes a specified template from the ForceEffectManager.

void removeAllTemplates (bool deleteTemplates=true)

Removes all templates from the ForceEffectManager.

ForceEffect * createEffect (const String &name, const String &templateName)

Creates a force effect based on a template.

ForceEffect * createEffect (const String &name)

Creates a blank force effect.

ForceEffect * getEffect (const String &name) const

Returns a pointer to the named ForceEffect.

bool hasEffect (const String &name) const

Returns whether a force effect with the given name exists.

void destroyEffect (const String &name)

Removes and destroys the named ForceEffect.

void destroyEffect (ForceEffect *effect)

Removes and destroys the given ForceEffect.

void destroyAllEffects (void)

Removes and destroys all ForceEffects from the manager.

void addAlgorithmFactory (ForceEffectAlgorithmFactory *factory)

Adds a new factory object for algorithms to the list of available algorithm types.

ForceEffectAlgorithmFactoryIterator getAlgorithmFactoryIterator (void)

Returns a specialised Ogre::ConstMapIterator over the registered ForceAlgorithmFactory instances.

ForceEffectAlgorithm * _createAlgorithm (const String &algorithmType)

Internal method for creating an algorithm from a factory.

void _destroyAlgorithm (ForceEffectAlgorithm *algorithm)

Internal method for destroying an algorithm.

Static Public Member Functions

static ForceEffectManager & getSingleton (void)

Override standard Ogre::Singleton retrieval.

static ForceEffectManager * getSingletonPtr (void)

Override standard Ogre::Singleton retrieval.

Protected Types

typedef std::map< String,
ForceEffect * > ForceEffectMap

typedef std::map< String,
ForceEffectAlgorithmFactory * > ForceEffectAlgorithmFactoryMap

Protected Member Functions

void parseNewAlgorithm (const String &type, DataStreamPtr &stream, ForceEffect *effect)

Internal script parsing method.

void parseAttrib (const String &line, ForceEffect *effect)

Internal script parsing method.

void parseAlgorithmAttrib (const String &line, ForceEffectAlgorithm *algorithm)

Internal script parsing method.

void skipToNextCloseBrace (DataStreamPtr &stream)

Internal script parsing method.

void skipToNextOpenBrace (DataStreamPtr &stream)

Internal script parsing method.

Protected Attributes

OGREHAPTICS_AUTO_MUTEX
ForceEffectMap mEffectTemplates

Templates based on scripts.

ForceEffectMap mEffects

List of managed effects.

ForceEffectAlgorithmFactoryMap mAlgorithmFactories

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

StringVector mScriptPatterns

List of patterns.

Detailed Description

Manages force effects, force effect scripts (templates) and the available algorithm factories.

Remarks:: This class is responsible for creating and managing force effect instances. All force effects must be created and destroyed using the single instance of this class.

: This class also manages factories for ForceEffectAlgorithm classes. To enable easy extensions to the types of algorithms the ForceEffectManager lets plugins and applications register factory classes which submit new subclasses to ForceEffectAlgorithm. OgreHaptics comes with a small number of them already provided, such as constant, spring, sine wave and viscosity algorithms. However using this registration process, a plugin or application can create new behaviour required.

: This class also manages the loading and parsing of force effect scripts, which are text files describing named force effect templates. Instances of force effects using these templates can then be created easily through the createEffect method.

Definition at line 79 of file OgreHapticsForceEffectManager.h.

Member Typedef Documentation

typedef std::map<String, ForceEffect*> OgreHaptics::ForceEffectManager::ForceEffectMap [protected]

Definition at line 83 of file OgreHapticsForceEffectManager.h.

typedef std::map<String, ForceEffectAlgorithmFactory*> OgreHaptics::ForceEffectManager::ForceEffectAlgorithmFactoryMap [protected]

Definition at line 84 of file OgreHapticsForceEffectManager.h.

typedef ConstMapIterator<ForceEffectMap> OgreHaptics::ForceEffectManager::ForceEffectIterator

Definition at line 173 of file OgreHapticsForceEffectManager.h.

typedef ConstMapIterator<ForceEffectAlgorithmFactoryMap> OgreHaptics::ForceEffectManager::ForceEffectAlgorithmFactoryIterator

Definition at line 285 of file OgreHapticsForceEffectManager.h.

Constructor & Destructor Documentation

OgreHaptics::ForceEffectManager::ForceEffectManager ( )

Standard constructor.

virtual OgreHaptics::ForceEffectManager::~ForceEffectManager ( ) [virtual]

Virtual destructor.

Member Function Documentation

static ForceEffectManager& OgreHaptics::ForceEffectManager::getSingleton ( void ) [static]

Override standard Ogre::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 ForceEffectManager* OgreHaptics::ForceEffectManager::getSingletonPtr ( void ) [static]

Override standard Ogre::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.

const StringVector& OgreHaptics::ForceEffectManager::getScriptPatterns ( void ) const

Implements Ogre::ScriptLoader::getScriptPatterns.

void OgreHaptics::ForceEffectManager::parseScript	(	DataStreamPtr &	stream,
		const String &	groupName
	)

Implements Ogre::ScriptLoader::parseScript.

Real OgreHaptics::ForceEffectManager::getLoadingOrder ( void ) const

Implements Ogre::ScriptLoader::getLoadingOrder.

ForceEffect* OgreHaptics::ForceEffectManager::createTemplate ( const String & name )

Creates a new force effect 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 force effect 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.

void OgreHaptics::ForceEffectManager::addTemplate	(	const String &	name,
		ForceEffect *	effect
	)

Adds a new force effect template to the list of available templates.

Remarks:: Instances of force effects in a scene are not normally unique - sometimes you want to render the same effect through multiple devices. This method allows you to register a ForceEffect as a named template, which can subsequently be used to create instances using the createEffect method.

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

Parameters:

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

ForceEffect* OgreHaptics::ForceEffectManager::getTemplate ( const String & name )

Retrieves a force effect template for possible modification.

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

Exceptions:

An

ItemNotFoundException if the template could not be found.

ForceEffectIterator OgreHaptics::ForceEffectManager::getTemplateIterator ( void )

Returns an specialised Ogre::ConstMapIterator over the list of force effect templates.

void OgreHaptics::ForceEffectManager::removeTemplate	(	const String &	name,
		bool	deleteTemplate = `true`
	)

Removes a specified template from the ForceEffectManager.

Remarks:: This method removes a given template from the force effect manager, optionally deleting the template if the deleteTemplate method is called.

Parameters:

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

Exceptions:

An

ItemNotFoundException if the template could not be found.

void OgreHaptics::ForceEffectManager::removeAllTemplates ( bool deleteTemplates = true )

Removes all templates from the ForceEffectManager.

Remarks:: This method removes all templates from the force effect manager, optionally deleting the templates if the deleteTemplate method is called.

Parameters:

deleteTemplates

Whether or not to delete the templates before removing it.

ForceEffect* OgreHaptics::ForceEffectManager::createEffect	(	const String &	name,
		const String &	templateName
	)

Creates a force effect based on a template.

Remarks:: This method creates a force effect instance based on a named template 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 destroyEffect method.

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

Parameters:

	name	The name to give the new force effect instance, must be unique.
	templateName	The name of the template to base the new instance on.

Exceptions:

	An	DuplicateItemException if an effect with the given name already exists.
	An	ItemNotFoundException if the template could not be found.

ForceEffect* OgreHaptics::ForceEffectManager::createEffect ( const String & name )

Creates a blank force effect.

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

: The instance returned won't actually do anything, since on creation no algorithms are added. The caller should add algorithms through the methods provided by the ForceEffect class.

Parameters:

name

The name to give the new force effect instance, must be unique.

Exceptions:

An

DuplicateItemException if an effect with the given name already exists.

ForceEffect* OgreHaptics::ForceEffectManager::getEffect ( const String & name ) const

Returns a pointer to the named ForceEffect.

Exceptions:

An

ItemNotFoundException if the named force effect does not exist.

bool OgreHaptics::ForceEffectManager::hasEffect ( const String & name ) const

Returns whether a force effect with the given name exists.

void OgreHaptics::ForceEffectManager::destroyEffect ( const String & name )

Removes and destroys the named ForceEffect.

Parameters:

name

The name of the force effect to be destroyed.

void OgreHaptics::ForceEffectManager::destroyEffect ( ForceEffect * effect )

Removes and destroys the given ForceEffect.

Parameters:

effect

Pointer to the force effect to be destroyed.

void OgreHaptics::ForceEffectManager::destroyAllEffects ( void )

Removes and destroys all ForceEffects from the manager.

void OgreHaptics::ForceEffectManager::addAlgorithmFactory ( ForceEffectAlgorithmFactory * factory )

Adds a new factory object for algorithms to the list of available algorithm types.

Remarks:: This method allows plugins etc. to add new algorithm types to OgreHaptics. ForceEffectAlgorithms are objects used for the calculation of forces (of part) of a ForceEffect. Plugins would create new subclasses of ForceEffectAlgorithm which calculate forces in a specific way, and register a subclass of ForceEffectAlgorithmFactory to create them (since multiple algorithms can be created for different force effects).

: All algoritm factories have an assigned name which is used to identify the algorithm type. This name must be unique.

: Note that the object passed to this function will not be destroyed by the ForceEffectManager, 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 ForceAlgorithmFactory subclass created by the plugin or application code.

ForceEffectAlgorithmFactoryIterator OgreHaptics::ForceEffectManager::getAlgorithmFactoryIterator ( void )

Returns a specialised Ogre::ConstMapIterator over the registered ForceAlgorithmFactory instances.

ForceEffectAlgorithm* OgreHaptics::ForceEffectManager::_createAlgorithm ( const String & algorithmType )

Internal method for creating an algorithm from a factory.

Remarks:: Used internally by the system to create new ForceEffectAlgorithm instances from named factories. Applications should use ForceEffect::addAlgorithm method instead, which calls this method to create an instance.

Parameters:

algorithmType

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

Exceptions:

An

InvalidArgumentsException if no factory for the given type could be found.

void OgreHaptics::ForceEffectManager::_destroyAlgorithm ( ForceEffectAlgorithm * algorithm )

Internal method for destroying an algorithm.

Remarks:: Because algorithms 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:

algorithm

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

void OgreHaptics::ForceEffectManager::parseNewAlgorithm	(	const String &	type,
		DataStreamPtr &	stream,
		ForceEffect *	effect
	)			`[protected]`