OpenHaptics Unity Plugin User Guide
11
When to Use One Over the Other
HDAPI requires the developer to manage direct force rendering for the haptic device whereas HLAPI handles the computations
of haptic rendering based on geometric primitives, transforms, and material properties. Direct force rendering with HDAPI
requires ecient force rendering / collision detection algorithms and data structures. This is due to the high frequency of force
refreshes required for stable closed-loop control of the haptic device. HLAPI differs in this regard, since it shields the developer
from having to implement ecient force rendering algorithms and managing the synchronization of servo loop thread-safe
data structures and state.
HLAPI allows the developer to command the haptic rendering pipeline from the graphics rendering loop, which makes it
signicantly more approachable for a developer to introduce haptic rendering to an existing graphics loop driven application.
HLAPI enables an event driven programming model, which eases the implementation of complicated haptic interactions
involving events like touching geometry, button clicks, and motion. HDAPI does not offer events as part of the API. However,
the OpenHaptics toolkit does offer a HapticDevice C++ utility class that offers a basic event callback infrastructure for use with
HDAPI. HLAPI only deals with the device at the Cartesian space level whereas HDAPI offers access to lower-level control spaces,
like the raw encoder and motor joint torque values.
What Parts Can be Used Together
HLAPI is built on top of HDAPI, therefore developers can leverage pieces of functionality from HDAPI to augment an HLAPI
program. HDAPI must be used to initialize and congure the haptic device handle (HHD). The HHD from HDAPI is used by the
HL haptic rendering context (HHLRC) to interface with the haptic device. This allows the developer to control behaviors for the
haptic device that will be realized by the haptic rendering library. For instance, hdEnable()/hdDisable() can be used to turn on
or off capabilities of HDAPI, like force output, force ramping, and max force clamping.
HDAPI can be used to query properties and capabilities of the device, for instance: input and output DOF, the nominal max
force, workspace dimensions.
HDAPI can be used to modify the rate of the servo loop. Increasing the servo loop rate has the benets of improved stability
and responsiveness of the device as well as increased nominal max stiffness of forces. However, this comes at the expense of
higher CPU utilization (i.e. 2000 Hz means an update every 0.5 ms instead of 1 ms for the default 1000 Hz rate). Conversely, the
servo loop rate can also be lowered to decrease the amount of CPU used for force rendering (i.e. 500 Hz means an update every
2 ms instead of 1 ms for the default 1000 Hz rate). This has the benet of freeing up valuable CPU cycles for other threads, but
at the expense of reduced stability of the device and lower nominal max stiffness.
HLAPI allows for custom effects. A custom effect is principally responsible for adding to or modifying a force to be sent to
the haptic device. Since forces are computed in the servo loop thread, the user can choose to use HDAPI routines in tandem
with the custom effect callback to gain access to additional information about the device, for instance, device velocity and
instantaneous rate. In addition, the HDAPI scheduler can be used as a synchronization mechanism for custom effects so that
the main application thread can safely modify state or data used by the effect.
Since the last hdEndFrame() will actually commit the force to the haptic device, please note that it is not necessary to call
hdStartScheduler() or hdStopScheduler() when using HDAPI in tandem with HLAPI. HLAPI will manage starting and stopping
the scheduler when the context is created and deleted as long as a valid handle to a haptic device is provided to the context.
See “Haptic Frames” on page 88 for a more complete description.
Servo Loop
The servo loop refers to the tight control loop used to calculate forces to send to the haptic device. In order to render stable
haptic feedback, this loop must be executed at a consistent 1khz rate or better. In order to maintain such a high update rate,
the servo loop is generally executed in a separate, high-priority thread. This thread is referred to as the servo loop thread.