OgreHaptics::System Class Reference

System is the root class of the OgreHaptics system. More...

#include <OgreHapticsSystem.h>

List of all members.

Public Types
typedef std::vector< DynLib * >	PluginLibList
typedef std::vector< Plugin * >	PluginInstanceList
Public Member Functions
	System (const String &pluginsFileName="HapticsPlugins.cfg", const String &configFileName="OgreHaptics.cfg", const String &logFileName="OgreHaptics.log")
	Constructor.
virtual	~System ()
	Virtual destructor.
Device *	initialise (bool autoCreateDevice)
	Initialises the system.
void	shutdown (void)
	Shuts down the system manually.
bool	isInitialised (void) const
	Returns whether the system is initialised or not.
void	saveConfig (void)
	Saves the details of the current configuration.
bool	restoreConfig (void)
	Restores configuration from previously saved settings.
bool	showConfigDialog (void)
	Displays a dialog asking the user to choose config settings.
void	setConfigSettings (const DeviceInitInfo &configSettings)
	Sets the configuration settings which will be used for automatically creating a device during initialisation.
const DeviceInitInfo &	getConfigSettings (void) const
	Returns the configuration settings used for automatically creating a device during initialisation.
bool	setOption (const String &key, const void *value)
	Method for setting a specific option of the system.
bool	getOption (const String &key, void *value)
	Gets the specified option for the System.
Log *	getLog (void)
	Returns a pointer to the log used by OgreHaptics.
void	logMessage (const String &message, LogMessageLevel lml=LML_NORMAL, bool maskDebug=false)
	Log a message to the log used by OgreHaptics.
Log::Stream	logStream (LogMessageLevel lml=LML_NORMAL, bool maskDebug=false)
	Get a stream on the log used by OgreHaptics.
void	loadPlugin (const String &pluginName)
	Manually load a Plugin contained in a DLL / DSO.
void	unloadPlugin (const String &pluginName)
	Manually unloads a Plugin contained in a DLL / DSO.
void	installPlugin (Plugin *plugin)
	Install a new Plugin.
void	uninstallPlugin (Plugin *plugin)
	Uninstall an existing plugin.
const PluginInstanceList &	getInstalledPlugins () const
	Gets a read-only list of the currently installed plugins.
void	addRenderSystem (RenderSystem *newRend)
	Adds a new rendering subsystem to the list of available rendering systems.
RenderSystem *	getRenderSystemByName (const String &name)
	Retrieve a pointer to the rendering system by the given name or by the name of the API the RenderSystem supports.
RenderSystemList *	getAvailableRenderSystems (void)
	Retrieve a list of the available render systems.
const DeviceInfoList &	getAvailableNamedDevices (void) const
	Obtains an iterator over all haptics devices available on the users system supported through loaded Plugins.
unsigned int	getNumConnectedDevices (void)
	Returns the total number of available devices on all registered render systems.
Device *	createDevice (const String &name, const DeviceInitInfo &initInfo)
	Creates a new named Device.
Device *	createDevice (const String &name, unsigned int index, DeviceInitInfo &initInfo)
	Creates a new named Device.
Device *	getDevice (const String &name)
	Retrieves a pointer to a named Device.
void	destroyDevice (const String &name)
	Destroys a named device.
void	destroyDevice (Device *device)
	Destroys the given Device.
void	destroyAllDevices (void)
	Removes and destroys all devices created through the registered rendering systems.
ConstDeviceIterator	getDeviceIterator (void) const
	Returns a specialised Ogre::ConstDeviceIterator on all devices created by all registered rendering systems.
void	startSchedulers (unsigned long rate=1000, bool autoEnableDevices=true)
	Starts all schedulers used to manage the haptic threads of all registered render systems.
void	stopSchedulers (void)
	Stops the schedulers used by the registered rendering systems.
void	update (void)
	Updates all devices managed by the registered render systems.
void	_oneTimePostDeviceCreate (void)
	Operation for one time task to be performed after device creation.
Static Public Member Functions
static System &	getSingleton (void)
	Override standard Ogre::Singleton retrieval.
static System *	getSingletonPtr (void)
	Override standard Ogre::Singleton retrieval.
Protected Member Functions
void	loadPlugins (const String &pluginsFileName="HapticsPlugins.cfg")
	Method reads a plugins configuration file and instantiates all plugins.
void	initialisePlugins (void)
	Initialise all loaded plugins - allows plugins to perform actions once the system has been initialised.
void	shutdownPlugins (void)
	Shuts down all loaded plugins - allows things to be tidied up whilst all plugins are still loaded.
void	unloadPlugins (void)
	Unloads all loaded plugins.
Protected Attributes
OGREHAPTICS_AUTO_MUTEX bool	mIsInitialised
	Private mutex, not allowed to lock from outside.
bool	mFirstTimePostDeviceCreate
	Is the initialisation of subsystems done after the first device.
String	mConfigFileName
	Name of the haptics configuration file to be used.
DeviceInitInfo	mConfigSettings
	DeviceInfo structure holding information about the device to create.
PluginLibList	mPluginLibs
	List of Plugin DLLs loaded.
PluginInstanceList	mPlugins
	List of Plugin instances registered.

---

Detailed Description

System is the root class of the OgreHaptics system.

It is the first class that must be instantiated and the last class that must be cleaned up.

Remarks:

It represents a starting point for the client application. From here the application can gain access to ther fundamentals of the system, namely the haptics devices available and access to other classes in the system. An instance of the System must be created before any other OgreHaptics operations are called.

The management of plugins has been fully copied from Ogre::Root. This is done, so users familiar with OGRE will know how to handle these subsystems quickly, and last but not least it saves a lot of OgreHaptics development time.

Note:

The Ogre::Root class must be instantiated before an instance of this class is created.

Definition at line 80 of file OgreHapticsSystem.h.

---

Member Typedef Documentation

typedef std::vector<DynLib*> OgreHaptics::System::PluginLibList

Definition at line 300 of file OgreHapticsSystem.h.

typedef std::vector<Plugin*> OgreHaptics::System::PluginInstanceList

Definition at line 301 of file OgreHapticsSystem.h.

---

Constructor & Destructor Documentation

OgreHaptics::System::System	(	const String &	pluginsFileName = "HapticsPlugins.cfg",
		const String &	configFileName = "OgreHaptics.cfg",
		const String &	logFileName = "OgreHaptics.log"
	)

Constructor.

Parameters:

	pluginsFileName	The file that contains plugins information, defaults to 'HapticsPlugins.cfg'.
	configFileName	The file the contains configuration settings for creating and setting up a device instance.
	logFileName	The logfile to be used by OgreHaptics, defaults to 'OgreHaptics.log'. If this is left blank, the default log of OGRE will be used for logging.

virtual OgreHaptics::System::~System

(

)

[virtual]

Virtual destructor.

---

Member Function Documentation

static System& OgreHaptics::System::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 System* OgreHaptics::System::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.

Device* OgreHaptics::System::initialise

(

bool

autoCreateDevice

)

Initialises the system.

Parameters:

autoCreateDevice

If set to true, a device will be created automatically. To make use of this, System::setConfigSettings must have been called first.

Returns:

A pointer to the created device, if requested, NULL otherwise.

See also:

System::setConfigSettings

void OgreHaptics::System::shutdown

(

void

)

Shuts down the system manually.

Remarks:

This is normally called by OgreHaptics automatically. It is made available to those who need to shutdown the system on demand.

bool OgreHaptics::System::isInitialised

(

void

)

const

Returns whether the system is initialised or not.

Definition at line 152 of file OgreHapticsSystem.h.

void OgreHaptics::System::saveConfig

(

void

)

Saves the details of the current configuration.

Remarks:

Stores details of the current configuration so it may be restored later on.

bool OgreHaptics::System::restoreConfig

(

void

)

Restores configuration from previously saved settings.

Remarks:

This method checks whether or not previously saved settings from a previous run are stored or not. If there are, the state of the system will be restored to that configuration.

Returns:

true if a valid configuration was found, false otherwise.

bool OgreHaptics::System::showConfigDialog

(

void

)

Displays a dialog asking the user to choose config settings.

Returns:

If the user clicked 'OK', true will be returned false otherwise.

void OgreHaptics::System::setConfigSettings

(

const DeviceInitInfo &

configSettings

)

Sets the configuration settings which will be used for automatically creating a device during initialisation.

Remarks:

You need to call this if you do not wish to make use of the provided configuration, either through restoring previously set configuration settings or through the default configuration dialog, but do wish to create a device automatically when the system is initialised.

See also:

System::initialise

const DeviceInitInfo& OgreHaptics::System::getConfigSettings

(

void

)

const

Returns the configuration settings used for automatically creating a device during initialisation.

Definition at line 193 of file OgreHapticsSystem.h.

bool OgreHaptics::System::setOption	(	const String &	key,
		const void *	value
	)

Method for setting a specific option of the system.

These options are usually specific to the platform the system is running on.

Remarks:

Current options supported are:

• Key: ThreadAffinityMask
  Description: OgreHaptics normally will allow all threads used by the system to run on all available processors given by the OS. The Win32 Ogre::Timer is bound to a single core, normally the lowest core available to the process, to implement a high resolution timer used for OGRE's timings. Since the Ogre::Timer is called every frame the Ogre thread uses the core used by the Ogre::Timer almost exclusively, the binding of the timing calculations can in the case of extensive calculations in the haptic thread result in strong fluctuations in graphic and haptic rendering. In this case the client application might want to change the thread affinity mask used by OgreHaptics. It is up to the user to exclude the core used by the Ogre::Timer, or any other core it wishes not be used by OgreHaptics, from the given bitvector. The given bitvector is checked against the process affinity core mask. If the bitvector does not overlap this mask, the method returns false. The client application can also set the thread affinity mask for a specific RenderSystem. This operation will apply the thread affinity OgreHaptics wide.
  Value: DWORD*
  Default: Affinity mask for the process, allowing threads to be run on all available cores for the process.
  Notes: [Windows specific]

Parameters:

	key	The name of the option to set
	value	A pointer to the value

Returns:

true if the option was successfully set, false otherwise.

bool OgreHaptics::System::getOption	(	const String &	key,
		void *	value
	)

Gets the specified option for the System.

Remarks:

Current options supported are:

• Key: ThreadAffinityMask
  Description: See setOption.
  Notes: [Windows specific] The value might not represent the values of all rendering systems if the client application has set the thread affinity mask on one or more rendering systems directly.

Returns:

true if the option was successfully retrieved, false otherwise.

See also:

System::setOption

Log* OgreHaptics::System::getLog

(

void

)

Returns a pointer to the log used by OgreHaptics.

Definition at line 251 of file OgreHapticsSystem.h.

void OgreHaptics::System::logMessage	(	const String &	message,
		LogMessageLevel	lml = LML_NORMAL,
		bool	maskDebug = false
	)

Log a message to the log used by OgreHaptics.

Log::Stream OgreHaptics::System::logStream	(	LogMessageLevel	lml = LML_NORMAL,
		bool	maskDebug = false
	)

Get a stream on the log used by OgreHaptics.

void OgreHaptics::System::loadPlugin

(

const String &

pluginName

)

Manually load a Plugin contained in a DLL / DSO.

Remarks:

Plugins embedded in DLLs can be loaded at startup using the plugin configuration file specified when you create System (default: hapticsplugins.cfg). This method allows you to load plugin DLLs directly in code. The DLL in question is expected to implement a dllStartPlugin method which instantiates an Ogre::Plugin subclass and calls System::installPlugin. It should also implement dllStopPlugin.

Parameters:

pluginName

Name of the plugin library to load

See also:

System::unloadPlugin

Exceptions:

Ogre::Exception

if dllStartPlugin has not been implemented.

void OgreHaptics::System::unloadPlugin

(

const String &

pluginName

)

Manually unloads a Plugin contained in a DLL / DSO.

Remarks:

Plugin DLLs are unloaded at shutdown automatically. This method allows you to unload plugins in code, but make sure their dependencies are decoupled first. This method will call the dllStopPlugin method defined in the DLL, which in turn should call System::uninstallPlugin.

Parameters:

pluginName

Name of the plugin library to unload

void OgreHaptics::System::installPlugin

(

Plugin *

plugin

)

Install a new Plugin.

Remarks:

This installs a new extension to OgreHaptics. The plugin itself may be loaded from a DLL / DSO

void OgreHaptics::System::uninstallPlugin

(

Plugin *

plugin

)

Uninstall an existing plugin.

Remarks:

This uninstalls an extension to OgreHaptics. Plugins are automatically uninstalled at shutdown but this lets you remove them early. If the plugin was loaded from a DLL / DSO you should call unloadPlugin which should result in this method getting called anyway (if the DLL is well behaved).

const PluginInstanceList& OgreHaptics::System::getInstalledPlugins

(

)

const

Gets a read-only list of the currently installed plugins.

Definition at line 304 of file OgreHapticsSystem.h.

void OgreHaptics::System::addRenderSystem

(

RenderSystem *

newRend

)

Adds a new rendering subsystem to the list of available rendering systems.

Remarks:

This operation is intended for plugins only. Calling this method with a pointer to a valid subclass of RenderSystem adds a haptics rendering API implementation to the list of available ones. Typical examples would be an OpenHaptics or a Falcon/HDAL implementation.

Note:

This should usually be called from the dllStartPlugin() function of an extension plugin.

RenderSystem* OgreHaptics::System::getRenderSystemByName

(

const String &

name

)

Retrieve a pointer to the rendering system by the given name or by the name of the API the RenderSystem supports.

Parameters:

name

Name of the rendering system intend to retrieve.

Returns:

A pointer to the rendering system, NULL if no found.

RenderSystemList* OgreHaptics::System::getAvailableRenderSystems

(

void

)

Retrieve a list of the available render systems.

const DeviceInfoList& OgreHaptics::System::getAvailableNamedDevices

(

void

)

const

Obtains an iterator over all haptics devices available on the users system supported through loaded Plugins.

Remarks:

The iterator iterates over a list of DeviceInfo entries. These entries can be used to create instances of haptics devices.

Exceptions:

Ogre::Exception

unsigned int OgreHaptics::System::getNumConnectedDevices

(

void

)

Returns the total number of available devices on all registered render systems.

Device* OgreHaptics::System::createDevice	(	const String &	name,
		const DeviceInitInfo &	initInfo
	)

Creates a new named Device.

Remarks:

This method creates a subclass of the Device depending on the API for which the render system is implemented. Named devices can be obtained using the getAvailableNamedDevices method.

Different names might point to the same actual device, depending on API implementation, but with different settings specified in a configuration file. This method will not catch any error when a physical device is being tried to initialised using different settings.

After the creation of the first device subsystems needed will be initialised.

Parameters:

	name	The name of the Device to create.
	initInfo	Structure holding initialisation data, such as the underlying API to use for instantation and the name to be used for initialisation.

Exceptions:

A

DuplicateItemException if a device with the initName or index specified already exists.

See also:

System::getAvailableNamedDevices

Device* OgreHaptics::System::createDevice	(	const String &	name,
		unsigned int	index,
		DeviceInitInfo &	initInfo
	)

Creates a new named Device.

Remarks:

This method creates a subclass of the Device depending on the API for which the render system is implemented based on zero-based indexing.

The behaviour of an indexed device depends on the API implementation. The Falcon/HDAL API allows to specify specific devices to be indexed based on the serial numbers of the devices available on the system in a configuration file. The zero-based index specifies the device in an alphabetically sorted list. For the OpenHaptics API the index will point to the position in the list of available devices, which is the same as can be read in the Sensable PHANToM configuration dialog.

Parameters:

	name	The name of the Device to create.
	index	The zero-based API specific index to identify the device to instantiate.
	initInfo	Structure holding initialisation data, such as the underlying API to use for instantation and the name to be used for initialisation. The initName property of this structure will be ignored and modified to reflect the actual initName used.

Exceptions:

A

DuplicateItemException if a device with the initName or index specified already exists.

See also:

RenderSystem::getNumConnectedDevices

Device* OgreHaptics::System::getDevice

(

const String &

name

)

Retrieves a pointer to a named Device.

Parameters:

name

The name of the device to retrieve.

Exceptions:

ItemNotFoundException

if no Device could be found.

See also:

System::createDevice

void OgreHaptics::System::destroyDevice

(

const String &

name

)

Destroys a named device.

Parameters:

name

The name of the device to be destroyed.

void OgreHaptics::System::destroyDevice

(

Device *

device

)

Destroys the given Device.

void OgreHaptics::System::destroyAllDevices

(

void

)

Removes and destroys all devices created through the registered rendering systems.

Remarks:

The schedulers used by the rendering systems will be stopped.

ConstDeviceIterator OgreHaptics::System::getDeviceIterator

(

void

)

const

Returns a specialised Ogre::ConstDeviceIterator on all devices created by all registered rendering systems.

void OgreHaptics::System::startSchedulers	(	unsigned long	rate = 1000,
		bool	autoEnableDevices = true
	)

Starts all schedulers used to manage the haptic threads of all registered render systems.

Remarks:

If autoEnableDevices is set to true all devices managed by the rendering systems will be enabled, including those that have been disabled manually. An update frequency of 1 kHz is typical for most haptic applications.

Not all rendering systems support different scheduler rates. Falcon supports only 1 kHz, while OpenHaptics supports 500, 1000 and 2000 Hz for PPE and PCI devices. For IEEE1394 (FireWire) connections OpenHaptics supports 500, 1000, 1600 and some values based on floor(8000/N + .5).

Be cautious to set any other update rate than 1000 Hz. Decreasing this rate may result in instable rendering, while increasing the rate can result in better haptic rendering, though this leaves less time for haptic calculations to complete. To verify if the set rate can be maintained by the haptic renderer read the device statistics on a highly regular basis.

Note:

The scheduler will not be started when none of the devices managed by the rendering system is initialised.

Parameters:

	rate	The rate of the scheduler in Hertz.
	autoEnableDevices	Specifies whether or not the devices should be enabled automatically.

Exceptions:

An

Exception if a scheduler has already been started.

void OgreHaptics::System::stopSchedulers

(

void

)

Stops the schedulers used by the registered rendering systems.

See also:

System::startSchedulers

void OgreHaptics::System::update

(

void

)

Updates all devices managed by the registered render systems.

See also:

Device::update

void OgreHaptics::System::_oneTimePostDeviceCreate

(

void

)

Operation for one time task to be performed after device creation.

Remarks:

This operation must be called by the client application when a Device is created using RenderSystem::_createDevice

void OgreHaptics::System::loadPlugins

(

const String &

pluginsFileName = "HapticsPlugins.cfg"

)

[protected]

Method reads a plugins configuration file and instantiates all plugins.

Parameters:

pluginsFileName

The name of the file that contains plugin information, defaults to 'HapticsPlugins.cfg'.

void OgreHaptics::System::initialisePlugins

(

void

)

[protected]

Initialise all loaded plugins - allows plugins to perform actions once the system has been initialised.

void OgreHaptics::System::shutdownPlugins

(

void

)

[protected]

Shuts down all loaded plugins - allows things to be tidied up whilst all plugins are still loaded.

void OgreHaptics::System::unloadPlugins

(

void

)

[protected]

Unloads all loaded plugins.

---

Member Data Documentation

OGREHAPTICS_AUTO_MUTEX bool OgreHaptics::System::mIsInitialised [protected]

Private mutex, not allowed to lock from outside.

Are we initialised yet?

Definition at line 473 of file OgreHapticsSystem.h.

bool OgreHaptics::System::mFirstTimePostDeviceCreate [protected]

Is the initialisation of subsystems done after the first device.

has been created?

Definition at line 476 of file OgreHapticsSystem.h.

String OgreHaptics::System::mConfigFileName [protected]

Name of the haptics configuration file to be used.

Definition at line 478 of file OgreHapticsSystem.h.

DeviceInitInfo OgreHaptics::System::mConfigSettings [protected]

DeviceInfo structure holding information about the device to create.

Definition at line 480 of file OgreHapticsSystem.h.

PluginLibList OgreHaptics::System::mPluginLibs [protected]

List of Plugin DLLs loaded.

Definition at line 482 of file OgreHapticsSystem.h.

PluginInstanceList OgreHaptics::System::mPlugins [protected]

List of Plugin instances registered.

Definition at line 484 of file OgreHapticsSystem.h.

---

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

• OgreHapticsSystem.h