OgreHaptics::RenderSystem Class Reference

Abstract class defining the interface of a haptics rendering system, through which API wide settings and schedulers can be controlled. More...

#include <OgreHapticsRenderSystem.h>

List of all members.

Public Member Functions
	RenderSystem ()
	Default constructor.
virtual	~RenderSystem ()
	Virtual destructor.
virtual const String &	getName (void) const =0
	Returns the name of the rendering system.
virtual const String &	getDefaultDeviceInitName (void) const =0
	Returns the name used for initialisation of the default device.
virtual const DeviceInfoList &	getAvailableNamedDevices (void)=0
	Obtains a list of DeviceInfo entries describing all haptics devices available by a specific name on the users system supported through this RenderSystem.
virtual unsigned int	getNumConnectedDevices (void)=0
	Returns the number of devices connected to the users machine.
Device *	_createDevice (const String &name, System *system, const DeviceInitInfo &info)
	Creates a new Device instance.
Device *	_createDevice (const String &name, unsigned int index, System *system, DeviceInitInfo &info)
void	_destroyDevice (Device *device)
	Removes and destroys an instance of the Device class (internal use only).
virtual bool	setOption (const String &key, const void *value)
	Method for setting a specific option of the rendering system.
virtual bool	getOption (const String &key, void *value)
	Gets the specified option for the System.
virtual void	startScheduler (unsigned long rate=1000, bool autoEnableDevices=true)=0
	Starts the scheduler used for managing the haptic thread of the rendering system.
virtual void	stopScheduler (bool autoDisableDevices=true)=0
	Stops the scheduler used by the rendering system.
bool	isSchedulerStarted (void) const
	Returns whether the scheduler of the haptics rendering system has been started or not.
unsigned long	getSetSchedulerRate (void) const
	Returns the rate of the scheduler as set in startScheduler.
Timer *	getTimer (void) const
	Returns a pointer to the timer used by the rendering system.
virtual void	_scheduleSynchronousCallback (SchedulerCallback callback, void *params)=0
	Schedules a synchronous callback to be executed from the haptic thread.
virtual short	_scheduleAsynchronousCallback (SchedulerCallback callback, void *params)=0
	Scheduls an asynchronous callback to be executed from the haptic thread.
virtual void	_unscheduleAsynchronousCallback (short id)=0
	Unschedules a previously scheduled asynchronous callback.
virtual String	getErrorDescription (long errorNumber) const =0
	Returns a description of an error code.
Protected Member Functions
virtual Device *	createDeviceImpl (const String &name, const DeviceInitInfo &initInfo)=0
	Internal implementation of create method.
virtual Device *	createDeviceImpl (const String &name, unsigned int index, const DeviceInitInfo &initInfo)=0
	Internal implementation of create method.
virtual String	getInitNameByIndex (unsigned int index)=0
	Internal method to obtain the initialisation name based on the given zero-based index.
virtual void	initConfigOptions (DeviceInitInfo &info)=0
virtual void	_notifyThreadAffinityChanged (void)=0
	Notifies devices created through a subclass of the RenderSystem class the thread affinity mask has been changed.
Protected Attributes
Timer *	mTimer
	Pointer to the timer used for timings in this rendering system.
bool	mIsSchedulerStarted
	Has the scheduler of the haptics rendering system been started?
unsigned long	mSetSchedulerRate
	The scheduler rate as set when started.
bool	mAvailableDevicesDirty
	Has the list of available devices been build?
DeviceInfoList	mAvailableDevices
	List of available devices.
DeviceMap	mDevices
	List of devices created through the rendering system.
DWORD	mThreadAffinityMask
	The thread affinity mask used by the scheduler of the rendering system.
Static Protected Attributes
static short	msNextAsynchronousCallbackID
	The next callback ID.

---

Detailed Description

Abstract class defining the interface of a haptics rendering system, through which API wide settings and schedulers can be controlled.

Remarks:

The RenderSystem class provides a base interface which abstracts the general functionality of a haptics API, such as OpenHaptics or Falcon/HDAL (used for the Falcon). Whilst a few of the general methods have implementations, most of this class is abstract, requiring a subclass to provide full functionality.

Most users of OgreHaptics will not need to communicate with this class directly, but will use classes which are part of a system, such as the Device class.

Todo:

Test availability of 3rd party libraries (must be done when plugin is installed?)

Definition at line 49 of file OgreHapticsRenderSystem.h.

---

Constructor & Destructor Documentation

OgreHaptics::RenderSystem::RenderSystem

(

)

Default constructor.

virtual OgreHaptics::RenderSystem::~RenderSystem

(

)

[virtual]

Virtual destructor.

---

Member Function Documentation

virtual const String& OgreHaptics::RenderSystem::getName

(

void

)

const [pure virtual]

Returns the name of the rendering system.

virtual const String& OgreHaptics::RenderSystem::getDefaultDeviceInitName

(

void

)

const [pure virtual]

Returns the name used for initialisation of the default device.

virtual const DeviceInfoList& OgreHaptics::RenderSystem::getAvailableNamedDevices

(

void

)

[pure virtual]

Obtains a list of DeviceInfo entries describing all haptics devices available by a specific name on the users system supported through this RenderSystem.

Remarks:

Based on the implementation the system searches the registry (Windows) or uses .ini files provided with the client application and/or by the driver manufacturer to obtain devices which are available by a specific name. Since devices can be identified through multiple ID's the client application needs to verify it can successfully initialise devices needed.

Named devices can be used in environments where specific devices are to be used for a specific (sub)set of controls. In example, an application might implement one device for the left hand and one for the right hand, and the left device is used to control different aspects of the application as opposed to the right device.

For the Falcon API LEDs of the devices might blink.

virtual unsigned int OgreHaptics::RenderSystem::getNumConnectedDevices

(

void

)

[pure virtual]

Returns the number of devices connected to the users machine.

Remarks:

When devices are connected or disconnected during run-time this results in undefined behaviour.

Device* OgreHaptics::RenderSystem::_createDevice	(	const String &	name,
		System *	system,
		const DeviceInitInfo &	info
	)

Creates a new Device instance.

Remarks:

This method creates a subclass of the Device depending on the API for which the render system is implemented. It allows to create a named device or a device based on indexing. 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.

The behaviour of an indexed devicedepends 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.

If you call this operation directly and it is the first device that is created you need to call System::_oneTimePostDeviceCreate to initialise the subsystems needed.

Parameters:

	info	A DeviceInfo struct, which is obtained through getAvailableNamedDevices, specifying the parameters needed for the creation and initialisation of the device.
	index	The index of the device to initialise. Will override the initName of the info struct if larger than 0.

See also:

RenderSystem::getAvailableNamedDevices

Exceptions:

A

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

Device* OgreHaptics::RenderSystem::_createDevice	(	const String &	name,
		unsigned int	index,
		System *	system,
		DeviceInitInfo &	info
	)

void OgreHaptics::RenderSystem::_destroyDevice

(

Device *

device

)

Removes and destroys an instance of the Device class (internal use only).

virtual bool OgreHaptics::RenderSystem::setOption	(	const String &	key,
		const void *	value
	)			[virtual]

Method for setting a specific option of the rendering system.

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

Remarks:

Current options supported are:

• Key: ThreadAffinityMask
  Description: Sets the thread affinity mask used by the rendering system. See System::setOption for further explanation.
  Value: DWORD*
  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.

virtual bool OgreHaptics::RenderSystem::getOption	(	const String &	key,
		void *	value
	)			[virtual]

Gets the specified option for the System.

Remarks:

Current options supported are:

• Key: ThreadAffinityMask
  Description: See System::setOption.

Returns:

true if the option was successfully retrieved, false otherwise.

See also:

System::setOption

virtual void OgreHaptics::RenderSystem::startScheduler	(	unsigned long	rate = 1000,
		bool	autoEnableDevices = true
	)			[pure virtual]

Starts the scheduler used for managing the haptic thread of the rendering system.

Remarks:

If autoEnableDevices is set to true all devices managed by the rendering system 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 suuports 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 the scheduler has already been started

virtual void OgreHaptics::RenderSystem::stopScheduler

(

bool

autoDisableDevices = true

)

[pure virtual]

Stops the scheduler used by the rendering system.

Remarks:

If autoDisableDevices is set to true all devices managed by the rendering system will be disabled. This ensures they are not enabled automatically when the scheduler is restarted with autoEnableDevices = false.

Parameters:

autoDisableDevices

Specifies whether or not the devices should be disabled automatically.

See also:

RenderSystem::startScheduler

bool OgreHaptics::RenderSystem::isSchedulerStarted

(

void

)

const

Returns whether the scheduler of the haptics rendering system has been started or not.

Definition at line 209 of file OgreHapticsRenderSystem.h.

unsigned long OgreHaptics::RenderSystem::getSetSchedulerRate

(

void

)

const

Returns the rate of the scheduler as set in startScheduler.

Remarks:

If the scheduler has not been started yet, 0 will be returned.

Returns:

The scheduler rate as set in the last call of startScheduler

See also:

RenderSystem::startScheduler

Definition at line 218 of file OgreHapticsRenderSystem.h.

Timer* OgreHaptics::RenderSystem::getTimer

(

void

)

const

Returns a pointer to the timer used by the rendering system.

Definition at line 221 of file OgreHapticsRenderSystem.h.

virtual void OgreHaptics::RenderSystem::_scheduleSynchronousCallback	(	SchedulerCallback	callback,
		void *	params
	)			[pure virtual]

Schedules a synchronous callback to be executed from the haptic thread.

Remarks:

A synchronous callback is typically used to synchronise data between the haptic thread and the calling thread. The calling thread waits for the callback to be completed.

The number of synchronous callbacks to be performed from multiple threads depends on the API used to implement the Device class. HDAL/Falcon allows only one synchronous callback at a time. In this case the scheduling of synchronous callbacks is made thread safe.

Parameters:

	callback	The function callback.
	params	A pointer to parameter(s) to be passed to the callback.

Exceptions:

An

HapticAPIException if the scheduling of the callback fails.

virtual short OgreHaptics::RenderSystem::_scheduleAsynchronousCallback	(	SchedulerCallback	callback,
		void *	params
	)			[pure virtual]

Scheduls an asynchronous callback to be executed from the haptic thread.

Remarks:

An asynchronous callback is typically used to calculate forces and apply these forces to the device. The callback is called every haptic frame and the calling thread will not wait for the callback to be completed.

Parameters:

	callback	The function callback.
	params	A pointer to parameter(s) to be passed to the callback.

Returns:

An id of the asynchronous callback handle, used to remove the callback if needed.

Exceptions:

An

HapticAPIException if the scheduling of the callback fails.

virtual void OgreHaptics::RenderSystem::_unscheduleAsynchronousCallback

(

short

id

)

[pure virtual]

Unschedules a previously scheduled asynchronous callback.

Parameters:

id

The id of the asynchronous callback handle to be removed.

Exceptions:

An

HapticsAPIException if the unscheduling of the callback fails.

See also:

Device::_scheduleAsynchronousCallback

virtual String OgreHaptics::RenderSystem::getErrorDescription

(

long

errorNumber

)

const [pure virtual]

Returns a description of an error code.

virtual Device* OgreHaptics::RenderSystem::createDeviceImpl	(	const String &	name,
		const DeviceInitInfo &	initInfo
	)			[protected, pure virtual]

Internal implementation of create method.

virtual Device* OgreHaptics::RenderSystem::createDeviceImpl	(	const String &	name,
		unsigned int	index,
		const DeviceInitInfo &	initInfo
	)			[protected, pure virtual]

Internal implementation of create method.

virtual String OgreHaptics::RenderSystem::getInitNameByIndex

(

unsigned int

index

)

[protected, pure virtual]

Internal method to obtain the initialisation name based on the given zero-based index.

virtual void OgreHaptics::RenderSystem::initConfigOptions

(

DeviceInitInfo &

info

)

[protected, pure virtual]

virtual void OgreHaptics::RenderSystem::_notifyThreadAffinityChanged

(

void

)

[protected, pure virtual]

Notifies devices created through a subclass of the RenderSystem class the thread affinity mask has been changed.

---

Member Data Documentation

short OgreHaptics::RenderSystem::msNextAsynchronousCallbackID [static, protected]

The next callback ID.

Subclasses must increment this when a new asychronous callback is scheduled.

Definition at line 268 of file OgreHapticsRenderSystem.h.

Timer* OgreHaptics::RenderSystem::mTimer [protected]

Pointer to the timer used for timings in this rendering system.

Definition at line 271 of file OgreHapticsRenderSystem.h.

bool OgreHaptics::RenderSystem::mIsSchedulerStarted [protected]

Has the scheduler of the haptics rendering system been started?

Definition at line 273 of file OgreHapticsRenderSystem.h.

unsigned long OgreHaptics::RenderSystem::mSetSchedulerRate [protected]

The scheduler rate as set when started.

Definition at line 275 of file OgreHapticsRenderSystem.h.

bool OgreHaptics::RenderSystem::mAvailableDevicesDirty [protected]

Has the list of available devices been build?

Definition at line 277 of file OgreHapticsRenderSystem.h.

DeviceInfoList OgreHaptics::RenderSystem::mAvailableDevices [protected]

List of available devices.

Definition at line 279 of file OgreHapticsRenderSystem.h.

DeviceMap OgreHaptics::RenderSystem::mDevices [protected]

List of devices created through the rendering system.

Used for updating and auto starting devices.

Definition at line 282 of file OgreHapticsRenderSystem.h.

DWORD OgreHaptics::RenderSystem::mThreadAffinityMask [protected]

The thread affinity mask used by the scheduler of the rendering system.

Definition at line 300 of file OgreHapticsRenderSystem.h.

---

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

• OgreHapticsRenderSystem.h