OgreHaptics::ForceEffect Class Reference

A ForceEffect provides a way to render forces to a Device to simulate arbitrary sensations. More...

#include <OgreHapticsForceEffect.h>

List of all members.

Public Types

typedef VectorIterator
< ForceEffectAlgorithmList > 		AlgorithmIterator

Public Member Functions

 ForceEffect (const String &name)
 Constructor - use ForceEffectManager's create method rather than this.
virtual ~ForceEffect ()
 Virtual destructor.
ForceEffect & operator= (const ForceEffect &rhs)
 Assignment operator to allow easy copying between force effects.
const String & getName (void) const
 Returns the name of the force effect.
const String & getOrigin (void) const
 Get the origin of this force effect, e.g.
void _notifyOrigin (const String &origin)
 Notify this force effect of it's origin.
void start (Device *device)
 Starts the ForceEffect to be rendered by the specified Device.
void restart (void)
 Restarts the force effect for the device specified at ForceEffect::start.
void stop (bool immediate=false)
 Stops the force effect from rendering.
bool isActive (void) const
 Returns whether or not the force effect is actively rendered or will be rendered the next time Device::update is called on the device the force effect was started for.
ForceEffectState getState (void) const
 Returns the current state the force effect is in.
void _notifyDeviceDisabled (void)
 Notify this force effect the device it is rendering force to has been disabled.
void setSustainMode (ForceEffectSustainMode mode)
 Sets the ForceEffectMode that the sustaining state of the force effect will be in.
ForceEffectSustainMode getSustainMode (void) const
 Returns the ForceEffectMode of the sustaining state.
void setSustainDuration (long duration)
 Sets the duration of the sustaining state in milliseconds.
long getSustainDuration (void) const
 Returns the number of milliseconds for the ForceEffect to be in sustaining state.
void setFadeInDuration (long duration)
 Sets the duration of the fading in state.
long getFadeInDuration (void) const
 Returns the number of milliseconds for the ForceEffect to be in fading in state.
void setFadeOutDuration (long duration)
 Sets the duration of the fading out state.
long getFadeOutDuration (void) const
 Returns the number of milliseconds for the ForceEffect to be in fading out state.
long getRemainingTime (ForceEffectTimeType type=FETT_TOTAL) const
 Returns the remaining time of the ForceEffect to render forces.
void setListener (Listener *listener)
 Sets a listener for the force effect.
Listener * getListener (void) const
 Gets the current listener of the force effect.
void setAlgorithmParameter (unsigned short index, const String &name, const String &value)
 Method to set the value of a parameter on the indexed algorithm in an internally thread safe manner.
void setAlgorithmParameterList (unsigned short index, const NameValuePairList &paramList)
 Method to set multiple parameters on the indexed algorithm in an internally thread safe manner.
void setAllAlgorithmsParameter (const String &name, const String &value)
 Convenience method to set the value of a parameter on all added algorithms in an internally thread safe manner.
void setAllAlgorithmsParameterList (const NameValuePairList &paramList)
 Convenience method to set multiple parameters on all added algorithms in an internally thread safe manner.
ForceEffectAlgorithm * addAlgorithm (const String &algorithmType)
 Adds a ForceEffectAlgorithm to the list of algorithms used by the force effect to render forces.
ForceEffectAlgorithm * getAlgorithm (unsigned short index) const
 Retrieves an algorithm by it's index (zero-based).
void removeAlgorithm (unsigned short index)
 Removes an algorithm for the force effect.
void removeAllAlgorithms (void)
 Removes all algorithms registerd with the force effect.
unsigned short getNumAlgorithms (void) const
 Returns the number of algorithms for the force effect.
AlgorithmIterator getAlgorithmIterator (void)
 Returns an iterator over the list of registered algorithms.
void _applyAlgorithmParameters (void)
 Applies the parameters set to the algorithms through setAlgorithmParameter and setAlgorithmsParameter.
void _setState (ForceEffectState state, double currentTime)
 Sets the state of the force effect (internal use only).
void _resetAlgorithms (void)
 Resets all registered algorithms (internal use only).
const ForceOutput & _calculateForces (const Vector3 &position, const Quaternion &orientation, const Vector3 &linearVelocity, const Vector3 &angularVelocity, double timeElapsed)
 Calculates the forces the effect will apply to the device the effect has been started for (internal use only).
Real _getLerpFraction (double currentTime, bool fadingIn)
 Returns the linear interpolation fraction for fading the force effect (internal use only).

Protected Types

typedef std::map< unsigned
short, NameValuePairList > 		AlgorithmsParameterMap

Protected Member Functions

void updateRemainingTime (double timeElapsed)
 Updates the remaining time the force effect will actively render output.

Protected Attributes

Device * mDevice
 Pointer to the device for which the force effect was started.
Listener * mListener
 Pointer to the listener of events.
bool mhtIsMaxLerpFractionSet
 Has the maximum linear interpolation fraction been set?
long mhtCurrentStateDuration
 The duration of the current state, in milliseconds.
double mhtCurrentStateStartTime
 The time at which the current state was started.
Real mhtMaxLerpFraction
 The maximum linear interpolation fraction used for fading.
ForceEffectSustainMode mSustainMode
 The mode the force effect will remain in in the sustain state.
String mName
 Name of the force effect.
String mOrigin
 Optional origin of this force effect (e.g. script name).
AtomicScalar< ForceEffectState > mState
 Is the force effect being used for rendering?
AtomicScalar< long > mSustainDuration
 The time of the sustaining state of the effect, in milliseconds.
AtomicScalar< long > mFadeInDuration
 The time to fade the effect in after it has been started, in milliseconds.
AtomicScalar< long > mFadeOutDuration
 The time to fade the effect out after it has been stopped, in milliseconds.
AtomicScalar< int > mDurationChanged
 Has the any duration been changed?
AtomicScalar< long > mCurrentStateRemainingTime
 The time in milliseconds the effect remains in in its current state.
AtomicScalar< long > mTotalRemainingTime
 The time in milliseconds the effect remains active.
ForceOutput mOutput
 The force output by the force effect.
ForceEffectAlgorithmList mAlgorithms
 A list of all algorithms used.
AlgorithmsParameterMap mAlgorithmsParameterMap
 Used to store name/value pairs to update algoritm parameters.

Static Protected Attributes

static CmdSustainMode msSustainModeCmd
static CmdSustainDuration msSustainDurationCmd
static CmdFadeInDuration msFadeInDurationCmd
static CmdFadeOutDuration msFadeOutDurationCmd

Friends

class ForceEffectManager

Classes

class  CmdFadeInDuration
 Command object for fade_in_duration (see Ogre::ParamCommand). More...
class  CmdFadeOutDuration
 Command object for fade_out_duration (see Ogre::ParamCommand). More...
class  CmdSustainDuration
 Command object for sustain_duration (see Ogre::ParamCommand). More...
class  CmdSustainMode
 Command object for sustain_mode (see Ogre::ParamCommand). More...
class  Listener

Detailed Description

A ForceEffect provides a way to render forces to a Device to simulate arbitrary sensations.

Force effects are typically used to generate ambient sensations, like drag, inertia or gravity. These sensations are ambient because they apply throughout the touch space. Force effects can also be used to generate transient sensations, like an impulse.

Remarks:
A ForceEffect can be started or stopped in response to events, such as pressing a button. A force effect persist until stopped or until the duration has elapsed.
Force effects are created using the ForceEffectManager, never directly.
Todo:
  • Add Listener to listen for state change events

Definition at line 100 of file OgreHapticsForceEffect.h.

Member Typedef Documentation

typedef VectorIterator<ForceEffectAlgorithmList> OgreHaptics::ForceEffect::AlgorithmIterator

Definition at line 441 of file OgreHapticsForceEffect.h.

typedef std::map<unsigned short, NameValuePairList> OgreHaptics::ForceEffect::AlgorithmsParameterMap [protected]

Definition at line 530 of file OgreHapticsForceEffect.h.

Constructor & Destructor Documentation

OgreHaptics::ForceEffect::ForceEffect ( const String &  name  ) 

Constructor - use ForceEffectManager's create method rather than this.

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

Virtual destructor.

Member Function Documentation

ForceEffect& OgreHaptics::ForceEffect::operator= ( const ForceEffect &  rhs  ) 

Assignment operator to allow easy copying between force effects.

Remarks:
The effect's name is not copied.

const String& OgreHaptics::ForceEffect::getName ( void   )  const

Returns the name of the force effect.

Definition at line 171 of file OgreHapticsForceEffect.h.

const String& OgreHaptics::ForceEffect::getOrigin ( void   )  const

Get the origin of this force effect, e.g.

a script file name.

Remarks:
This property will only contain something if the creator of this force effect chose to populate it. Script loaders are advised to populate it.

Definition at line 180 of file OgreHapticsForceEffect.h.

void OgreHaptics::ForceEffect::_notifyOrigin ( const String &  origin  ) 

Notify this force effect of it's origin.

Definition at line 182 of file OgreHapticsForceEffect.h.

void OgreHaptics::ForceEffect::start ( Device *  device  ) 

Starts the ForceEffect to be rendered by the specified Device.

Remarks:
The force effect will be added to a list of force effects to start and to be rendering by the given device. Only after calling Device::update the force effect will be rendered. In the case the force effect is already being rendered to the given device, it will be restarted automatically.
Parameters:
device The Device through which the effect will be rendered.
Exceptions:
InvalidOperationException if the effect is already actively rendering on another device.

void OgreHaptics::ForceEffect::restart ( void   ) 

Restarts the force effect for the device specified at ForceEffect::start.

Remarks:
The ForceEffect will not fade out before restart.
Exceptions:
InvalidOperationException if the effect has not been started before.

void OgreHaptics::ForceEffect::stop ( bool  immediate = false  ) 

Stops the force effect from rendering.

Remarks:
After calling this the force effect will fade out. If it is needed to stop the effect immediately, you need to call this with true.
Parameters:
immediate Specifies whether or not the force effect will be stopped immediately.

bool OgreHaptics::ForceEffect::isActive ( void   )  const

Returns whether or not the force effect is actively rendered or will be rendered the next time Device::update is called on the device the force effect was started for.

ForceEffectState OgreHaptics::ForceEffect::getState ( void   )  const

Returns the current state the force effect is in.

void OgreHaptics::ForceEffect::_notifyDeviceDisabled ( void   ) 

Notify this force effect the device it is rendering force to has been disabled.

Internal use only.

Remarks:
In the case a device is destroyed or disabled, while force effects are still actively rendering forces to this device, we need to notify the force effect the device has stopped rendering. This method provides the means to do so.

void OgreHaptics::ForceEffect::setSustainMode ( ForceEffectSustainMode  mode  ) 

Sets the ForceEffectMode that the sustaining state of the force effect will be in.

Parameters:
mode The new mode of the force effect.
Remarks:
Changing the ForceEffectMode while the force effect is active will not have any result.
When set to ForceEffectMode::FEM_TEMPORAL and the sustain duration is not set, the force effect will fade out or stop after fading in or starting.

ForceEffectSustainMode OgreHaptics::ForceEffect::getSustainMode ( void   )  const

Returns the ForceEffectMode of the sustaining state.

Definition at line 248 of file OgreHapticsForceEffect.h.

void OgreHaptics::ForceEffect::setSustainDuration ( long  duration  ) 

Sets the duration of the sustaining state in milliseconds.

Remarks:
This duration will only be used if the force effect is started with the sustaining mode set to temporal.
Parameters:
duration The duration in milliseconds for the sustaining state.
See also:
ForceEffect::setSustainMode

long OgreHaptics::ForceEffect::getSustainDuration ( void   )  const

Returns the number of milliseconds for the ForceEffect to be in sustaining state.

Returns:
The number of milliseconds as set for temporal sustain mode or the maximum possible of long.

void OgreHaptics::ForceEffect::setFadeInDuration ( long  duration  ) 

Sets the duration of the fading in state.

Remarks:
Setting this to 0 will cause the force effect to immediately go into sustaining state when started.
Parameters:
duration The duration in milliseconds for the fading in state.

long OgreHaptics::ForceEffect::getFadeInDuration ( void   )  const

Returns the number of milliseconds for the ForceEffect to be in fading in state.

void OgreHaptics::ForceEffect::setFadeOutDuration ( long  duration  ) 

Sets the duration of the fading out state.

Remarks:
Setting this to 0 will cause the force effect to immediately stop rendering forces.
Parameters:
duration The duration in milliseconds for the fading out state.

long OgreHaptics::ForceEffect::getFadeOutDuration ( void   )  const

Returns the number of milliseconds for the ForceEffect to be in fading out state.

long OgreHaptics::ForceEffect::getRemainingTime ( ForceEffectTimeType  type = FETT_TOTAL  )  const

Returns the remaining time of the ForceEffect to render forces.

Parameters:
type Specifies whether the total remaining time or the remaining time of the current state is returned.

void OgreHaptics::ForceEffect::setListener ( Listener *  listener  ) 

Sets a listener for the force effect.

Remarks:
For size and performance reasons only one listener per force effect is allowed.

Definition at line 305 of file OgreHapticsForceEffect.h.

Listener* OgreHaptics::ForceEffect::getListener ( void   )  const

Gets the current listener of the force effect.

Definition at line 307 of file OgreHapticsForceEffect.h.

void OgreHaptics::ForceEffect::setAlgorithmParameter ( unsigned short  index,
const String &  name,
const String &  value 
)

Method to set the value of a parameter on the indexed algorithm in an internally thread safe manner.

Remarks:
The ForceEffectAlgorithm class is not thread safe, e.g. setting a parameter directly on the algorithm might result in undefined behaviour. This method provides the means to set a named parameter on a single algorithm in a thread safe manner.
You should check how many algorithms are registered against the force effect before calling this method with an arbitrary index using getNumAlgorithms.
If the force effect is actively rendering, the parameter will be updated the next time Device::update is called. Otherwise the parameters is updated immediately.
A getter operation which mirrors this setter method is not implemented. Use ForceEffect::getAlgorithm to obtain the algorithm to read the parameter.
See Ogre::StringInterface::setParameter
Parameters:
index Zero-based index of the algorithm to set the parameter on.
name The name of the parameter to update.
value The Ogre::String value of the parameter. Must be in the right format for the type specified in the parameter definition.

void OgreHaptics::ForceEffect::setAlgorithmParameterList ( unsigned short  index,
const NameValuePairList &  paramList 
)

Method to set multiple parameters on the indexed algorithm in an internally thread safe manner.

Remarks:
The ForceEffectAlgorithm class is not thread safe, e.g. setting a parameter directly on the algorithm might result in undefined behaviour. This method provides the means to set multiple parameters on a single algorithm in a thread safe manner.
You should check how many algorithms are registered against the force effect before calling this method with an arbitrary index using getNumAlgorithms.
If the force effect is actively rendering, the parameter will be updated the next time Device::update is called. Otherwise the parameters is updated immediately.
See Ogre::StringInterface::setParameterList
Parameters:
index Zero-based index of the algorithm to set the parameter on.
paramList An name/value pair list.

void OgreHaptics::ForceEffect::setAllAlgorithmsParameter ( const String &  name,
const String &  value 
)

Convenience method to set the value of a parameter on all added algorithms in an internally thread safe manner.

Remarks:
The ForceEffectAlgorithm class is not thread safe, e.g. setting a parameter directly on the algorithm might result in undefined behaviour. This method provides the means to set a named parameter on a all added algorithm in a thread safe manner.
If the force effect is actively rendering, the parameter will be updated the next time Device::update is called. Otherwise the parameters are updated immediately.
See Ogre::StringInterface::setParameter
Parameters:
name The name of the parameter to update.
value The Ogre::String value of the parameter. Must be in the right format for the type specified in the parameter definition.

void OgreHaptics::ForceEffect::setAllAlgorithmsParameterList ( const NameValuePairList &  paramList  ) 

Convenience method to set multiple parameters on all added algorithms in an internally thread safe manner.

Remarks:
The ForceEffectAlgorithm class is not thread safe, e.g. setting a parameter directly on the algorithm might result in undefined behaviour. This method provides the means to set multiple parameters on a all added algorithm in a thread safe manner.
If the force effect is actively rendering, the parameter will be updated the next time Device::update is called. Otherwise the parameters are updated immediately.
See Ogre::StringInterface::setParameterList
Parameters:
paramList A name/value pair list.

ForceEffectAlgorithm* OgreHaptics::ForceEffect::addAlgorithm ( const String &  algorithmType  ) 

Adds a ForceEffectAlgorithm to the list of algorithms used by the force effect to render forces.

Remarks:
Algorithm types can be extended by OgreHaptics, plugin authors or application developers.
Exceptions:
InvalidOperationException if the force effect is active.

ForceEffectAlgorithm* OgreHaptics::ForceEffect::getAlgorithm ( unsigned short  index  )  const

Retrieves an algorithm by it's index (zero-based).

Remarks:
The ForceEffectAlgorithm class is not thread safe. Since the algorithm might be used by the haptic thread, modifying a parameter on the algorithm while the force effect using the algorithm is active results in undefined behaviour.
You should check how many algorithms are registered against the force effect before calling this method with an arbitrary index using getNumAlgorithms.
You can set a parameter on an algorithm in a thread safe manner through ForceEffect::setAlgorithmParameter.
Parameters:
index Zero-based index of the algorithm to retrieve.

void OgreHaptics::ForceEffect::removeAlgorithm ( unsigned short  index  ) 

Removes an algorithm for the force effect.

You should check how many algorithms are registered against the force effect before calling this method with an arbitrary index using getNumAlgorithms.
Parameters:
index Zero-based index of the algorithm to remove.
Exceptions:
InvalidOperationException if the force effect is active.

void OgreHaptics::ForceEffect::removeAllAlgorithms ( void   ) 

Removes all algorithms registerd with the force effect.

Exceptions:
InvalidOperationException if the force effect is active.

unsigned short OgreHaptics::ForceEffect::getNumAlgorithms ( void   )  const

Returns the number of algorithms for the force effect.

AlgorithmIterator OgreHaptics::ForceEffect::getAlgorithmIterator ( void   ) 

Returns an iterator over the list of registered algorithms.

Remarks:
The ForceEffectAlgorithm class is not thread safe. Since the algorithm might be used by the haptic thread, modifying a parameter on the algorithm while the force effect using the algorithm is active results in undefined behaviour.

void OgreHaptics::ForceEffect::_applyAlgorithmParameters ( void   ) 

Applies the parameters set to the algorithms through setAlgorithmParameter and setAlgorithmsParameter.

Internal use only.

void OgreHaptics::ForceEffect::_setState ( ForceEffectState  state,
double  currentTime 
)

Sets the state of the force effect (internal use only).

Remarks:
Allows to set the state of the force effect externally.
Parameters:
state The new state.
currentTime The time the state is set in seconds.

void OgreHaptics::ForceEffect::_resetAlgorithms ( void   ) 

Resets all registered algorithms (internal use only).

const ForceOutput& OgreHaptics::ForceEffect::_calculateForces ( const Vector3 &  position,
const Quaternion &  orientation,
const Vector3 &  linearVelocity,
const Vector3 &  angularVelocity,
double  timeElapsed 
)

Calculates the forces the effect will apply to the device the effect has been started for (internal use only).

Remarks:
Returns the full forces to be added to the output of the device the ForceEffect was started for.
See also:
ForceEffectAlgorithm::calculateForces

Real OgreHaptics::ForceEffect::_getLerpFraction ( double  currentTime,
bool  fadingIn 
)

Returns the linear interpolation fraction for fading the force effect (internal use only).

void OgreHaptics::ForceEffect::updateRemainingTime ( double  timeElapsed  )  [protected]

Updates the remaining time the force effect will actively render output.

Parameters:
timeElapsed The time elapsed since the last call in milliseconds.

Friends And Related Function Documentation

friend class ForceEffectManager [friend]

Definition at line 103 of file OgreHapticsForceEffect.h.

Member Data Documentation

CmdSustainMode OgreHaptics::ForceEffect::msSustainModeCmd [static, protected]

Definition at line 485 of file OgreHapticsForceEffect.h.

CmdSustainDuration OgreHaptics::ForceEffect::msSustainDurationCmd [static, protected]

Definition at line 486 of file OgreHapticsForceEffect.h.

CmdFadeInDuration OgreHaptics::ForceEffect::msFadeInDurationCmd [static, protected]

Definition at line 487 of file OgreHapticsForceEffect.h.

CmdFadeOutDuration OgreHaptics::ForceEffect::msFadeOutDurationCmd [static, protected]

Definition at line 488 of file OgreHapticsForceEffect.h.

Device* OgreHaptics::ForceEffect::mDevice [protected]

Pointer to the device for which the force effect was started.

Definition at line 491 of file OgreHapticsForceEffect.h.

Listener* OgreHaptics::ForceEffect::mListener [protected]

Pointer to the listener of events.

Definition at line 493 of file OgreHapticsForceEffect.h.

bool OgreHaptics::ForceEffect::mhtIsMaxLerpFractionSet [protected]

Has the maximum linear interpolation fraction been set?

Definition at line 495 of file OgreHapticsForceEffect.h.

long OgreHaptics::ForceEffect::mhtCurrentStateDuration [protected]

The duration of the current state, in milliseconds.

Definition at line 497 of file OgreHapticsForceEffect.h.

double OgreHaptics::ForceEffect::mhtCurrentStateStartTime [protected]

The time at which the current state was started.

Definition at line 499 of file OgreHapticsForceEffect.h.

Real OgreHaptics::ForceEffect::mhtMaxLerpFraction [protected]

The maximum linear interpolation fraction used for fading.

If the fading in process was not completed, this is used to cap the fading out.

Definition at line 503 of file OgreHapticsForceEffect.h.

ForceEffectSustainMode OgreHaptics::ForceEffect::mSustainMode [protected]

The mode the force effect will remain in in the sustain state.

Definition at line 505 of file OgreHapticsForceEffect.h.

String OgreHaptics::ForceEffect::mName [protected]

Name of the force effect.

Definition at line 507 of file OgreHapticsForceEffect.h.

String OgreHaptics::ForceEffect::mOrigin [protected]

Optional origin of this force effect (e.g. script name).

Definition at line 509 of file OgreHapticsForceEffect.h.

AtomicScalar<ForceEffectState> OgreHaptics::ForceEffect::mState [protected]

Is the force effect being used for rendering?

Definition at line 511 of file OgreHapticsForceEffect.h.

AtomicScalar<long> OgreHaptics::ForceEffect::mSustainDuration [protected]

The time of the sustaining state of the effect, in milliseconds.

Definition at line 513 of file OgreHapticsForceEffect.h.

AtomicScalar<long> OgreHaptics::ForceEffect::mFadeInDuration [protected]

The time to fade the effect in after it has been started, in milliseconds.

Definition at line 516 of file OgreHapticsForceEffect.h.

AtomicScalar<long> OgreHaptics::ForceEffect::mFadeOutDuration [protected]

The time to fade the effect out after it has been stopped, in milliseconds.

Definition at line 519 of file OgreHapticsForceEffect.h.

AtomicScalar<int> OgreHaptics::ForceEffect::mDurationChanged [protected]

Has the any duration been changed?

Definition at line 521 of file OgreHapticsForceEffect.h.

AtomicScalar<long> OgreHaptics::ForceEffect::mCurrentStateRemainingTime [protected]

The time in milliseconds the effect remains in in its current state.

Definition at line 523 of file OgreHapticsForceEffect.h.

AtomicScalar<long> OgreHaptics::ForceEffect::mTotalRemainingTime [protected]

The time in milliseconds the effect remains active.

Definition at line 525 of file OgreHapticsForceEffect.h.

ForceOutput OgreHaptics::ForceEffect::mOutput [protected]

The force output by the force effect.

Definition at line 527 of file OgreHapticsForceEffect.h.

ForceEffectAlgorithmList OgreHaptics::ForceEffect::mAlgorithms [protected]

A list of all algorithms used.

Definition at line 529 of file OgreHapticsForceEffect.h.

AlgorithmsParameterMap OgreHaptics::ForceEffect::mAlgorithmsParameterMap [protected]

Used to store name/value pairs to update algoritm parameters.

Definition at line 532 of file OgreHapticsForceEffect.h.

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

Last modified Tue Jan 6 22:31:26 2009