SurgSim::Devices::PhantomScaffold Class Reference

A class that manages Sensable PHANTOM devices. More...

`#include <SurgSim/Devices/Phantom/PhantomScaffold.h>`

## Classes

class | Callback
struct | DeviceData
class | Handle
struct | StateData

## Public Member Functions

| PhantomScaffold ()
| Constructor. More...
| ~PhantomScaffold ()
| Destructor. More...

## Static Public Member Functions

static std::shared_ptr< PhantomScaffold > | getOrCreateSharedInstance ()
| Gets or creates the scaffold shared by all PhantomDevice instances. More...

## Private Member Functions

bool | registerDevice (PhantomDevice *device)
| Registers the specified device object. More...
bool | unregisterDevice (const PhantomDevice *device)
| Unregisters the specified device object. More...
bool | initializeDeviceState (DeviceData *info)
| Initializes a single device, creating the necessary HDAPI resources. More...
bool | finalizeDeviceState (DeviceData *info)
| Finalizes a single device, destroying the necessary HDAPI resources. More...
bool | updateDevice (DeviceData *info)
| Updates the device information for a single device. More...
void | calculateForceAndTorque (DeviceData *info)
| Calculates forces and torques and sends them to the device library. More...
void | setInputData (DeviceData *info)
| Sets the input DataGroup, which will be pushed to the InputComponent. More...
bool | runHapticFrame ()
| Executes the operations for a single haptic frame. More...
bool | createHapticLoop ()
| Creates the haptic loop callback. More...
bool | destroyHapticLoop ()
| Destroys the haptic loop callback. More...
bool | startScheduler ()
| Starts the OpenHaptics scheduler. More...
bool | stopScheduler ()
| Stops the OpenHaptics scheduler. More...

## Static Private Member Functions

static SurgSim::DataStructures::DataGroup | buildDeviceInputData ()
| Builds the data layout for the application input (i.e. device output). More...

## Private Attributes

std::shared_ptr< SurgSim::Framework::Logger > | m_logger
| Logger used by the scaffold and all devices. More...
std::unique_ptr< StateData > | m_state
| Internal scaffold state. More...

## Friends

class | PhantomDevice

## Detailed Description

A class that manages Sensable PHANTOM devices.

This should support any PHANTOM device that can communicate using OpenHaptics 3.0 toolkit, such as PHANTOM Omni, PHANTOM Desktop, and the PHANTOM Premium series devices. The implementation is currently limited to 3DoF haptic output (forces only, no torques).

See also
  SurgSim::Devices::PhantomDevice

## Constructor & Destructor Documentation

## PhantomScaffold()

SurgSim::Devices::PhantomScaffold::PhantomScaffold | ( |  | ) |

Constructor.

## ~PhantomScaffold()

SurgSim::Devices::PhantomScaffold::~PhantomScaffold | ( |  | ) |

Destructor.

## Member Function Documentation

## buildDeviceInputData()

SurgSim::DataStructures::DataGroup SurgSim::Devices::PhantomScaffold::buildDeviceInputData | ( |  | ) |

static private

Builds the data layout for the application input (i.e. device output).

## calculateForceAndTorque()

void SurgSim::Devices::PhantomScaffold::calculateForceAndTorque | ( | PhantomScaffold::DeviceData * | info | ) |

private

Calculates forces and torques and sends them to the device library.

The force to output is composed of a vector named "force" in the output data, plus contributions from two optional Jacobians. If the matrix "springJacobian" is provided in the output data, a spring force & torque are generated from its product with the difference between the current pose and the pose in the output data named "inputPose". A damping force & torque are generated similarly. The intention is for a Behavior to calculate a nominal force & torque as well as the desired linearized changes to the force & torque based on changes to the input's pose & velocities. Then the linearized deltas to the output force & torque can be calculated at the haptic update rates, thereby smoothing the output response to motion.

Parameters

  info | The device data.

## createHapticLoop()

bool SurgSim::Devices::PhantomScaffold::createHapticLoop | ( |  | ) |

private

Creates the haptic loop callback.

Returns
  true on success.

## destroyHapticLoop()

bool SurgSim::Devices::PhantomScaffold::destroyHapticLoop | ( |  | ) |

private

Destroys the haptic loop callback.

Should be called while NOT holding the internal device list mutex, to prevent deadlock.

Returns
  true on success.

## finalizeDeviceState()

bool SurgSim::Devices::PhantomScaffold::finalizeDeviceState | ( | DeviceData * | info | ) |

private

Finalizes a single device, destroying the necessary HDAPI resources.

Parameters

  [in,out] | info | The device data.

Returns
  true on success.

## getOrCreateSharedInstance()

std::shared_ptr< PhantomScaffold > SurgSim::Devices::PhantomScaffold::getOrCreateSharedInstance | ( |  | ) |

static

Gets or creates the scaffold shared by all PhantomDevice instances.

The scaffold is managed using a SharedInstance object, so it will be destroyed when all devices are released.

Returns
  the scaffold object.

## initializeDeviceState()

bool SurgSim::Devices::PhantomScaffold::initializeDeviceState | ( | DeviceData * | info | ) |

private

Initializes a single device, creating the necessary HDAPI resources.

Parameters

  [in,out] | info | The device data.

Returns
  true on success.

## registerDevice()

bool SurgSim::Devices::PhantomScaffold::registerDevice | ( | PhantomDevice * | device | ) |

private

Registers the specified device object.

If successful, the device object will become connected to an unused controller.

Parameters

  device | The device object to be used, which should have a unique name.

Returns
  True if the initialization succeeds, false if it fails.

## runHapticFrame()

bool SurgSim::Devices::PhantomScaffold::runHapticFrame | ( |  | ) |

private

Executes the operations for a single haptic frame.

Should only be called from the context of an OpenHaptics callback.

Returns
  true on success.

## setInputData()

void SurgSim::Devices::PhantomScaffold::setInputData | ( | DeviceData * | info | ) |

private

Sets the input DataGroup, which will be pushed to the InputComponent.

Parameters

  info | The device data

## startScheduler()

bool SurgSim::Devices::PhantomScaffold::startScheduler | ( |  | ) |

private

Starts the OpenHaptics scheduler.

Returns
  true on success.

## stopScheduler()

bool SurgSim::Devices::PhantomScaffold::stopScheduler | ( |  | ) |

private

Stops the OpenHaptics scheduler.

Returns
  true on success.

## unregisterDevice()

bool SurgSim::Devices::PhantomScaffold::unregisterDevice | ( | const PhantomDevice * | device | ) |

private

Unregisters the specified device object.

The corresponding controller will become unused, and can be re-registered later.

Parameters

  device | The device object.

Returns
  true on success, false on failure.

## updateDevice()

bool SurgSim::Devices::PhantomScaffold::updateDevice | ( | PhantomScaffold::DeviceData * | info | ) |

private

Updates the device information for a single device.

Parameters

  info | The device data.

Returns
  true on success.

## Friends And Related Function Documentation

## PhantomDevice

friend class PhantomDevice

friend

## Member Data Documentation

## m_logger

std::shared_ptr<SurgSim::Framework::Logger> SurgSim::Devices::PhantomScaffold::m_logger

private

Logger used by the scaffold and all devices.

## m_state

std::unique_ptr<StateData> SurgSim::Devices::PhantomScaffold::m_state

private

Internal scaffold state.

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

- SurgSim/Devices/Phantom/PhantomScaffold.h
- SurgSim/Devices/Phantom/PhantomScaffold.cpp