Open Haptics Ref Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 75

Download
Open PDF In Browser	View PDF

TABLE OF CONTENTS
COPYRIGHT

5

WARRANTY

5

LIMITATION OF LIABILITY

5

11 INTRODUCTION

6

RESOURCES FOR LEARNING THE OPENHAPTICS TOOLKIT

6

THE DEVELOPER SUPPORT CENTER

6

OVERVIEW

6

22 DEVICE ROUTINES

7

HDBEGINFRAME

7

HDDISABLE

7

HDDISABLEDEVICE

7

HDENABLE

8

HDENDFRAME

8

HDGET (PARAMETER VALUES)

8

HDGETCURRENTDEVICE

9

HDGETERROR

9

HDGETERRORSTRING

9

HDGETSTRING

10

HDINITDEVICE

10

HDISENABLED

10

HDMAKECURRENTDEVICE

11

HDSET (PARAMETER VALUES)

11

HD_DEVICE_ERROR

12

33 CALIBRATION ROUTINES

14

HDCHECKCALIBRATION

14

HDUPDATECALIBRATION

15

44 SCHEDULER ROUTINES

16

HDGETSCHEDULERTIMESTAMP

16

HDSCHEDULEASYNCHRONOUS

16

HDSCHEDULESYNCHRONOUS

17

HDSETSCHEDULERRATE

18

HDSTARTSCHEDULER

18

HDSTOPSCHEDULER

18

HDUNSCHEDULE

19

HDWAITFORCOMPLETION

19

55 HDAPI DEPLOYMENT

20

HDDEPLOYMENTLICENSE

20

66 HDAPI TYPES

21

HDSCHEDULERCALLBACK TYPE

21

HDSCHEDULERHANDLE TYPE

21

7
3D Systems, Inc.

1

7C ONTEXT/FRAME MANAGEMENT

22

HLBEGINFRAME

22

HLCONTEXTDEVICE

22

HLCREATECONTEXT

23

HLDELETECONTEXT

23

HLENDFRAME

24

HLGETCURRENTCONTEXT

24

HLGETCURRENTDEVICE

24

HLMAKECURRENT

25

88 STATE MAINTENANCE AND ACCESSORS

26

HLENABLE, HLDISABLE

26

HLGETBOOLEANV, HLGETDOUBLEV, HLGETINTEGERV

26

HLGETERROR

27

HLGETSTRING

27

HLHINTI, HLHINTB

28

HLISENABLED

28

HLMAKECURRENT

29

99 CACHED STATE ACCESSORS

30

HLCACHEGETBOOLEANV, HLCACHEGETDOUBLEV

30

1 SHAPES
10

31

HLBEGINSHAPE

31

HLDELETESHAPE

31

HLENDSHAPE

32

HLGENSHAPES

32

HLLOCALFEATURE

33

HLISSHAPE

34

HLGETSHAPEBOOLEANV, HLGETSHAPEDOUBLEV

34

11
1 MATERIAL AND SURFACE PROPERTIES

36

HLGETMATERIALFV

36

HLMATERIALF

36

HLTOUCHABLEFACE

37

HLTOUCHMODEL

37

HLTOUCHMODELF

38

1 FORCE EFFECTS
12

39

HLDELETEEFFECTS

39

HLEFFECTD, HLEFFECTI, HLEFFECTDV, HLEFFECTIV

39

HLGENEFFECTS

40

HLGETEFFECTDV, HLGETEFFECTIV, HLGETEFFECTBV

40

HLISEFFECT

41

HLSTARTEFFECT

41

HLSTOPEFFECT

41

HLTRIGGEREFFECT

42

HLUPDATEEFFECT

42

1
3D Systems, Inc.

2

13

PROXY

43

HLDELETEEFFECTS

43

14
1 TRANSFORMS

44

HLLOADIDENTITY

44

HLLOADMATRIXD, HLLOADMATRIXF

44

HLMULTMATRIXD, HLMULTMATRIXF

45

HLMATRIXMODE

45

HLORTHO

46

HLPUSHATTRIB, HLPOPATTRIB

47

HLPUSHMATRIX, HLPOPMATRIX

47

HLROTATEF, HLROTATED

48

HLSCALEF, HLSCALED

48

HLTRANSLATEF, HLTRANSLATED

49

HLWORKSPACE

49

151 CALLBACKS

51

HLCALLBACK

51

16
1 EVENTS

52

HLADDEVENTCALLBACK

52

HLCHECKEVENTS

52

HLEVENTD

54

HLREMOVEEVENTCALLBACK

54

HLISEFFECT

55

HLSTARTEFFECT

55

HLSTOPEFFECT

55

171 CALIBRATION

56

HLUPDATECALIBRATION

56

1 HLAPI DEPLOYMENT

57

HLDEPLOYMENTLICENSE

57

18
1 HAPTIC DEVICE API PARAMETERS

58

GET PARAMETERS

58

SET PARAMETERS

61

CAPABILITY PARAMETERS

63

CODES

63

19
2 HAPTIC LIBRARY API PARAMETERS

65

STATE MAINTENANCE PARAMETERS

65

SHAPE PARAMETERS

68

TABLE B-7: HLGETSHAPEBOOLEANV, HLGETSHAPEDOUBLEV

68

CAPABILITY PARAMETERS

69

MATERIAL AND SURFACE PARAMETERS

70

FORCE EFFECT PARAMETERS

71

CALLBACK PARAMETERS

73

EVENT PARAMETERS

73

PROXY PARAMETERS

74

TRANSFORM PARAMETERS

74

3D Systems, Inc.

3

COPYRIGHT
©2015. 3D Systems, Inc. All rights reserved. The content of this manual is furnished for informational use only, is subject to change
without notice, and should not be construed as a commitment by 3D Systems, Inc. This document is copyrighted and contains
proprietary information that is the property of 3D Systems, Inc. Touch, Geomagic Touch, Geomagic Touch X, Geomagic OpenHaptics,
Geomagic, Phantom, Phantom Desktop, Phantom Omni, Sensable, 3D Systems, and the 3D Systems logo are registered trademarks,
and Touch is a trademark, of 3D Systems, Inc. Use of the Cubify.com website constitutes acceptance of its Terms of Service and
Privacy Policy. Any names, places, and/or events in this publication are not intended to correspond or relate in any way to individuals,
groups or associations. Any similarity or likeness of the names, places, and/or events in this publication to those of any individual, living
or dead, place, event, or that of any group or association is purely coincidental and unintentional.

WARRANTY
No warranties of any kind are created or extended by this publication. 3D Systems warrants that the Touch haptic device will be free
from defects in materials and workmanship, during the applicable warranty period, when used under the normal conditions described
in the documentation provided to you, including the respective User Guide. 3D Systems will promptly repair or replace the Touch, if
required, to make it free of defects during the warranty period. This warranty excludes repairs required during the warranty period
because of abnormal use or conditions (such as riots, floods, misuse, neglect or improper service by anyone except 3D Systems or its
authorized service provider). For consumers who are covered by consumer protection laws or regulations in their country of purchase
or, if different, their country of residence, the benefits conferred by our standard warranty are in addition to, and operate concurrently
with, all rights and remedies conveyed by such consumer protection laws -and regulations, including but not limited to these additional
rights.

LIMITATION OF LIABILITY
3D SYSTEMS WILL NOT BE RESPONSIBLE FOR CONSEQUENTIAL, EXEMPLARY OR INCIDENTAL DAMAGES (SUCH AS
LOSS OF PROFIT OR EMPLOYEE’S TIME) REGARDLESS OF THE REASON. IN NO EVENT SHALL THE LIABILITY AND/OR
OBLIGATIONS OF 3D SYSTEMS ARISING OUT OF THE PURCHASE, LEASE, LICENSE AND/OR USE OF THE EQUIPMENT BY
YOU OR OTHERS EXCEED THE PURCHASE PRICE OF THE TOUCH 3D DEVICE.

3D Systems, Inc.

4

1 1 INTRODUCTION
Thank you for downloading the OpenHaptics Toolkit version 3.4.0!
Should you encounter any difficulties while setting up or learning the application, we provide a variety of resources to help you learn the
product. These are described below in “Resources for Learning the OpenHaptics Toolkit”.

Resources for Learning the OpenHaptics Toolkit
The following documentation and other materials are provided to assist you in learning about OpenHaptics:

OpenHaptics Installation Guide This guide walks you through installing the toolkit and deploying your haptically enabled

application. Detailed instructions for installing the Geomagic® Touch™ haptic device can be found in the Geomagic Touch User Guide
that came with your device. This can also be found on the OpenHaptics CD.

OpenHaptics Programmer’s Guide This guide explains the OpenHaptics toolkit (which includes the QuickHaptics™ micro

API), and introduces you to the architecture of the toolkit, how it works, and what you can do with it. The guide will also introduce you to
the fundamental components of creating haptic environments.

OpenHaptics API Reference This manual is meant to be used as a companion to the OpenHaptics Toolkit Programmer’s Guide.
It contains reference pages to all the QuickHaptics micro API and OpenHaptics toolkit HDAPI and HLAPI functions and types as well as
appendices with tables that describe all the parameters.

Source Code Examples & Guide Several examples with source code to illustrate commonly used functionality of the HDAPI
and HLAPI are installed with the toolkit. These include both console examples and graphics examples. A guide to these examples is
located in \doc.

Developer Support Center This is described in more detail below.

The Developer Support Center
A more recent version of this document may be available for download from the online Developer Support Center (DSC). To access the
DSC, go to http://dsc.sensable.com.
The DSC provides customers with 24 x 7 access to the most current information and forums for the OpenHaptics toolkit. Please note
that you will be asked to create a registration profile and have your customer information authenticated before you will have access to
the DSC.

OVerview
This manual is meant to be used as a companion to the OpenHaptics® Toolkit Programmer’s Guide. It contains reference pages to all
the OpenHaptics® toolkit HDAPI and HLAPI functions and types as well as appendices with tables that describe all the parameters.
Functions are listed alphabetically by section.
A more recent version of this document may be available for download from the online Developer Support Center (DSC). To access the
DSC, go to http://dsc.sensable.com/. The DSC provides 24/7 access to the most current information and forums for the OpenHaptics
toolkit. Please note that you will need to register for a user name and password to access the DSC.
For the QuickHaptics™ micro API, a detailed description of classes and functions with links to code examples is provided in online
Doxygen format in the DSC and not in this guide.

3D Systems, Inc.

5

2 2 DEVICE ROUTINES
The following are routines for managing the device and forces. This includes all functionality for initializing devices, querying and setting
device state, and turning capabilities on or off.

hdBeginFrame
Description:
Syntax:
Returns:
Usage:
Example:
Errors:
See also:

Begins an haptics frame, which is a block of code within which the device state is guaranteed
to be consistent. Updates state from the device for current/last information. All state-related
information, such as setting state, should be done within a haptics frame.
void hdBeginFrame(HHD hHD)
Argument: hHD - The device handle of an initialized device
None
Typically the first haptics call per device per scheduler tick. For example, if two haptics devices
are being managed, hdBeginFrame() should be called for each of them before device-specific
calls are made. Only one frame is allowed per device per scheduler tick unless HD_ONE_
FRAME_LIMIT is disabled. However, frames for the same device can be nested within a
scheduler tick. This function automatically makes the supplied device current.
HHD hHD = hdGetCurrentDevice;
hdBeginFrame(hHD;
HD_ILLEGAL_BEGIN if a frame was already completed for the current device within the current
scheduler tick.
hdMakeCurrentDevice, hdDisable, hdIsEnabled

hdDisable
Description:

Disables a capability.
void hdDisable(HDenum cap)

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

Argument: cap - The capability to disable. For a list of the capabilities see “Table A-10: hdEnable,
hdDisable Parameters” on page 61.
None
Capabilities are typically related to safety mechanisms. Use extreme caution when disabling
safety features.
hdDisable(HD_MAX_FORCE_CLAMPING);
HD_INVALID_ENUM if cap does not support hdEnable() or hdDisable().
hdEnable, hdIsEnabled

hdDisableDevice
Description:

Disables a device. The handle should not be used afterward.
void hdDisableDevice(HHD hHD)

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

3D Systems, Inc.

Argument: hHD - The device handle of an initialized device.
None
Call during cleanup when done using a device. Typically the last call after stopping the scheduler
and unscheduling all scheduled callbacks.
hdStopScheduler();
hdUnschedule(scheduleCallbackHandle);
hdDisableDevice(hdGetCurrentDevice());
None
hdInitDevice, hdStopScheduler
6

hdEnable
Description:

Enables a capability.
void hdEnable(HDenum cap)

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

Argument: cap - The capability to enable. For a list of the capabilities see “Table A-10: hdEnable,
hdDisable Parameters” on page 61.
None
Capabilities are typically related to safety mechanisms. Most are turned on by default.
hdEnable(HD_FORCE_OUTPUT);
HD_INVALID_ENUM if cap does not support enable/disable.
hdDisable, hdIsEnabled

hdEndFrame
Description:

Ends a haptics frame. Causes forces and other states to be written to the device. An
hdBeginFrame() and hdEndFrame() should always be paired within the same scheduler tick.
void hdEndFrame(HHD hHD)

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

Argument: hHD - The device handle of an initialized device.
None
Typically the last haptics call per device, per scheduler tick.
hdEndFrame(hdGetCurrentDevice());
HD_ILLEGAL_END if this call is not paired correctly with an hdBeginFrame() of the same device
handle.
hdBeginFrame, hdMakeCurrentDevice

hdGet (Parameter Values)
Description:

Syntax:

Returns:
Usage:

Example:
Errors:
See also:

3D Systems, Inc.

Obtains information about the device. There are five query functions for obtaining information
about the device associated with the parameter name used.
void
void
void
void
void

hdGetBooleanv(HDenum pname, HDboolean *params)
hdGetIntegerv(HDenum pname, HDint *params)
hdGetFloatv(HDenum pname, HDfloat *params)
hdGetDoublev(HDenum pname, HDdouble *params)
hdGetLongv(HDenum pname, HDlong *params)

Argument: pname - Parameter name to use.
Argument: params - Array where the results will be returned. For a list of parameters see “Table
A-1: hdGet Parameters” on page 56.
None
Primary function for getting device information. Depending on the parameter, one should use
the appropriate params type, and therefore the appropriate function signature. The caller of
the function has the responsibility for allocating memory. These functions should only be called
within a haptics frame.
HDdouble position[3];
hdGetDoublev(HD_CURRENT_POSITION,position);
HDint buttons;
hdGetIntegerv(HD_CURRENT_BUTTONS,&buttons);
HD_INVALID_INPUT_TYPE if pname does not support the input type.
HD_INVALID_ENUM if pname does not support hdGet().
hdSet (Parameter Values)

7

hdGetCurrentDevice
Description:

Gets the handle of the current device.

Syntax:
Returns:

HHD hdGetCurrentDevice()

Usage:
Example:
Errors:
See also:

The handle of the current device.
Primarily used in multi-device applications to keep track of which device is current, or for calls
that require a device handle.
HHD hHD = hdGetCurrentDevice();
HD_INVALID_HANDLE if no device is current, for example, if no device has been initiated yet.
hdMakeCurrentDevice

hdGetError
Description:
Syntax:
Returns:
Usage:

Returns errors in order from most recent to least. Each call retrieves and removes one error from
the error stack. If no error exists, this function returns a HDErrorInfo with HD_SUCCESS as its
code. HDErrorInfo contains the error code from the defines file, the handle of the device that was
active when the error occurred, and the device’s original internal error code. The internal code
can be used for obtaining additional support from the device vendor.
HDErrorInfo hdGetError()
HDErrorInfo. This data structure is a typedef in hdDefines.h. It exposes information on the handle
of the device, an errorCode, and an internal error code. See “Table A-15: Device Error Codes” on
page 62 for a list of errorCodes and descriptions.
Intersperse in code to occasionally check for errors.
HHDErrorInfo error;
error = hdGetError();

Example:

if (HD_DEVICE_ERROR(error))
// do error handling

Errors:
See also:

hdGetErrorString(error.errorCode);
None
hdGetErrorString, HDErrorInfo Type

hdGetErrorString
Description:

Returns information about an error code.
HDstring hdGetErrorString(HDerror errorCode)

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

3D Systems, Inc.

Argument: errorCode - An error code from hdDefines.
A readable string representing the explanation of the error code.
Obtains useful information about error codes. The return string is static and should not be
deallocated using Free or Delete or any similar function.
hdGetErrorString(HD_FRAME_ERROR);
None
hdGetError, HD_DEVICE_ERROR

8

hdGetString
Description:

Gets a string value for the associated parameter name.
HDstring hdGetString(HDenum pname)

Syntax:
Returns:
Usage:
Example:
Errors:

Argument: pname - Parameter name to use. For a list what types and how many values are used
by each parameter name, see “Table A-3: Get Identification Parameters” on page 57. Note
that not all parameter names support string values.
Requested string associated with the parameter name.
Gets readable string information about device properties, such as the device model type. The
return string is static and should not be deallocated using Free or Delete or any similar function.
HDstring *deviceType = hdGetString(HD_DEVICE_MODEL_TYPE);
HD_INVALID_INPUT_TYPE if pname does not support string as an input type.
HD_INVALID_ENUM if pname does not support hdGetString().

hdInitDevice
Description:

Initializes the device. If successful, this returns a handle to the device and sets the device as the
current device.
HHD hdInitDevice(HDstring pConfigName)

Syntax:

Argument: pConfigName - The name of the device, such as the name found under the control
panel “Geomagic Touch Setup”. If HD_DEFAULT_DEVICE is passed in as pConfigName,
hdInitiDevice() will initialize the first device that it finds.

Returns:
Usage:
Example:

A handle to the initialized device.

Errors:
See also:

Generally the first haptics command that should be issued.
HHD hDevice = hdInitDevice(“Default Device”);
HD_DEVICE_ALREADY_INITIATED if the device was already initiated.
HD_DEVICE_FAULT if the device could not be initiated, for example, if pConfigName is invalid.
hdDisableDevice, hdMakeCurrentDevice, hdStartScheduler

hdIsEnabled
Description:

Checks if a capability is enabled. Capabilities are in hdDefines.h file under the enable/disable
category.
HDboolean hdIsEnabled(HDenum cap)

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

3D Systems, Inc.

Argument: cap - Capability to check. For a list of the capabilities see “Table A-10: hdEnable,
hdDisable Parameters” on page 61.
Whether the capability is enabled.
Capabilities are typically related to safety mechanisms. Most are turned on by default.
HDboolean bForcesOn = hdIsEnabled(HD_FORCE_OUTPUT);
HD_INVALID_ENUM if cap does not support enable/disable.
hdEnable, hdDisable

9

hdMakeCurrentDevice
Description:
Syntax:
Returns:
Usage:

Example:

Errors:
See also:

Makes the device current. All subsequent device-specific actions such as getting and setting
state or querying device information will be performed on this device until another is made
current.
void hdMakeCurrentDevice(HHD hHD)
Argument: hHD - The device handle of an initialized device.
None
Primarily used to switch between devices in multi-device applications.
hdBeginFrame(hHD1);
hdGetDoublev(HD_CURRRENT_POSITION, p1);
hdBeginFrame(hHD2);
hdGetDoublev(HD_CURRENT_POSITION, p2);
calculateforce(p1,p2,outforce1,outforce2);
hdMakeCurrentDevice(hHD1);
hdSetDoublev(HD_CURRENT_FORCE,outforce1);
hdEndFrame(hHD1);
hdMakeCurrentDevice(hHD2);
hdSetDoublev(HD_CURRENT_FORCE,outforce2);
hdEndFrame(hHD2);
HD_INVALID_HANDLE if hHD does not refer to an initiated device.
hdInitDevice

hdSet (Parameter Values)
Description:

Syntax:

Sets information associated with the parameter name.
void
void
void
void
void

hdSetBooleanv(HDenum pname, const HDboolean *params)
hdSetIntegerv(HDenum pname, const HDint *params)
hdSetFloatv(HDenum pname, const HDfloat *params)
hdSetDoublev(HDenum pname, const HDdouble *params)
hdSetLongv (HDenum pname,const HDlong *params)

Argument: pname - Parameter name to set.
Argument: params - Array of values to set. For a list of parameters see Tables in “Set
Parameters” on page 59.

Returns:
Usage:

None
Primary function for sending information to the device or changing device properties. Depending
on the parameter, one should use the appropriate params type, and therefore the appropriate
function signature. The caller of the function has the responsibility for allocating memory. These
functions should only be called within a haptics frame.
HDfloat forces[3] = { 2,.5, 0};
hdSetFloatv(HD_CURRENT_FORCE,forces);

Example:

Or,
hduVector3Dd forces(0.2,0.5,0);

Errors:
See also:

3D Systems, Inc.

hdSetFloatv(HD_CURRENT_FORCE,forces);
HD_INVALID_INPUT_TYPE if pname does not support the input type.
HD_INVALID_ENUM if pname does not support hdSet.
hdGet (Parameter Values).

10

HD_DEVICE_ERROR
Description:

A macro useful for checking if an error has occurred.
#define HD_DEVICE_ERROR(X)(((X).errorCode)!=HD_SUCCESS)
int HD_DEVICE_ERROR(x)

Syntax:
Returns:
Usage:

Argument: X - The error structure to check. Error structure is of type HDErrorInfo.
1 if error, 0 if no error
Typically, call this with hdGetError() to check if the error stack contains an error.
HDErrorInfo error;
if (HD_DEVICE_ERROR(error = hdGetError()))

Example:

{
hduPrintError(stderr, &error, “HDAPI device error encountered”);
return -1;

Errors:
See also:

3D Systems, Inc.

}
None
hdGetError, hdGetErrorString

11

3 3 CALIBRATION ROUTINES
This chapter covers the routines used for managing the calibration of the device. Calibration is necessary for accurate position mapping
and force/torque rendering of the haptic device; calibration synchronizes the software’s notion of the device position with the actual
mechanical position. For example, if the device is not calibrated, then the software may believe the device position is in the corner of
the workspace while the actual device arm is in the center of its workspace.
A typical application begins by asking the user to put the device in a neutral position or inkwell so that it can be calibrated. Some
devices automatically calibrate so that this step is unnecessary.
The calibration interface provides functions for querying the calibration style(s) supported by the device, checking the calibration status,
and updating the calibration.

Querying Calibration Styles
Supported calibration styles differ depending on device. The list of calibration styles is:
HD_CALIBRATION_ENCODER_RESET: The device position must be read while the device is in a specified neutral position. For
devices that use encoder reset calibration style, typically the user is asked to place the device in the neutral position at the start of the
application so that position can be sampled. Touch X haptic device models use encoder reset.
HD_CALIBRATION_INKWELL: The device must be placed into the device’s inkwell to be calibrated. The Geomagic Touch haptic device
supports inkwell calibration.
HD_CALIBRATION_AUTO: The device automatically calibrates by collecting positional data while the user moves the device arm
around. This data persists between sessions so the device does not need to be repeatedly calibrated. The Geomagic Touch X haptic
device supports auto calibration.
The calibration styles that a particular device supports can be obtained as follows:
HDint supportedStyles;
hdGetIntegerv(HD_CALIBRATION_STYLE,&supportedStyles);
It is possible for a device to support more than one calibration style. The supportedStyles value should be masked (&) with HD_
CALIBRATION_ENCODER_RESET, HD_CALIBRATION_INKWELL, HD_CALIBRATION_AUTO to determine if each particular style is
supported.

hdCheckCalibration
Checks the calibration status.
If the return value is HD_CALIBRATION_OK, the device is already calibrated.

Description:

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

3D Systems, Inc.

If the return value is HD_CALIBRATION_NEEDS_UPDATE, call hdUpdateCalibration() to update
the calibration.
If the return value is HD_CALIBRATION_NEEDS_MANUAL_INPUT, the user needs to provide
additional input particular to the calibration style.
HDenum hdCheckCalibration()
Possible values are:
HD_CALIBRATION_OK
HD_CALIBRATION_NEEDS_UPDATE
HD_CALIBRATION_NEEDS_MANUAL_INPUT
For devices that support auto calibration, call intermittently so that the device continues to update
its calibration.
if(hdCheckCalibration()==HD_CALIBRATION_NEEDS_UPDATE)
{
hdUpdateCalibration(myStyle);
HD_DEVICE_FAULT if the calibration information could not obtained from the device.
hdUpdateCalibration

12

hdUpdateCalibration
Description:

Calibrates the device. The type of calibration supported can be queried through getting HD_
CALIBRATION_STYLE.
void hdUpdateCalibration(HDenum style)

Syntax:

Argument: style - The calibration style of the device. For a list of calibration styles see “Table A-3:
Get Identification Parameters” on page 57.

Returns:

None

Usage:
Example:
Errors:
See also:

3D Systems, Inc.

Calibrate the device when hdCheckCalibration() returns
HD_CALIBRATION_NEEDS_UPDATE.
HDint style;
hdGetIntegerv(HD_CALIBRATION_STYLE,&style); hdUpdateCalibration(style);
HD_DEVICE_FAULT if the calibration type could not be performed on the device.
hdCheckCalibration

13

4 4 SCHEDULER ROUTINES
The following are routines for managing the scheduler and scheduler routines. This includes starting and stopping the scheduler, adding
callbacks into the scheduler, and managing those callbacks.

hdGetSchedulerTimeStamp
Description:
Syntax:
Returns:
Usage:

Returns the elapsed time since the start of the servo loop tick. This is useful for measuring duty
cycle of the servo loop.
HDdouble hdGetSchedulerTimeStamp()
Number of seconds since the start of the servo loop tick.
Used to check how long operations have taken.
HDCallbackCode HDCALLBACK schedulerTimeCallback(void *pUserData)
{
HDdouble *schedulerTime = (HDdouble *)pUserData;
*schedulerTime = hdGetSchedulerTimeStamp();

Example:

return HD_CALLBACK_DONE;
}
HDdouble schedulerTime;
hdScheduleSynchronous(schedulerTimeCallback,&schedulerTime,
HD_MAX_SCHEDULER_PRIORITY);

Errors:

None

See also:

None

hdScheduleAsynchronous
Description:

Syntax:

Returns:
Usage:

3D Systems, Inc.

Schedules an operation to be executed by the scheduler in the servo loop, and does not wait for
its completion. Scheduler callbacks submitted from the servo loop thread are run immediately
regardless of priority.
HDSchedulerHandle
hdScheduleAsynchronous(HDSchedulerCallback pCallback,
void *pUserData,
HDushort nPriority)
Argument: pCallback - The function callback.
Argument: pUserData - The data to be used by the function.
Argument: nPriority - The priority of the operation. Callbacks are processed once per
scheduler tick, in order of decreasing priority.
Handle for the operation.
Typically used for scheduling callbacks that run every tick of the servo loop. For example,
one can run a dynamic simulation within an asynchronous callback and set forces within that
simulation.

14

HDCallbackCode HDCALLBACK mySchedulerCallback(void *pUserData)
{
HDint buttons;
hdGetIntegerv(HD_CURRENT_BUTTONS,&buttons);
if (buttons == 0)

Example:

return HD_CALLBACK_CONTINUE;
return HD_CALLBACK_DONE;
}
...
HDSchedulerHandle hHandle = hdScheduleAsynchronous(mySchedulerCallback,

Errors:
See also:

(void*)0, HD_DEFAULT_SCHEDULER_PRIORITY);
HD_SCHEDULER_FULL if the scheduler has reached its upper limit on the number of scheduler
operations that it can support at once.
HD_INVALID_PRIORITY if nPriority is out of range,
i.e. less than HD_MIN_SCHEDULER_PRIORITY or greater than
HD_MAX_SCHEDULER_PRIORITY.
HDSchedulerCallback Type, hdStartScheduler

hdScheduleSynchronous
Description:

Syntax:

Returns:
Usage:

Schedules an operation to be executed by the scheduler in the servo loop, and waits for its
completion. Scheduler callbacks submitted from the servo loop thread are run immediately
regardless of priority.
void hdScheduleSynchronous(HDSchedulerCallback pCallback,
void *pUserData,
HDushort nPriority)
Argument: pCallback - The function callback.
Argument: pUserData - The data to be used by the function.
Argument: nPriority - The priority of the operation. Callbacks are processed once per
scheduler tick, in order of decreasing priority.
None
Typically used as a synchronization mechanism between the servo loop thread and other threads
in the application. For example, if the main application thread needs to access the position or
button state, it can do so through a synchronous scheduler call. Can be used for synchronously
copying state from the servo loop or synchronously performing an operation in the servo loop.
HDCallbackCode HDCALLBACK buttonCallback(void *pUserData)
{
int *buttons = (int *)pUserData;
hdGetIntegerv(HD_CURRENT_BUTTONS,buttons);

Example:

return HD_CALLBACK_DONE;
}
int buttons;
HDSchedulerHandle hHandle =
hdScheduleSynchronous(buttonCallback, &buttons,

Errors:
See also:

3D Systems, Inc.

HD_DEFAULT_SCHEDULER_PRIORITY);
HD_SCHEDULER_FULL if the scheduler has reached its upper limit on the number of scheduler
operations that it can support at once.
HD_INVALID_PRIORITY if nPriority is out of range,
i.e. less than HD_MIN_SCHEDULER_PRIORITY or greater than
HD_MAX_SCHEDULER_PRIORITY.
HDSchedulerCallback Type, hdStartScheduler

15

hdSetSchedulerRate
Description:

Sets the number of times the scheduler ticks its callbacks per second.
void hdSetSchedulerRate(HDulong nRate)

Syntax:
Returns:

Usage:

Example:
Errors:
See also:

Argument: nrate - The requested rate for the scheduler to run in Hz.
None
Typically used to control the fidelity of force rendering. Most haptic applications run at 1000Hz.
PCI and EPP support 500, 1000, and 2000 Hz. Firewire supports 500, 1000, 1600 Hz, plus some
increments in between based on the following expression: floor(8000/N + 0.5).
As a word of caution, decreasing the rate can lead to instabilities and kicking. Increasing
the servo loop rate can yield stiffer surfaces and better haptic responsiveness, but leaves
less time for scheduler operations to complete. When setting the scheduler rate, check
hdGetSchedulerTimeStamp() and HD_INSTANTANEOUS_UPDATE_RATE to verify that the
servo loop is able to maintain the rate requested.
Some devices may support a variety of settings. Certain devices may need to be flashed with the
latest firmware to be able to use this feature. You can find current information from the Developer
Support Center, see”The Developer Support Center” on page 5 for information about the
DSC.
// try to set rate of 500 Hz
hdSetSchedulerRate(500);
HD_INVALID_VALUE if the nRate specified cannot be set.
hdGetSchedulerTimeStamp

hdStartScheduler
Description:

Starts the scheduler. The scheduler manages callbacks to be executed within the servo loop
thread.

Syntax:

void hdStartScheduler()

Returns:

None
Typically call this after all device initialization routines and after all asynchronous scheduler
callbacks have been added. There is only one scheduler, so it needs to be started once, no
matter how many devices one is using. Execution of callbacks starts when the scheduler is
started. Forces are enabled at this point also.
hdStartScheduler();
HD_TIMER_ERROR if the servo loop thread could not be initialized or the servo loop could not
be started.
hdStopScheduler

Usage:
Example:
Errors:
See also:

hdStopScheduler
Description:

Stops the scheduler.

Syntax:
Returns:
Usage:

void hdStopScheduler()

Example:
Errors:
See also:
3D Systems, Inc.

None
Typically call this as a first step for cleanup and shutdown of devices.
hdStopScheduler();
hdUnschedule();
hdUnschedule(myCallbackHandle);
hdDisableDevice(hHD);
HD_TIMER_ERROR if the servo loop thread could not be initialized.
hdUnschedule, hdDisableDevice
16

hdUnschedule
Description:

Un-schedules an operation by removing the associated callback from the scheduler.
void hdUnschedule(HDSchedulerHandle hHandle)

Syntax:
Returns:
Usage:

Example:
Errors:
See also:

Argument: hHandle - Handle for an active operation to be unscheduled, obtained via
hdScheduleAsynchronous() or hdScheduleSynchronous().
None
Used to stop an active asynchronous operation. For example, if the application thread has
created an asynchronous operation that returns HD_CALLBACK_CONTINUE to run indefinitely,
the application can call hdUnschedule() to force the callback to terminate.
HDSchedulerHandle hHandle =
hdScheduleAsynchronous(mySchedulerCallback,
(void*)0, 		

HD_DEFAULT_SCHEDULER_PRIORITY);

hdUnschedule(hHandle);
HD_INVALID_OPERATION if the scheduler operation associated with the handle has already
terminated.
hdStopScheduler, hdScheduleAsynchronous, hdScheduleSynchronous

hdWaitForCompletion
Description:
Syntax:

Returns:

Usage:

Checks if a callback is still scheduled for execution. This can be used as a non-blocking test or
can block and wait for the callback to complete.
HDboolean hdWaitForCompletion(HDSchedulerHandle hHandle,
HDWaitCode param)
Argument hHandle - Handle of the target active asynchronous operation.
Argument param - Either HD_WAIT_CHECK_STATUS or HD_WAIT_INFINITE.
Whether the callback is still scheduled.
If HD_WAIT_CHECK_STATUS is passed into param, returns true if the scheduler operation is
still active.
If HD_WAIT_INFINITE is passed into param, this function will return true if the wait was
successful or false if the wait failed.
Can be used on an asynchronous operation to either check the status or to commit to waiting for
the operation to finish.
HDSchedulerHandle hHandle =
hdSchedulerAsynchronous(mySchedulerCallback,
(void*) 0, HD_DEFAULT_SCHEDULER_PRIORITY);

Example:

Errors:
See also:

3D Systems, Inc.

/* Do some other work and then wait for the operation to complete */
HDboolean bWaitSuccess = hdWaitForCompletion(hHandle, HD_WAIT_
INFINITE);
None
hdUnschedule, hdScheduleAsynchronous, hdScheduleSynchronous

17

5 5 HDAPI DEPLOYMENT

hdDeploymentLicense
Description:

Activates the deployment license issued to the application developer. Once the deployment
license has been validated, it will remain active until the application is exited. It is not an error to
call this more than once in an application session.
HDboolean hdDeploymentLicense (const char* vendorName, const char*
applicationName, const char* password)

Syntax:

Argument: vendor - The name of the organization to which the license is issued.
Argument: applicationName - The name of the application the license is tied to.
Argument: password - The license string which authenticates the deployment license.

Returns:

Non-zero if the validation succeeded, zero if the validation failed.

Usage:
Example:
Errors:
See also:

3D Systems, Inc.

Needs to be executed before hdInitDevice to operate correctly. hdInitDevice will fail if the
deployment license is not valid. Note that if a developers license is present hdInitDevice will
succeed.
HDboolean bValid = hdDeploymentLicense (“Haptic Co.”, “Haptic Application”, 6A12...);
HD_DEVICE_FAULT if the calibration information could not obtained from the device.
hdDeploymentLicense

18

6 6 HDAPI TYPES
The following are variable and function types used by the HDAPI.

HDSchedulerCallback Type
Description:
Syntax:
Returns:
Usage:

Scheduler operation function type, used to define operations to be run in the scheduler thread.
typedef HDCallbackCode (HDCALLBACK *HDSchedulerCallabck)
(void *pUserData)
Argument: pUserData - Data used by the operation, created when the operation is scheduled.
HD_CALLBACK_DONE or HD_CALLBACK_CONTINUE depending on whether the operation is
complete or should be executed again the next tick of the scheduler.
Scheduled by hdSchedulerSynchronous() or hdScheduleAsynchronous(), the operation is then
run during the next scheduler tick, or immediately for synchronous operations if the scheduler
has not been started. The return value controls whether the operation terminates after being run
or runs again in the next scheduler tick. A periodic operation, i.e. one that is executed indefinitely,
should return HD_CALLBACK_DONE when it is finally to be unscheduled.
HDCallbackCode HDCALLBACK renderForceCallback(void *pUserData)
{
HDdouble beginTime = hdGetSchedulerTimeStamp();
HHD hHD = hdGetCurrentDevice();
hdBeginFrame(hHD);

Example:

computeForce();
hdEndFrame(hHD);
HDdouble endTime = hdGetSchedulerTimeStamp();
/* Compute the elasped time within this callback */
HDdouble callbackTime = endTime - beginTime;
}

HDSchedulerHandle Type
Description:

A handle to scheduler operations.

Syntax:
Returns:

typedef unsigned long HDSchedulerHandle

Usage:

Example:
Errors:
See also:

3D Systems, Inc.

None
A HDSchedulerHandle is returned whenever the user schedules a scheduler callback. It can
be used for a variety of operations such as unscheduling the associated callback, checking the
status of the callback, and waiting for the callback to complete.
HDSchedulerHandle handle = hdScheduleAsynchronous(
MyServoForceCallbackFunction, 0, HD_MAX_SCHEDULER_PRIORITY);
...
hdUnSchedule(handle);
None
HDSchedulerCallback Type, hdScheduleSynchronous, hdScheduleAsynchronous,
hdUnschedule, hdWaitForCompletion

19

7 7 CONTEXT/FRAME MANAGEMENT

hlBeginFrame

Description:

Syntax:
Returns:
Usage:

Begins a haptics rendering pass, that is, a block of code that sends primitives to the haptic
device to be rendered. hlBeginFrame() updates the current state of the haptic device and clears
the current set of haptics primitives being rendered in preparation for rendering a new or updated
set of primitives. All haptic primitive rendering functions (that is, shapes and effects) must be
made within a begin/end frame pair. hlBeginFrame() also updates the world coordinate reference
frame used by the haptic rendering engine. By default, hlBeginFrame() samples the current
GL_MODELVIEW_MATRIX from OpenGL® to provide a world coordinate space for the entire
haptic frame. All positions, vectors and transforms queried through hlGet*() or hlCacheGet*() in
the client or collision threads will be transformed into that world coordinate space. Typically, the
GL_MODELVIEW_MATRIX contains just the world to view transform at the beginning of a render
pass.
void hlBeginFrame()
none.
Typically, haptic primitives are specified just following (or just before) rendering of graphics
primitives. hlBeginFrame() is called at the start of the haptics update, the primitives are specified,
and then hlEndFrame() is called.
hlBeginFrame();
hlBeginShape(…);

Example:

…
hlEndShape();

Errors:
See also:

hlEndFrame();
HL_INVALID_OPERATION if nested inside another hlBeginFrame() or if no haptic rendering
context is active.
hlEndFrame

hlContextDevice
Description:

Sets the haptic device for the current rendering context.

Syntax:
Returns:
Parameters:

void hlContextDevice(HHD hHD)

Usage:

None
hHD - handle to haptic device or HD_INVALID_HANDLE to set no device.
Used to change which haptic device will be used with the current haptic rendering context.
HD_INVALID_HANDLE can also be used to release the use of the device and deactivate haptic
rendering.
HHD hHD1, hHD2;
…
// create context with first haptic device

Example:

hHLRC = hlCreateContext(hHD1);
hlMakeCurrent(hHLRC);
…
// switch to second device

Errors:

hlContextDevice(hHD2);
HL_INVALID_OPERATION if nested inside another hlBeginFrame() or if no haptic rendering
context is active.

See also:

hlMakeCurrent, hlCreateContext, hlDeleteContext, hlGetCurrentContext, hlGetCurrentDevice

3D Systems, Inc.

20

hlCreateContext
Description:
Syntax:
Returns:
Usage:

Creates a new haptic rendering context. The haptic rendering context stores the current set of
haptic primitives to be rendered as well as the haptic rendering state.
HHLRC hlCreateContext(HHD hHD);
Argument: hHD - Device handle to the initialized haptic device.
HHLRC handle to haptic rendering context.
Called during program initialization after initializing the haptic device.
HD_INVALID_HANDLE can be provided as the device handle in order to create the context in
suspended state.
HDErrorInfo error;
hHD = hdInitDevice(HD_DEFAULT_DEVICE);
if (HD_DEVICE_ERROR(error = hdGetError()))
{

Example:

hduPrintError(stderr, &error, “Failed to initialize haptic device”);
exit(1);
}
hHLRC = hlCreateContext(hHD);

Errors:

hlMakeCurrent(hHLRC);
None

See also:

hlMakeCurrent, hlDeleteContext

hlDeleteContext
Description:
Syntax:
Returns:
Usage:

Deletes a haptic rendering context. The haptic rendering context stores the current set of haptic
primitives to be rendered as well as the haptic rendering state.
void hlDeleteContext(HHLRC hHLRC);
Argument: hHLRC - Handle to haptic rendering context returned by hlCreateContext().
None
Called at program exit to end haptic rendering and deallocate memory.
hHLRC = hlCreateContext(hHD);
hlMakeCurrent(hHLRC);

Example:

…
hlMakeCurrent(NULL);

Errors:

hlDeleteContext(hHLRC);
None

See also:

hlMakeCurrent, hlCreateContext

3D Systems, Inc.

21

hlEndFrame
Description:
Syntax:
Returns:
Usage:

Ends a haptics rendering pass, that is a block of code that sends primitives to the haptic device
to be rendered. hlEndFrame() flushes the set of haptics primitives (that is, shapes, effects)
specified since the last hlBeginFrame() to the haptics device. All haptic primitive rendering
functions must be made within a begin/end frame pair.
void hlEndFrame()
None
Typically, haptic primitives are specified just following (or just before) rendering of graphics
primitives. hlBeginFrame() is called at the start of the haptics update, the primitives are specified,
and then hlEndFrame() is called.
hlBeginFrame();
hlBeginShape(…);

Example:

…
hlEndShape();

Errors:

hlEndFrame();
HL_INVALID_OPERATION if not preceded by an hlBeginFrame(), if inside an hlBeginShape()/
hlEndShape() block, or if no rendering context is active.

See also:

hlBeginFrame

hlGetCurrentContext
Description:

Returns a handle to the currently active haptic rendering context for a given thread.

Syntax:
Returns:
Parameters:
Usage:

HHLRC hlGetCurrentContext(void)
Handle to currently active rendering context for the current thread or NULL if no context is active.
None
Used to query which haptic rendering context is active for a given thread.
HHLRC hHLRC = hlGetCurrentContext();
if (hHLRC != myHLRC)

Example:

{
hlMakeCurrent(myHLRC);

Errors:

}
None

See also:

hlMakeCurrent, hlCreateContext, hlDeleteContext, hlContextDevice, hlGetCurrentContext

hlGetCurrentDevice
Description:

Returns a handle to the haptic device for the currently active haptic rendering context.

Syntax:

HHD hlGetCurrentDevice(void);
Handle to haptic device for currently active rendering context for the current thread or HD_
INVALID_HANDLE if no context is active or no haptic device is selected for the current context.
None

Returns:
Parameters:
Usage:

Used to query which haptic device is active for the current context.
HHHD hHD = hlGetCurrentDevice();
if (hHD == HD_INVALID_HANDLE)

Example:

{
hlContextDevice(myHD);

Errors:

}
None

See also:

hlMakeCurrent, hlCreateContext, hlDeleteContext, hlContextDevice, hlGetCurrentContext

3D Systems, Inc.

22

hlMakeCurrent
Description:
Syntax:

Makes a haptic rendering context current. The current rendering context is the target for all
rendering and state commands. All haptic rendering commands will be sent to the device in the
current context until a context with a different device is made current.
void hlMakeCurrent (HHLRC hHLRC)
Argument: hHLRC - The handle to haptic rendering context returned by hlCreateContext().

Returns:

None

Usage:

Called at program startup after creating the rendering context or called during program execution
to switch rendering contexts in order to render to multiple haptic devices.
HDErrorInfo error;
hHD = hdInitDevice(HD_DEFAULT_DEVICE);
if (HD_DEVICE_ERROR(error = hdGetError()))
{

Example:

hduPrintError(stderr, &error, “Failed to initialize haptic device”);
exit(1);
}
hHLRC = hlCreateContext(hHD);

Errors:

hlMakeCurrent(hHLRC);
None

See also:

hlCreateContext, hlDeleteContext

3D Systems, Inc.

23

8 8 STATE MAINTENANCE AND ACCESSORS

hlEnable, hlDisable
Description:

Syntax:
Returns:
Usage:
Example:
Errors:
See also:

Enables or disables a capability for the current rendering context.
void
void

hlEnable(HLenum cap);
hlDisable(HLenum cap);

Argument: cap - Capability to enable. For a list of possible capabilities see, “Table B-9:
hlEnable, hlDisable, hlIsEnabled” on page 67.
none.
Enables or disables the capability specified.
hlDisable(HL_PROXY_RESOLUTION);
hlProxydv(HL_PROXY_POSITION, newProxyPos);
HL_INVALID_ENUM if cap is not one of the values listed.
hlIsEnabled

hlGetBooleanv, hlGetDoublev, hlGetIntegerv
Description:

Syntax:

Returns:
Parameters:
Usage:

Allow querying of the different state values of the haptic renderer.
void
void
void

hlGetBooleanv(HLenum pname, HLboolean *params)
hlGetDoublev(HLenum pname, HLdouble *params)
hlGetIntegerv(HLenum pname, HLint *params)

Argument: pname - Name of parameter (state value) to query. For a list of parameters see
“Table B-1: hlGetBooleanv, hlGetIntegerv, hlGetDoublev” on page 63.
Argument: params - Address to which to return the value of the parameter being queried.
None
hHD - handle to haptic device or HD_INVALID_HANDLE to set no device.

Errors:

Queries the state of the haptic renderer.
hlDouble proxyPos[3];
hlGetDoublev(HL_PROXY_POSITION, proxyPos);
hlBoolean switchDown;
hlGetBooleanv(HL_BUTTON1_STATE, &switchDown);
HL_INVALID_ENUM if pname is not one of listed values.

See also:

hlIsEnabled, hlCacheGetBooleanv, hlCacheGetDoublev

Example:

3D Systems, Inc.

24

hlGetError
Description:

Returns the error code from the last API command called.

Syntax:

HLerror hlGetError(void);
An HLerror struct containing an HL error code and an optional device specific error code. The
device specific error code is the same as the errorCode in hdGetError(). For an explanation of
these device error codes, see “Table A-15: Device Error Codes” on page 62.

Returns:

Usage:

For a list of possible error codes the errorCode field of the returned HLerror can contain, see
“Table B-3: hlGetError” on page 65.
hlGetError() functions similarly to hdGetError(), i.e. it returns errors in order from most recent to
least. Each call retrieves and removes one error from the error stack. Intersperse hlGetError() in
the code to occasionally check for errors. For a list of possible error codes the errorCode field of
the returned HLerror can contain, see “Table B-3: hlGetError” on page 65.
HLerror error = hlGetError();
if (error.errorCode == HL_DEVICE_ERROR)

Example:

{

Errors:

}
None

hlGetString
Description:

Returns a string describing the haptic renderer implementation.
const HLubyte* hlGetString(HLenum name);

Syntax:

Argument: name - Haptic renderer implementation property to describe. For a list of possible
names, see “Table B-4: hlGetString” on page 66.

Returns:

A static character string describing the implementation of the haptic renderer.

Usage:

Example:
Errors:

3D Systems, Inc.

Used to determine which implementation and version of the HL library is being used. This allows
for programs to take advantage of functionality in newer implementation of the library while
maintaining backward compatibility.
const HLubyte* vendor = hlGetString(HL_VENDOR);
const HLubyte* version = hlGetString(HL_VERSION);
cout << “vendor= “ << vendor << “version= “ << version << endl;
output:
vendor=SensAble Technologies, Inc. version=1.01.23
HL_INVALID_ENUM if name is not one of the values listed.

25

hlHinti, hlHintb
Description:

Sets parameters that allow the haptic renderer to optionally perform selected optimizations.
void hlHinti(HLenum target, HLint value)
void hlHintb(HLenum target, HLboolean value)

Syntax:

Argument: target - Hint property to set. For list of possible values, see “Table B-5: hlHinti,
hlHintb” on page 66.
Argument: value - Value of target property to set.

Returns:
Usage:

None

Example:

Errors:
See also:

Used to allow control over the optimizations used by the haptics renderer.
hlHinti(HL_SHAPE_FEEDBACK_BUFFER_VERTICES, nVertices);
hlBeginShape(HL_SHAPE_FEEDBACK_BUFFER);
glBegin(GL_TRIANGLES);
for (int i = 0; i < nVertices; ++i)
glVertex3f(vertices[i][0], vertices[i][1],
vertices[i][2]);
glEnd();
hlEndShape();
HL_INVALID_ENUM if target is not one of the values listed.
HL_INVALID_VALUE if value is out of range.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlBeginShape, hlPushAttrib, hlPopAttrib

hlIsEnabled
Description:

Checks if a capability is enabled or disabled.

Syntax:

hlBoolean hlIsEnabled(HLenum cap);
HL_TRUE if the capability is enabled in the current rendering context,
HL_FALSE if it is disabled.

Returns:
Parameters:
Usage:
Example:
Errors:

3D Systems, Inc.

Argument: cap - Capability to query. For a list of possible capabilities, see “Table B-9: hlEnable,
hlDisable, hlIsEnabled” on page 67.
None
Used to query if a particular capability feature is enabled. Capabilities include proxy resolution,
haptic camera view, adaptive viewport, and gl modelview.
hlDisable(HL_PROXY_RESOLUTION);
assert(HL_FALSE == hlIsEnabled(HL_PROXY_RESOLUTION));
HL_INVALID_ENUM if cap is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering is current.

26

hlMakeCurrent
Description:
Syntax:

Makes a haptic rendering context current. The current rendering context is the target for all
rendering and state commands. All haptic rendering commands will be sent to the device in the
current context until a context with a different device is made current.
void hlMakeCurrent (HHLRC hHLRC)
Argument: hHLRC - The handle to haptic rendering context returned by hlCreateContext().

Returns:

None

Usage:

Called at program startup after creating the rendering context or called during program execution
to switch rendering contexts in order to render to multiple haptic devices.
HDErrorInfo error;
hHD = hdInitDevice(HD_DEFAULT_DEVICE);
if (HD_DEVICE_ERROR(error = hdGetError()))
{

Example:

hduPrintError(stderr, &error, “Failed to initialize haptic device”);
exit(1);
}
hHLRC = hlCreateContext(hHD);

Errors:

hlMakeCurrent(hHLRC);
None

See also:

hlCreateContext, hlDeleteContext

3D Systems, Inc.

27

9 9 CACHED STATE ACCESSORS

hlCacheGetBooleanv, hlCacheGetDoublev
Description:

These functions allow querying of the different state values from a cached version of the state of
the haptic renderer. Cached renderer states are passed into event and effect callback functions
and contain the renderer state relevant for use by the callback function. The cache is important
due to the multi-threaded implementation of the haptic renderer. The state may change between
the time the event occurs and the time the callback is called.
void hlCacheGetBooleanv(HLcache* cache, HLenum pname, HLboolean
*params)
void hlCacheGetDoublev(HLcache* cache, HLenum pname, HLdouble *params)

Syntax:

Argument: cache - state cache to query
Argument: pname - Name of parameter (state value) to query. For a list of possible pname
values, see “Table B-2: hlCacheGetBooleanv, hlCacheGetDoublev” on page 65.
Argument: params - Address at which to return the value of the parameter being queried.

Returns:

None.

Usage:

Queries the value of the state of the haptics renderer as stored in the state cache. Note that
cached state is a subset of the full renderer state and therefore the possible arguments to the
cached state query functions are a subset of those for the non-cached versions. The HLcache
container is used by events and custom force effects. All positions, vectors and transforms
accessible through hlCacheGet*() are provided in world coordinates for events and workspace
coordinates for custom force effects.
void onClickSphere(HLenum event, HLuint object, HLenum thread,		
HLcache *cache, void *userdata)

Example:

Errors:
See also:

3D Systems, Inc.

{
hlDouble proxyPos[3];
hlCacheGetDoublev(cache, HL_PROXY_POSITION, proxyPos);
hlBoolean switchDown;
hlCacheGetBooleanv(cache, HL_BUTTON1_STATE, &switchDown);
}
HL_INVALID_ENUM if param is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is active.
hlGetBooleanv, hlGetDoublev, hlGetIntegerv, hlAddEventCallback

28

10 10 SHAPES

hlBeginShape

Description:

Indicates that subsequent geometry commands will be sent to the haptic renderer as part of the
shape indicated until hlEndShape() is called. Geometric primitives may only be sent to the haptic
renderer if they are specified inside an hlBeginShape()/hlEndShape() block. Grouping geometric
primitives is important for two reasons:
1.

Event callbacks will report the shape id of geometric primitives touched, and

2.

Correct haptic rendering of geometric primitives that are dynamically moving is
accomplished by looking at frame to frame differences based on shape id.
void hlBeginShape(HLenum type, HLuint shape)

Syntax:

Argument: type - Type of shape to specify. For a list of supported shapes types, see “Table B-6:
hlBegin Shape” on page 66.
Argument: shape - The id of shape to specify returned from an earlier call to hlGenShapes().

Returns:
Usage:

None.

Example:

Errors:
See also:

Used before specifying geometry and callback functions to the haptic renderer.
hlBeginShape(HL_SHAPE_FEEDBACK_BUFFER, myShapeId);
glBegin(GL_TRIANGLES);
glVertex3f(-1,-1,0);
glVertex3f(-1,1,0);
glVertex3f(1,1,0);
glVertex3f(1,-1,0);
glEnd();
hlEndShape();
HL_INVALID_ENUM if the type is not one of the values listed.
HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if already
inside an hlBeginShape()/hlEndShape() block.
hlEndShape, hlHinti, hlHintb, hlCallback

hlDeleteShape
Description:

Deallocates unique identifiers created by hlGenShapes.
void hlDeleteShapes(HLuint shape, HLsizei range)

Syntax:

Argument: shape - ID of first shape to delete.
Argument: range - Number of consecutive unique identifiers to generate.

Returns:
Usage:

None.

Example:

…

Errors:

hlDeleteShapes(myShapeId, 1);
HL_INVALID_VALUE if any of the identifiers to deallocate were not previously allocated by
glGenShapes().
HL_INVALID_OPERATION if no haptic rendering context is active.
hlGenShapes, hlBeginShape, hlIsShape

See also:

3D Systems, Inc.

Deletes all consecutive shape identifiers in the range [shape, shape+range-1].
HLuint myShapeId = hlGenShapes(1);

29

hlEndShape
Description:
Syntax:
Returns:
Usage:

Example:

Errors:
See also:

Completes the shape specified by the last call to hlBeginShape(). Geometry, materials,
transforms and other state for the shape are captured and sent to the haptic renderer.
void hlEndShape()
None.
After a call to hlBeginShape().
hlBeginShape(HL_SHAPE_FEEDBACK_BUFFER, myShapeId);
glBegin(GL_TRIANGLES);
glVertex3f(-1,-1,0);
glVertex3f(-1,1,0);
glVertex3f(1,1,0);
glEnd();
hlEndShape();
HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() or an hlBeginShape()/
hlEndShape() block.
hlBeginShape

hlGenShapes
Description:
Syntax:
Returns:
Usage:
Example:
Errors:
See also:

3D Systems, Inc.

For shapes, generates a unique identifier that may be used with hlBeginShape().
HLuint hlGenShapes(HLsizei range)
Argument: range - Number of unique identifiers to generate.
A unique integer that may be used as an identifier for a shape. If the range is greater than one,
the return value represents the first of a series of range consecutive unique identifiers.
Before a call to hlBeginShape() to create a unique identifier for the new shape.
HLuint myShapeId = hlGenShapes(1);
hlBeginShape(HL_SHAPE_FEEDBACK_BUFFER, myShapeId);
…
hlEndShape();
HL_INVALID_OPERATION if no haptic rendering context is active.
hlBeginShape, hlDeleteShapes, hlIsShape

30

hlLocalFeature
Description:

These functions specify local feature geometry to the haptic renderer.
void hlLocalFeature1fv(HLgeom *geom, HLenum type,
const HLfloat *v)
void hlLocalFeature1dv(HLgeom *geom, HLenum type,
const HLdouble *v)
void hlLocalFeature2fv(HLgeom *geom, HLenum type,
const HLfloat *v1,

Syntax:

const HLfloat *v2)
void hlLocalFeature2dv(HLgeom *geom, HLenum type,
const HLdouble *v1,
const HLdouble *v2)
Argument: geom - Container for local features passed in as parameter to callback shape closest
features callback function.
Argument: ctype - Type of local feature to create. For a list of supported feature types, see
“Table B-8: hlLocalFeature types” on page 67.
Argument: v, v1, v2 - One or two vectors, given in the local coordinates of the shape, which
define the local feature.

Returns:

None
Called from within the closest feature callback function (HLclosestFeaturesProc) of a callback
shape. Used to specify the geometry of whatever local feature of the callback shape is closest to
the proxy position. That local feature is then used by the haptic renderer when either rendering
the callback shape using the constraint touch model or dynamically deforming the callback
shape.

Usage:

In terms of threading, the haptic renderer calls the closest features callback in the collision thread
and stores the local feature that is specified by that callback. The renderer then uses that local
features in the servo thread to constrain the proxy and generate forces.
The example below implements a closest feature callback function for a sphere. A sphere can be
represented locally as a plane tangent to a point of interest on it. So our callback function finds
the closest point on the sphere to the proxy and then generates a plane tangent to the sphere at
that point. This might then be used by the servo thread to constrain the proxy to the surface of
the sphere.

3D Systems, Inc.

31

// find the closest surface feature(s) to queryPt for sphere
// callback shape
bool closestSurfaceFeatures(const HLdouble queryPt[3],
const HLdouble targetPt[3],
HLgeom *geom,
void *userdata)
{
HapticSphere *pThis = static_cast
(userdata);

Example:

// Return a plane tangent to the sphere as the closest
// 2D local feature
hduVector3Dd normal(queryPt);
normal.normalize();
hduVector3Dd point = normal * pThis->getRadius();
hlLocalFeature2dv(geom, HL_LOCAL_FEATURE_PLANE, normal, point);
return true;

Errors:
See also:

}
HL_INVALID_ENUM if ctype is not one of the values listed.
hlBeginShape, hlEndShape

hlIsShape
Description:
Syntax:
Returns:
Usage:
Example:
Errors:
See also:

Determines if an identifier is a valid shape identifier.
HLboolean hlIsShape(HLuint shape)
Argument: shape - Identifier of shape.
Returns HL_TRUE if the shape identifier is a valid allocated value.
Determines if an identifier is a valid shape identifier.
HLuint myShapeId = hlGenShapes(1);
assert(hlIsShape(myShapeId));
HL_INVALID_OPERATION if called within an hlBeginShape()/ hlEndShape() block.
hlGenShapes, hlBeginShape, hlIsShape

hlGetShapeBooleanv, hlGetShapeDoublev
Description:

These functions allow querying of the state of specific shapes.
void hlGetShapeBooleanv(HLuint shapeId, HLenum pname, HLboolean
*params)

Syntax:

void hlGetShapeDoublev(HLuint shapeId, HLenum pname, HLdouble *params)
Argument: geom - Container for local features passed in as parameter to callback shape closest
features callback function.
Argument: shapeid - Identifier of shape to query.
Argument: pname - Name of parameter (state value) to query.
Argument: params - Address at which to return the value of the parameter being queried. For a
list of supported shapes types, see “Shape Parameters” on page 66.

Returns:
3D Systems, Inc.

None
32

Usage:

Queries the state of the shape with identifier shapeid from the haptic rendering engine. This
shape must have been rendered during the last frame.
HLboolean isTouching;
hlGetShapeBooleanv(myShapeId, HL_PROXY_IS_TOUCHING, &isTouching);
if (isTouching)

Example:

{
hduVector3Dd force;
hlGetShapeDoublev(myShapeId, HL_REACTION_FORCE, force);
}

Errors:
See also:

3D Systems, Inc.

HL_INVALID_ENUM if param is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is active.
hlBeginShape, hlEndShape, hlGetBooleanv, hlGetDoublev, hlGetIntegerv

33

11 11 MATERIAL AND SURFACE PROPERTIES

hlGetMaterialfv
Description:

Gets the current haptic material properties for shapes.
void hlGetMaterialfv(HLenum face, HLenum pname, HLfloat *param)

Syntax:

Returns:
Usage:
Example:
Errors:
See also:

Argument: face - Face(s) to apply this material to. For a list of the supported face values, see
“Table B-12: hlGetMaterialfv - face values” on page 68.
Argument: pname - Material property to set. For a list of the supported values for pname, see
“Table B-11: hlMaterialf - pname values” on page 68.
Argument: paramfac - New value for material property.
None.
Used to find the material properties that will be used for rendering shapes.
hlFloat stiffness;
hlGetMaterialfv(HL_FRONT, HL_STIFFNESS, &stiffness);
HL_INVALID_ENUM if the face or pname arguments are not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlMaterialf, hlPushAttrib, hlPopAttrib

hlMaterialf
Description:

Syntax:

Returns:
Usage:
Example:
Errors:
See also:

3D Systems, Inc.

Sets haptic material properties for shapes. Material properties can be set independently for front
and back facing triangles of contact shapes. Only front face materials apply to constraints.
void hlMaterialf(HLenum face, HLenum pname, HLfloat param)
Argument: face - Face(s) to apply this material to. For a list of the supported face values, see
“Table B-10: hlMaterialf - face values” on page 68.
Argument: pname - Material property to set. For a list of the supported values for pname, see
“Table B-11: hlMaterialf - pname values” on page 68.
Argument: param - New value for material property.
None.
Used before defining shapes to set their materials.
hlMaterialf(HL_FRONT_AND_BACK, HL_STIFFNESS, 0.8);
hlMaterialf(HL_FRONT_AND_BACK, HL_DAMPING, 0.6);
hlMaterialf(HL_FRONT_AND_BACK, HL_STATIC_FRICTION, 0.5);
hlMaterialf(HL_FRONT_AND_BACK, HL_DYNAMIC_FRICTION, 0.4);
HL_INVALID_ENUM if the face or pname arguments are not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.
HL_INVALID_VALUE if param is not between 0 and 1.
hlGetMaterialfv, hlPushAttrib, hlPopAttrib

34

hlTouchableFace
Description:

Sets which faces of shapes will be touchable by the haptic device.
void hlTouchableFace(HLenum mode)

Syntax:

Argument: mode - Which face(s) of shapes to make touchable. For a list of mode values, see
“Table B-14: hlTouchableFace - mode values” on page 69.

Returns:

None.

Usage:

Shapes may be touchable on one or both sides. Use this function to set which of those sides is
touchable. The front side of feedback buffer and depth buffer shapes is defined by the winding
order of the vertices as set in OpenGL; that is, triangles considered front facing by OpenGL will
also be considered as front facing by HL.

Example:
Errors:
See also:

When using the HL_CONSTRAINT touch model, all shapes are always touchable from both
sides, independent of the touchable face.
hlTouchableFace(HL_FRONT);
HL_INVALID_ENUM if the mode is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is active.
hlTouchModel

hlTouchModel
Description:

Sets the touch model to specify shapes as contact shapes or constraints.
void hlTouchModel(HLenum mode)

Syntax:

Argument: mode - Contact or constraint model. For a list of supported mode values, see “Table
B-15: hlTouchModel” on page 69.

Returns:

None

Usage:

Used before specifying a shape to set whether it is a contact shape that resists penetration or
whether it is a constraint that will force the haptic device to the surface of the shape.
hlTouchModel(HL_CONTACT);
HL_INVALID_ENUM if mode is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlTouchModelf, hlPushAttrib, hlPopAttrib

Example:
Errors:
See also:

3D Systems, Inc.

35

hlTouchModelf
Description:

Sets properties of the touch model.
void hlTouchModelf(HLenum pname, HLfloat param)

Syntax:

Argument: pname - Touch model parameter to modify. For a list of supported values for pname,
see “Table B-16: hlTouchModelIf” on page 69.
Argument: param - New value for the parameter.

Returns:
Usage:
Example:

None

Errors:

HL_INVALID_ENUM if pname is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.

See also:

hlTouchModel, hlPushAttrib, hlPopAttrib

3D Systems, Inc.

Used before specifying a shape to set the parameters used by the touch model for that shape.
hlTouchModelf(HL_SNAP_DISTANCE, 1.5);

36

13 12 FORCE EFFECTS

hlDeleteEffects
Description:

For effect, deallocates unique identifiers created by hlGenEffects().
void hlDeleteEffects(HLuint effect, HLsizei range)

Syntax:

Argument: effect - Identifier of first effect to delete.
Argument: range - Number of consecutive unique identifiers to generate.

Returns:
Usage:

None.

Example:

…

Errors:

hlDeleteEffects(myEffectId, 1);
HL_INVALID_VALUE if any of the effect identifiers to deallocate were not previously allocated by
glGenEffects()
HL_INVALID_OPERATION if no haptic rendering context is active.
hlGenEffects, hlStartEffect, hlStopEffect, hlIsEffect

See also:

Deletes all consecutive effect identifiers starting in the range [effect, effect+range-1].
HLuint myEffectId = hlGenEffects(1);

hlEffectd, hlEffecti, hlEffectdv, hlEffectiv
Description:

Sets the current value of an effect property.
void hlEffectd (HLenum pname, HLdouble param)
void hlEffecti (HLenum pname, HLint param)
void hlEffectdv (HLenum pname, const HLdouble *params)

Syntax:

void hlEffectiv (HLenum pname, const HLint *params)
Argument: pname - The name of parameter to set. For a list of possible names, see “Table B-19:
hlEffectd, hlEffecti, hlEffectdv, hlEffectiv” on page 70.
Argument: params - The new value of the property.

Returns:

None.

Usage:

Sets the value of an effect property which will be applied to the effect generated by the next call
to hlStartEffect() or hlTriggerEffect().
hlBeginFrame();
hlEffectd(HL_EFFECT_PROPERTY_DURATION, pulseLength);
hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.4);
hlEffectd(HL_EFFECT_PROPERTY_MAGNITUDE, 0.4);
hlTriggerEffect(HL_EFFECT_FRICTION);
hlEndFrame();
HL_INVALID_ENUM if the type is not one of the values listed.
HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if inside an
hlBeginShape()/hlEndShape() block.
hlStartEffect, hlTriggerEffect, hlStartEffect, hlEffectd, hlEffecti, hlEffectdv, hlEffectiv, hlCallback,
hlPushAttrib, hlPopAttrib

Example:

Errors:
See also:

3D Systems, Inc.

37

hlGenEffects
Description:
Syntax:
Returns:
Usage:
Example:

Errors:
See also:

Generates unique identifiers for effects that may be used with hlStartEffect().
HLuint hlGenEffects(HLsizei range)
Argument: range - Number of unique identifiers to generate.
A unique integer that may be used as an identifier for an effect. If the range argument is greater
than one, the return value represents the first of a series of range consecutive unique identifiers.
Before a call to hlStartEffect() to create a unique identifier for the new effect.
HLUintfriction = hlGenEffects(1);
hlBeginFrame();
hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.4);
hlEffectd(HL_EFFECT_PROPERTY_MAGNITUDE, 0.4);
hlStartEffect(HL_EFFECT_FRICTION, friction);
hlEndFrame();
HL_INVALID_OPERATION if no haptic rendering context is active or if inside an hlBeginShape()/
hlEndShape() block.
hlStartEffect, hlStopEffect, hlDeleteEffects, hlIsEffect

hlGetEffectdv, hlGetEffectiv, hlGetEffectbv
Description:

Queries the current value of an effect property.
void hlGetEffectdv (HLuint effect, HLenum pname,
HLdouble *param)
void hlGetEffectiv (HLuint effect, HLenum pname,
HLint *param)

Syntax:

void hlGetEffectbv (HLuint effect, HLenum pname,
HLboolean *params)
Argument: effect - Identifier of effect to query.
Argument: pname - Name of parameter to query. For a list of supported name values, see “Table
B-20: hlEffectd, hlEffecti, hlEffectdv, hlEffectiv” on page 70.
Argument: params - Receives the value of the property.

Returns:

None

Usage:

Gets the value of an effect property which will be applied to the effect generated by the next call
to hlStartEffect() or hlTriggerEffect().
hlBeginFrame();
hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.4);
hlStartEffect(myEffect, HL_EFFECT_FRICTION);
hlEndFrame();

Example:

Errors:
See also:

3D Systems, Inc.

HLdouble gain;
hlGetEffectdv(myEffect, HL_EFFECT_PROPERTY_GAIN, &gain);
assert(gain == 0.4);
HL_INVALID_ENUM if the pname is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is active.
hlStartEffect, hlTriggerEffect, hlEffectd, hlEffecti, hlEffectdv, hlEffectiv

38

hlIsEffect
Description:
Syntax:

Determine if an identifier is a valid effect identifier.
HLboolean hlIsEffect(HLuint effect)
Argument: effect - Identifier of first effect to check.

Returns:
Usage:

None

Example:

…

Returns true if effect is a valid identifier that was previously returned by hlGenEffects().
HLuint myEffectId = hlGenEffects(1);
assert(hlIsEffect(myEffectId);

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlGenEffects

hlStartEffect
Description:

Starts an effect that will continue to run until it is terminated by a call to hlStopEffect().
void hlStartEffect (HLenum type, HLuint effect)

Syntax:

Argument: type - Type of effect to start. For a list of supported types, see “Table B-17:
hlStartEffect - effect types” on page 69.
Argument: effect - Identifier of effect to start, generated by a call to hlGenEffects().

Returns:

None

Usage:

Starting an effect will cause it to continue to run until hlStopEffect() is called to terminate it. When
using hlStartEffect(), the duration property is ignored.
hlBeginFrame();
hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.4);
hlEffectd(HL_EFFECT_PROPERTY_MAGNITUDE, 0.4);
hlStartEffect(HL_EFFECT_FRICTION);
hlEndFrame();
HL_INVALID_ENUM if the type is not one of the values listed.
HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if inside an
hlBeginShape()/hlEndShape() block.
hlStopEffect, hlEffectd, hlEffecti, hlEffectdv, hlEffectiv, hlTriggerEffect, hlCallback

Example:

Errors:
See also:

hlStopEffect
Description:
Syntax:

Stops an effect that was started with hlStartEffect().
void hlStopEffect (HLuint effect);
Argument: effect - Identifier of effect to start, generated by a call to hlGenEffects().

Returns:

None

Usage:

Once an effect has been started by a call hlStartEffect(), it will continue running until
hlStopEffect() is called.
hlBeginFrame();
hlStopEffect(friction);
hlEndFrame();

Example:
Errors:

HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if inside an
hlBeginShape()/hlEndShape() block.

See also:

hlStartEffect, hlEffectd, hlEffectdv, hlEffecti, hlEffectiv, hlTriggerEffect, hlCallback

3D Systems, Inc.

39

hlTriggerEffect
Description:

Starts an effect which will continue to run for a specified duration.
void hlTriggerEffect (HLenum type);

Syntax:

Argument: type - Type of effect to start. For a list of support value types, see “Table B-18:
hlTriggerEffect” on page 70.

Returns:

None

Usage:

Example:

Errors:
See also:

Triggering an effect will cause it to continue to run for the amount of time specified by the current
effect duration. Unlike effects started with hlStartEffect(), those started with hlTriggerEffect() do
not need to be terminated with a call to hlStopEffect(). The effect will be terminated automatically
when the time elapsed since the call to hlTriggerEffect() becomes greater than the effect
duration. The effect duration will be the value specified by the last call to hlEffectd() with HL_
EFFECT_PROPERTY_DURATION.
hlBeginFrame();
hlEffectd(HL_EFFECT_PROPERTY_DURATION, pulseLength);
hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.4);
hlEffectd(HL_EFFECT_PROPERTY_MAGNITUDE, 0.4);
hlTriggerEffect(HL_EFFECT_FRICTION);
hlEndFrame();
HL_INVALID_ENUM if the type is not one of the values listed.
HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if inside an
hlBeginShape()/hlEndShape() block.
hlStartEffect, hlEffectd, hlEffecti, hlEffectdv, hlEffectiv, hlCallback

hlUpdateEffect
Description:
Syntax:
Returns:
Usage:

Updates the given active effect with the current effect state.
hlUpdateEffect(HLuint effect)
Argument: effect - The id of the effect to be updated
None
hlUpdateEffect() is used for changing parameters of an effect that is currently active (has been
started by hlStartEffect(). For example, the user may want to increase the force of a spring effect
each time a button is pressed; hlUpdateEffect() allows the effect to be changed in place without
the user stopping the effect, specifying new parameters, and starting it again. The effect is
updated with whatever effect properties are in the current state, just as if the effect was specified
via hlStartEffect().
hlStartEffect(HL_EFFECT_SPRING, springEffect);

Example:

...

Errors:

HL_INVALID_VALUE if effect is not an active effect.

See also:

hlStartEffect, hlStopEffect

3D Systems, Inc.

hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.1);
hlUpdateEffect(springEffect);

40

14 13 PROXY

hlDeleteEffects
Description:

Sets properties of the proxy.
void hlProxydv (HLenum pname, const HLdouble *params)

Syntax:

Argument: pname - Name of parameter to set. For a list of supported pnames, see “Table B-25:
hlProxydv” on page 72.
Argument: param - Value of the property to set.

Returns:

None.

Usage:

Example:

Errors:
See also:

3D Systems, Inc.

Sets properties of the proxy. The proxy is a virtual object that follows the haptic device but is
constrained by geometric primitives. The force sent to the haptic device is based in part on the
relative positions of the haptic device and proxy. When proxy resolution is enabled, the haptic
rendering engine updates the proxy transform automatically as the haptic device moves and
geometric primitives change. Users may disable automatic proxy resolution (see hlDisable) and
set the proxy transform directly in order to use their own algorithms for proxy resolution.
hlBeginFrame();
hlDisable(HL_PROXY_RESOLUTION);
HLdouble newProxyPos[] = {3, 4, 5};
hlProxydv(HL_PROXY_POSITION, newProxyPos);
hlEndFrame();
HL_INVALID_ENUM if the pname is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is active or if not within an
hlBeginFrame()/hlEndFrame() block.
hlEnable, hlDisable, hlGetBooleanv, hlGetDoublev, hlGetIntegerv

41

15 14 TRANSFORMS

hlLoadIdentity
Description:

Replaces the current matrix on the top of the current matrix stack with the identity matrix.

Syntax:
Returns:

void hlLoadIdentity(void)

Usage:

Example:

None.

Clears the top of the current matrix and replaces it with the identity matrix:
This command applies to either the touchworkspace, viewtouch matrix or
modelview depending on the current matrix mode.

hlMatrixMode(HL_TOUCHWORKSPACE);
hlPushMatrix(); // save off old touchworkspace matrix
hlLoadIdentity(); // set touchworkspace to identity
hlScaled(wsscale, wsscale, wsscale); // set scale
// render some stuff
…

Errors:
See also:

hlPopMatrix(); // restore old touchworkspace matrix
HL_INVALID_OPERATION if no haptic rendering context is active.
hlMatrixMode, hlPushMatrix, hlPopMatrix, hlTranslated, hlTranslatef, hlRotated, hlRotatef,
hlScaled, hlScalef, hlLoadMatrixd, hlLoadMatrixf, hlMultMatrixd, hlMultMatrixf, hlGetBooleanv,
hlGetDoublev, hlGetIntegerv

hlLoadMatrixd, hlLoadMatrixf
Description:
Syntax:
Returns:

Replaces the current matrix on the top of the current matrix stack with the 4x4 matrix specified.
void hlLoadMatrixd(const HLdouble *m)
void hlLoadMatrixf(const HLfloat *m)
Argument: m - An array of 16 floating points or double precision values representing a 4x4
transform matrix.
None.
Clears the top of the current matrix and replaces it with the 4x4 matrix constructed from the
values in m as follows:

Usage:
This command applies to either the touchworkspace, viewtouch matrix or modelview depending
on the current matrix mode.
HLdouble myShapeXfm[16];
…

Example:

hlPushMatrix(); // save off old matrix
hlLoadMatrixd(myShapeXfm); // set xfm
// render some stuff
…

Errors:
3D Systems, Inc.

hlPopMatrix(); // restore old matrix
HL_INVALID_OPERATION if no haptic rendering context is active.
42

See also:

hlMatrixMode, hlPushMatrix, hlPopMatrix, hlTranslated, hlTranslatef, hlRotated, hlRotatef,
hlScaled, hlScalef, hlLoadIdentity, hlMultMatrixd, hlMultMatrixf, hlGetBooleanv, hlGetDoublev,
hlGetIntegerv

hlMultMatrixd, hlMultMatrixf
Description:
Syntax:
Returns:

Multiplies the current matrix on the top of the current matrix stack with the 4x4 matrix specified.
void hlMultMatrixd(const HLdouble *m)
void hlMultMatrixf(const HLfloat *m)
Argument: m - An array of 16 floating points or double precision values representing a 4x4
transform matrix.
None
Replaces the top of the current matrix stack with the product of the top of the stack and the
matrix constructed from the values in m as follows::

Usage:

This command applies to either the touchworkspace, viewtouch matrix or modelview depending
on the current matrix mode.
HLdouble myShapeXfm[16];
…

Example:

hlPushMatrix(); // save off old matrix
hlMultMatrixd(myShapeXfm); // set xfm
// render some stuff
…

Errors:
See also:

hlPopMatrix(); // restore old matrix
HL_INVALID_OPERATION if no haptic rendering context is active.
hlMatrixMode, hlPushMatrix, hlPopMatrix, hlTranslated, hlTranslatef, hlRotated, hlRotatef,
hlScaled, hlScalef, hlLoadIdentity, hlLoadMatrixd, hlLoadMatrixf, hlGetBooleanv, hlGetDoublev,
hlGetIntegerv

hlMatrixMode
Description:

Sets which matrix stack is the target for future calls to matrix manipulation commands.
void hlMatrixMode(HLenum mode);

Syntax:

Argument: mode - Which matrix stack to apply matrix manipulation commands to. See “Table
B-26: hlMatrix - mode values” on page 72 for a list of valid modes.

Returns:

None

Usage:

The HLAPI maintains two transforms that, when multiplied together, determine the mapping
from the local coordinate system of the haptic device (workspace coordinates) to graphical view
coordinates. The first transform maps from touch coordinates to workspace coordinates and the
second maps from view coordinates to touch coordinates. The API maintains a stack of matrices
for each of these of two transforms where the top of the stack represents the current matrix to
use for the transform. HLAPI also maintains an optional modelview matrix stack. The modelview
maps from model coordinates to view coordinates. By default, HLAPI ignores this stack and
instead uses the current OpenGL modelview matrix. This allows easier reuse of OpenGL code
by applying OpenGL transformations to geometry for haptic rendering. In some cases you may
not want to use the OpenGL modelview matrix (for example, if you have no OpenGL rendering
context.) In this case you can disable the use of the OpenGL modelview matrix by calling
hlDisable(HL_USE_GL_MODELVIEW) and HLAPI will use its own modelview matrix instead.
All matrix manipulation commands target the top matrix on one of these two stacks. Setting the
matrix mode controls which of the three stacks is targeted.

3D Systems, Inc.

43

Example:

hlMatrixMode(HL_TOUCHWORKSPACE);
hlPushMatrix(); // save off old touchworkspace matrix
hlLoadIdentity(); // set touchworkspace to identity
hlScaled(wsscale, wsscale, wsscale); // set scale
// render some stuff
…

Errors:
See also:

hlPopMatrix(); // restore old touchworkspace matrix
HL_INVALID_ENUM if the mode is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is active.
hlPushMatrix, hlPopMatrix, hlTranslatef, hlTranslated, hlRotatef, hlRotated, hlScalef, hlScaled,
hlWorkspace, hlLoadMatrixd, hlLoadMatrixf hlMultMatrixd, hlMultMatrixf, hlGetBooleanv,
hlGetDoublev, hlGetIntegerv

hlOrtho
Description:

Sets up the haptic view volume which determines how the workspace of the haptic device will be
mapped into the graphical view volume.
void hlOrtho (HLdouble left, HLdouble right,
HLdouble bottom, HLdouble top,
HLdouble zNear, HLdouble zFar);

Syntax:

Returns:

Usage:

Argument: left, right - The coordinates of the left and right boundaries of the haptic view
volume.
Argument: top, bottom - The coordinates of the top and bottom boundaries of the haptic view
volume.
Argument: zNear, zFar - The coordinates of the front and back boundaries of the haptic view
volume.
None
The hlOrtho() function is used in conjunction with hlWorkspace() to determine the mapping
between the physical workspace of the haptic device and the graphical view. hlOrtho() defines an
orthogonal view volume (that is an axis oriented bounding box) in the graphical view coordinate
system. hlWorkspace() defines a corresponding box in the physical coordinates of the haptic
device. The haptic rendering engine uses these to determine a transformation between the
two coordinate spaces. Specifically, the API creates a transform consisting of a uniform or
non-uniform scale about the center of the workspace box and a translation. The product of
this transform and the top of the matrix stack replaces the current top of the matrix stack. This
function is generally used with the
HL_TOUCHWORKSPACE matrix mode.
hlMatrixMode(HL_TOUCHWORKSPACE);
// clear the matrix stack
hlLoadIdentity();

Example:

// specify the boundaries for the workspace of the haptic
// device in millimeters in the cordiantes of the haptic
// device the haptics engine will map the view volume to
// this workspace
hlWorkspace (-80, -80, -70, 80, 80, 20);
// specify the haptic view volume
hlOrtho (0.0, 1.0, 0.0, 1.0, -1.0, 1.0);

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlWorkspace, hlMatrixMode

3D Systems, Inc.

44

hlPushAttrib, hlPopAttrib
Description:
Syntax:
Returns:

hlPushAttrib() pushes a set of attributes onto the top of the current attribute matrix stack.
hlPopAttrib() removes the top of the current attribute stack.
void hlPushAttrib(HLbitfield mask)
void hlPopAttrib()
Argument: mask - The type of attributes to push. See “Table B-27: hlPushAttrib, hlPopAttrib” on
page 72 for a list of attribute bits.
None

Example:

hlPush()/PopAttrib() allows the user to save and restore rendering state attributes. It works
similarly to hlPush()/PopMatrix(), except that it allows the user to selectively push attributes onto
the stack.
hlPushAttrib(HL_HINT_BIT | HL_TRANSFORM_BIT);

Errors:

HL_INVALID_VALUE if mask is not an attribute bit or set of attribute bits.

See also:

hlPushMatrix, hlPopMatrix

Usage:

hlPushMatrix, hlPopMatrix
Syntax:

hlPushMatrix() pushes a new matrix onto the top of the current matrix stack.
hlPopMatrix() removes the top of the current matrix stack.
void hlPushMatrix()
void hlPopMatrix()

Returns:

None

Description:

Usage:

Example:
Errors:
See also:

3D Systems, Inc.

The HLAPI maintains matrix stacks for the viewtouch matrix, the touchworkspace matrix, and
optionally for the modelview matrix. hlPushMatrix() and hlPopMatrix() allow these matrix stacks
to be changed temporarily and then restored. hlPushMatrix() pushes a new matrix onto the top
of the current matrix stack. The new matrix is initially a duplicate of the existing matrix on the top
of the stack. hlPopMatrix() removes the matrix on the top of the stack, leaving the old top of the
stack as the current matrix.
This command applies to either the touchworkspace, viewtouch matrix, or modelview depending
on the current matrix mode.
hlPushMatrix(); // save off old matrix
hlTranslate(0, 20, 0); // move geometry up 20
// draw some stuff
hlPopMatrix(); // restore old matrix
HL_INVALID_OPERATION if no haptic rendering context is active.
HL_STACK_OVERFLOW if hlPushMatrix() is called when the matrix stack is already full.
HL_STACK_UNDERFLOW if hlPopMatrix() is called when the matrix stack is only one deep.
hlMatrixMode, hlTranslated, hlTranslatef, hlRotated, hlRotatef, hlScaled, hlScalef, hlLoadIdentity,
hlLoadMatrixd, hlLoadMatrixf, hlMultMatrixd, hlMultMatrixf, hlGetBooleanv, hlGetDoublev,
hlGetIntegerv, hlPushAttrib, hlPopAttrib

45

hlRotatef, hlRotated
Description:

Multiplies the current matrix on the top of the current matrix stack by a 4x4 rotation matrix.
void hlRotated (HLdouble angle, HLdouble x, HLdouble y,
HLdouble z)

Syntax:

void hlRotatef (HLfloat angle, HLfloat x,
HLfloat y,HLfloatz)
Argument: angle - Angle, in degrees, to rotate.
Argument: x, y, z - Coordinates of a vector representing the axis about which to rotate.

Returns:

None
Creates a 4x4 rotation matrix that represents a rotation of angle degrees about the given axis.
Replaces the top of the current matrix stack with the product of the top of the matrix stack and
the rotation matrix. The rotation matrix created is of the form:

Usage:

This command applies to either the touchworkspace, viewtouch matrix, or modelview matrix
depending on the current matrix mode.

Example:

hlPushMatrix(); // save off old matrix
hlRotate(45, 0, 0, 1); // rotate 45 degrees about z axis
// draw some stuff
hlPopMatrix(); // restore old matrix

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlMatrixMode, hlPushMatrix, hlPopMatrix, hlTranslated, hlTranslatef, hlScaled, hlScalef,
hlLoadIdentity, hlLoadMatrixd, hlLoadMatrixf, hlMultMatrixd, hlMultMatrixf, hlGetBooleanv,
hlGetDoublev, hlGetIntegerv

hlScalef, hlScaled
Description:
Syntax:

Multiplies the current matrix on the top of the current matrix stack by a 4x4 scale matrix.
void hlScaled(HLdouble x, HLdouble y, HLdouble z);
void hlScalef(HLfloat x, HLfloat y, HLfloat z);
Argument: x, y, z - Scale factors about the x, y and z axes respectively.

Returns:

None
Creates a 4x4 scale matrix that scales about the three coordinate axes. Replaces the top of the
current matrix stack with the product of the top of the matrix stack and the scale matrix. The
scale matrix created is of the form:

Usage:

This command applies to either the touchworkspace, viewtouch matrix, or modelview matrix
depending on the current matrix mode.
3D Systems, Inc.

46

Example:

hlPushMatrix(); // save off old matrix
hlScale(1, 2, 1); // scale 2x along y axis
// draw some stuff
hlPopMatrix(); // restore old matrix

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlMatrixMode, hlPushMatrix, hlPopMatrix, hlTranslated, hlTranslatef, hlRotated, hlRotatef,
hlLoadIdentity, hlLoadMatrixd, hlLoadMatrixf, hlMultMatrixd, hlMultMatrixf, hlGetBooleanv,
hlGetDoublev, hlGetIntegerv

hlTranslatef, hlTranslated
Description:
Syntax:

Multiplies the current matrix on the top of the current matrix stack by a 4x4 translation matrix.
void hlTranslated (HLdouble x, HLdouble y, HLdouble z)
void hlTranslatef (HLfloat x, HLfloat y, HLfloat z)
Argument: x, y, z - Coordinates of translation vector.

Returns:

None
Creates a 4x4 translation matrix based on the vector (x, y, z) and replaces the top of the current
matrix stack with the product of the top of the matrix stack and the translation matrix. The
translation matrix created is of the form::

Usage:

This command applies to either the touchworkspace, viewtouch matrix, or modelview matrix
depending on the current matrix mode.

Example:

hlPushMatrix(); // save off old matrix
hlTranslate(0, 20, 0); // move geometry up 20
// draw some stuff
hlPopMatrix(); // restore old matrix

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlMatrixMode, hlPushMatrix, hlPopMatrix, hlRotated, hlRotatef, hlScaled, hlScalef,
hlLoadIdentity, hlLoadMatrixd, hlLoadMatrixf, hlMultMatrixd, hlMultMatrixf, hlGetBooleanv,
hlGetDoublev, hlGetIntegerv

hlWorkspace
Description:

Syntax:

Returns:

3D Systems, Inc.

Defines the extents of the workspace of the haptic device that will be used for mapping between
the graphics coordinate system and the physical units of the haptic device.
void hlWorkspace (HLdouble left, HLdouble bottom, HLdouble back,
HLdouble right, HLdouble top, HLdouble front);
Argument: left, right - The coordinates of the left and right boundaries of the haptic device
workspace.
Argument: top, bottom - The coordinates of the top and bottom boundaries of the haptic view
volume.
Argument: from, back - The coordinates of the front and back boundaries of the haptic view
volume.
None

47

Usage:

The hlWorkspace() function is used in conjunction with hlOrtho() to determine the mapping
between the physical workspace of the haptic device and the graphical view. hlOrtho() defines
an orthogonal view volume (that is, an axis oriented bounding box) in the graphical view
coordinate system. hlWorkspace() defines a corresponding box in the physical coordinates of the
haptic device. The haptic rendering engine uses these to determine a transformation between
the two coordinate spaces. Specifically, the API creates a transform consisting of a uniform
or non-uniform scale about the center of the workspace box and a translation. The product of
this transform and the top of the matrix stack replaces the current top of the matrix stack. This
function is generally used with the
HL_TOUCHWORKSPACE matrix mode.
hlMatrixMode(HL_TOUCHWORKSPACE);
// clear the matrix stack
hlLoadIdentity();

Example:

// specify the boundaries for the workspace of the haptic
// device in millimeters in the coordinates of the haptic
// device the haptics engine will map the view volume to
// this workspace
hlWorkspace (-80, -80, -70, 80, 80, 20);
// specify the haptic view volume
hlOrtho (0.0, 1.0, 0.0, 1.0, -1.0, 1.0);

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlOrtho, hlMatrixMode

3D Systems, Inc.

48

16 15 CALLBACKS

hlCallback
Description:

Sets a user callback function.
void hlCallback (HLenum type, HLcallbackProc fn, void *userdata)

Syntax:

Argument: type - Name of callback to set. For a list of supported type values, see “Table B-21:
hlCallback” on page 71.
Argument: fn - Pointer to callback function.
Argument: userdata - Pointer to client specific data that will be passed to the callback function.

Returns:
Usage:

None.

Example:

			&intersectSurface, (void*) &myShapeData);
hlCallback(HL_SHAPE_CLOSEST_POINT, (HLcallbackProc)

Errors:
See also:

3D Systems, Inc.

Used to set callback functions for custom shapes and custom effect types.
hlBeginShape(HL_SHAPE_CALLBACK, myshape);
hlCallback(HL_SHAPE_INTERSECT_LS, HLcallbackProc)

			&closestPointSurface, (void*) &myShapeData);
hlEndShape();
HL_INVALID_ENUM if type is not one of the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlBeginShape

49

17 16EVENTS

hlAddEventCallback
Description:

Adds a user defined event handling function to the list of callback functions for an event.
void hlAddEventCallback (HLenum event, HLuint shapeId,
HLenum thread, HLeventProc fn,
void *userdata)

Syntax:

Argument: event - Event to which to subscribe. For a list of supported event values, see “Table
B-22: hlAddEventCallback, hlRemoveEventCallBack - event values” on page 71.
Argument: shapeID - Identifier of shape. Callback will only be called if the event occurs on
the shape with this identifier unless this argument is set HL_OBJECT_ANY in which case the
callback will be called independent of any objects.
Argument: thread - Thread to have callback function called in. For a list of support thread
values, see “Table B-23: hlAddEventCallback, hlRemoveEventCallback - thread values” on page
72.
Argument: fn - Pointer to callback function.
Argument: userdata - Pointer to client specific data that will be passed to the callback function.

Returns:

None.

Usage:

Event callbacks are used to inform programs about occurrences in the haptic renderer such as
an object being touched.
void HLCALLBACK onClickSphere(HLenum event, HLuint object,
HLenum thread,
HLcache *cache,
void *userdata)
{

Example:

// handle event
}

Errors:
See also:

hlAddEventCallback(HL_EVENT_1BUTTONDOWN, mySphereId,
HL_CLIENT_THREAD, &onClickSphere,
(void*) &mydata);
HL_INVALID_ENUM if event and thread are not among the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlRemoveEventCallback, hlEventd, hlCheckEvents

hlCheckEvents
Description:
Syntax:
Returns:

3D Systems, Inc.

Calls callback functions for all events that are subscribed to and that have occurred since the last
call to hlCheckEvents().
void hlCheckEvents()
None.

50

Should be called on a regular basis in the client thread. This is often called as part of the main
rendering loop or main event loop. This function checks if any subscribed events have been
triggered since the last call to hlCheckEvents(). If any events have been triggered, then event
callbacks for these events will be called synchronously before the call to hlCheckEvents()
returns. This only applies to event callbacks in the client thread

Usage:

(HL_THREAD_CLIENT), collision thread events will be called from within the collision thread,
outside of call to the hlCheckEvents().
hlCheckEvents() can be called outside of a begin/endFrame pair. It can be called in place of
a begin/end frame to update just device and event state. For example, if the user is feeling a
static scene and only needs to have updated device state information periodically, he can forego
calling hlBegin()/EndFrame() and instead just call hlCheckEvents() periodically.
void HLCALLBACK onMotion(HLenum event, HLuint object,
HLenum thread, HLcache *cache,
void *userdata)
{
hlBeginFrame();
drawScene();
hlEndFrame();
}

Example:

void setup()
{
hlAddEventCallback(HL_EVENT_MOTION, HL_OBJECT_ANY,
HL_CLIENT_THREAD, &onMotion, NULL);
}
void onIdle()
{
hlCheckEvents();

Errors:
See also:

3D Systems, Inc.

}
HL_INVALID_OPERATION if no haptic rendering context is current.
hlAddEventCallback, hlRemoveEventCallback, hlEventd

51

hlEventd
Description:

Sets parameters that influence how and when event callbacks are called.
void hlEventd(HLenum pname, HLdouble param)

Syntax:

Argument: pname - Name of event parameter to set. For a list of pname parameters, see “Table
B-24: hlEventd - pname values” on page 72.
Argument: param - Value of parameter to set.

Returns:

None.

Usage:

Used at program startup to tailor the event management of the haptic renderer to the specific
application.
hlEventd(HL_EVENT_MOTION_LINEAR_TOLERANCE, 10);
HL_INVALID_ENUM if pname is not one of the values listed.
HL_INVALID_VALUE if param value is out of range.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlAddEventCallback; hlPushAttrib, hlPopAttrib

Example:
Errors:
See also:

hlRemoveEventCallback
Description:

Syntax:

Removes an existing user defined event handling function from the list of callback functions for
an event.
void hlRemoveEventCallback (HLenum event, HLuint shapeId,
HLenum thread, HLeventProc fn)
Argument: event - Subscribed event. For a list of event parameters, see “Table B-22:
hlAddEventCallback, hlRemoveEventCallBack - event values” on page 71.
Argument: shapeID - Identifier of shape. Callback will only be called if the event occurs on
the shape with this identifier unless this argument is set: HL_OBJECT_ANY. In which case the
callback will be called regardless of what object is being touched.
Argument: thread - Thread in which to have callback function called. For a list of thread
parameters, see “Table B-23: hlAddEventCallback, hlRemoveEventCallback - thread values” on
page 72.
Argument: fn - Pointer to callback function.

Returns:

None

Usage:

Removes any event callback that was added to list of subscribed events with a call to
hlAddEventCallback() with the same event, thread, shapeId and fn pointer.
void HLCALLBACK onClickSphere(HLenum event, HLuint object,
HLenum thread, HLcache *cache,
void *userdata)
{
// handle event

Example:

Errors:
See also:

3D Systems, Inc.

}
hlAddEventCallback(HL_EVENT_1BUTTONDOWN, mySphereId,
HL_CLIENT_THREAD, &onClickSphere,
void*) &mydata);
hlRemoveCallback(HL_EVENT_1BUTTONDOWN, mySphereId,
HL_CLIENT_THREAD, &onClickSphere);
HL_INVALID_ENUM if event and thread are not among the values listed.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlAddEventCallback, hlCheckEvents, hlEventd

52

hlIsEffect
Description:
Syntax:

Determine if an identifier is a valid effect identifier.
HLboolean hlIsEffect(HLuint effect)
Argument: effect - Identifier of first effect to check.

Returns:
Usage:

None

Example:

…

Returns true if effect is a valid identifier that was previously returned by hlGenEffects().
HLuint myEffectId = hlGenEffects(1);
assert(hlIsEffect(myEffectId);

Errors:

HL_INVALID_OPERATION if no haptic rendering context is active.

See also:

hlGenEffects

hlStartEffect
Description:

Starts an effect that will continue to run until it is terminated by a call to hlStopEffect().
void hlStartEffect (HLenum type, HLuint effect)

Syntax:

Argument: type - Type of effect to start. For a list of supported types, see “Table B-17:
hlStartEffect - effect types” on page 69.
Argument: effect - Identifier of effect to start, generated by a call to hlGenEffects().

Returns:

None

Usage:

Starting an effect will cause it to continue to run until hlStopEffect() is called to terminate it. When
using hlStartEffect(), the duration property is ignored.
hlBeginFrame();
hlEffectd(HL_EFFECT_PROPERTY_GAIN, 0.4);
hlEffectd(HL_EFFECT_PROPERTY_MAGNITUDE, 0.4);
hlStartEffect(HL_EFFECT_FRICTION);
hlEndFrame();
HL_INVALID_ENUM if the type is not one of the values listed.
HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if inside an
hlBeginShape()/hlEndShape() block.
hlStopEffect, hlEffectd, hlEffecti, hlEffectdv, hlEffectiv, hlTriggerEffect, hlCallback

Example:

Errors:
See also:

hlStopEffect
Description:
Syntax:

Stops an effect that was started with hlStartEffect().
void hlStopEffect (HLuint effect);
Argument: effect - Identifier of effect to start, generated by a call to hlGenEffects().

Returns:

None

Usage:

Once an effect has been started by a call hlStartEffect(), it will continue running until
hlStopEffect() is called.
hlBeginFrame();
hlStopEffect(friction);
hlEndFrame();

Example:
Errors:

HL_INVALID_OPERATION if not inside an hlBeginFrame()/hlEndFrame() block or if inside an
hlBeginShape()/hlEndShape() block.

See also:

hlStartEffect, hlEffectd, hlEffectdv, hlEffecti, hlEffectiv, hlTriggerEffect, hlCallback

3D Systems, Inc.

53

18 17CALIBRATION

hlUpdateCalibration
Description:

Causes the haptic device to recalibrate.

Syntax:
Returns:

void hlUpdateCalibration(void)
None.
Calibration of the haptic device is a two-stage process. First, new calibration data must be found.
How this is done depends on the device hardware.

Usage:

•

For the Geomagic Touch, new calibration data is found when the stylus is inserted into the
inkwell.

•

For the Geomagic Touch X, calibration data is found as the device is moved about the extents of
the workspace.

A program may subscribe to the HL_EVENT_CALIBRATION_UPDATE event to be notified when
valid calibration data has been found. It may also subscribe to the
HL_EVENT_CALIBRATION_INPUT event when to be notified when the device requires user
input (such as inserting the stylus into the inkwell) in order to obtain valid data.
Once valid calibration has been found, next hlUpdateCalibration() is called to flush that
data to the haptic device. Note that the change in calibration may cause a large discontinuity in
the positions reported by the device. For this reason, hlUpdateCalibration() should not be
called while the user is in the middle of an operation that relies on continuity of reported device
positions (for example, drawing or manipulating an object). For a list of calibration event types
see “Table B-28: Calibration Event Types” on page 73.
void HLCALLBACK calibrationCallback(HLenum event, HLuint object,
HLenum thread, HLcache *cache,
void *userdata)
{
if (event == HL_EVENT_CALIBRATION_UPDATE)
{
std::cout << “Device requires calibration update...” << std::endl;
hlUpdateCalibration();
}

Example:

else if (event == HL_EVENT_CALIBRATION_INPUT)
{
std::cout << “Device requires calibration.input...” << std::endl;
}
}
…
hlAddEventCallback(HL_EVENT_CALIBRATION_UPDATE, HL_OBJECT_ANY,
HL_CLIENT_THREAD, &calibrationCallback, NULL);
hlAddEventCallback(HL_EVENT_CALIBRATION_INPUT, HL_OBJECT_ANY,

Errors:
See also:

3D Systems, Inc.

HL_CLIENT_THREAD, &calibrationCallback, NULL);
HL_INVALID_ENUM if pname is not one of the values listed.
HL_INVALID_VALUE if value is out of range.
HL_INVALID_OPERATION if no haptic rendering context is current.
hlAddEventCallback

54

19 18HLAPI DEPLOYMENT

hlDeploymentLicense
Description:

Activates the deployment license issued to the application developer. Once the deployment
license has been validated, it will remain active until the application is exited. It is not an error to
call this more than once in an application session.
HLboolean hlDeploymentLicense (const char* vendorName, const char*
applicationName, const char* password)

Syntax:

Argument: vendor - The name of the organization to which the license is issued.
Argument: applicationName - The name of the application the license is tied to.
Argument: password - The license string which authenticates the deployment license.

Returns:

Non-zero if the validation succeeded, zero if the validation failed.

Usage:

Needs to be executed before hlCreateContext to operate correctly. hlCreateContext will fail if the
deployment license is not valid. Note that if a developers license is present, hlCreateContext will
succeed.

Example:

HLboolean bValid = hlDeploymentLicense (“Haptic Co.”, “Haptic
Application”, 6A12...);

3D Systems, Inc.

55

20 19HAPTIC DEVICE API PARAMETERS
The following pages contain tables that list the names of the HDAPI parameters. For each parameter the table lists a description and
what types and how many values are used by each parameter name. The developer is responsible for supplying the correct number of
parameters for the particular parameter name. Not all parameter names support every type.
The parameters are grouped as follows:
Topic
Get Parameters
Set Parameters
Capability Parameters
Codes

Page
page 56
page 59
page 61
page 61

Get Parameters
Table A-1: hdGet Parameters
Parameter Name
HD_CURRENT_BUTTONS

HD_CURRENT_SAFETY_SWITCH
HD_CURRENT_INKWELL_SWITCH
HD_CURRENT_ENCODER_VALUES
HD_CURRENT_POSITION
HD_CURRENT_VELOCITY
HD_CURRENT_TRANSFORM

Number of
Arguments

Description

Get the button state. Individual button values can be
retrieved by doing bitwise & with
1
HD_DEVICE_BUTTON_N (N=1,2,3, or 4).
Get whether the safety switch, if one exists, is
active. For example, the Geomagic Touch X safety
1
switch is true if the conductive portion of the stylus
is being held.
Get whether the inkwell switch, if one exists is
1
active.
Get the raw encoder values.
6
Get the current position of the device facing the
device base. Right is + x, up is +y, toward user is
3
+z.
Get the current velocity of the device. Note: This
3
value is smoothed to reduce high frequency jitter.
Get the column-major transform of the device end16
effector.

HD_CURRENT_ANGULAR_VELOCITY Gets the angular velocity of the device gimbal.

HD_CURRENT_JOINT_ANGLES

HD_CURRENT_GIMBAL_ANGLES
HD_USER_STATUS LIGHT

Get the joint angles of the device. These are joint
angles used for computing the kinematics of the
armature relative to the base frame of the device.
For Touch devices: Turet Left +, Thigh Up +, Shin
Up +
Get the angles of the device gimbal. For Touch
devices: From Neutral position Right is +, Up is -,
CW is +
Get the user setting of the LED status light. See
hdDefine.h for constant settings.

3

HDint

HDboolean
HDboolean
HDlong
HDdouble,
HDfloat
HDdouble,
HDfloat
HDdouble,
HDfloat
HDdouble,
HDfloat

mm
mm/s

rad/s

HDdouble,
HDfloat

rad

3

HDdouble,
HDfloat

rad

1

HDint

Get the current normalized pinch encoder value
(Windows only).

1

HD_LAST_PINCH_VALUE

Get the last normalized pinch encoder value
(Windows only).

1

56

Units

3

HD_CURRENT_PINCH_VALUE

3D Systems, Inc.

Allowed
Types

HDdouble
HDfloat
HDdouble
HDfloat

Table A-2: Get Forces Parameters
Parameter Name

HD_CURRENT_FORCE

HD_CURRENT_TORQUE

HD_CURRENT_MOTOR_DAC_
VALUES
HD_CURRENT_ENCODER_VALUES
HD_CURRENT_JOINT_TORQUE

HD_CURRENT_GIMBAL_TORQUE

Description
Get the current force, i.e. the force that the user
is commanding to the device during the frame in
which this is called. Returns 0 if no force has been
commanded yet in the frame.
Get the current torque, i.e. the torque that the user
is commanding to the device during the frame in
which this is called. Returns 0 if no torque has
been commanded yet in the frame.
Get the current motor DAC, i.e. the motor value
that the user is commanding to the device during
the frame in which this is called. Returns 0 if no
DAC has been commanded yet in the frame.
Get the raw encoder values.
Get the current joint torque, i.e. the torque the
user is commanding to the first 3 joints of the
device during the frame in which this is called.
Returns 0 if no joint torque has been commanded
yet in the frame.
Get the current gimbal torque, i.e. the gimbal
torque the user is commanding to the device
during the frame in which this is called. Returns 0
if no gimbal torque has been commanded yet in
the frame.

Number of
Arguments

Allowed
Types

Units

3

HDfloat,
HDdouble

N

3

HDfloat,
HDdouble

mNm

3 or 6

HDlong

Inclusive
range
[-32767,
32766]

6

HDlong

3

HDfloat,
HDdouble

mNm

3

HDfloat,
HDdouble

mNm

Number of
Arguments
1

Allowed
Types
HDdouble

1

HDstring

1
1
1
1

HDstring
HDstring
HDstring
HDstring

6

HDfloat,
HDdouble

mm

6

HDfloat,
HDdouble

mm

1

HDfloat

mm

1

HDint

1

HDint

Table A-3: Get Identification Parameters
Parameter Name

Description

HD_FIRMWARE_REVISION

Get the firmware revision.
Get the HDAPI software version, in the form of
major.minor.build. This is taken from the HD_
VERSION_ definitions.
Get a readable string of the device model type
Get a readable string of the driver version.
Get a readable string of the device vendor..
Gets a readable string of the device serial number.
Get the maximum workspace dimensions of the
device, i.e. the maximum mechanical limits of
the device, as (minX, minY, minZ, maxX, maxY,
maxZ).
Get the usable workspace dimensions of the
device, i.e. the practical limits for the device, as
(minX, minY, minZ, maxX, maxY, maxZ). It is
guaranteed that forces can be reliably rendered
within the usable workspace dimensions.
Get the mechanical offset of the device endeffector in Y from the table top.
Get the number of input degrees of freedom. (i.e.
the number of independent position variables
needed to fully specify the end-effector location for
Touch device) 3DOF input means xyz tranlsational
sensing-only. 6DOF means 3 translation and 3
rotation.
Get the number of output degrees of freedom, i.e.
the number of independent actuation variable.
For Touch devices 3DOF means XYZ linear force
output whereas 6DOF means xyz linear forces
and roll, pitch, yaw, torques about gimbal.

HD_VERSION
HD_DEVICE_MODEL_TYPE
HD_DEVICE_DRIVER_VERSION
HD_DEVICE_VENDOR
HD_DEVICE_SERIAL_NUMBER
HD_MAX_WORKSPACE_
DIMENSIONS

HD_USABLE_WORKSPACE_
DIMENSIONS
HD_TABLETOP_OFFSE

HD_INPUT_DOF

HD_OUTPUT_DOF

3D Systems, Inc.

57

Units

Number of
Arguments

Parameter Name

Description

HD_CALIBRATION_STYLE

The style(s) of calibration supported by the device.
Can be one or more bitwise of the following HD_
CALIBRATION_AUTO,
1
HD_CALIBRATION_ENCODER_RESET, or HD_
CALIBRATION_INKWELL

Allowed
Types

Units

HDint

Table A-4: Get Last Values Parameters
Parameter Name
HD_LAST_BUTTONS
HD_LAST_SAFETY_SWITCH
HD_LAST_INKWELL_SWITCH
HD_LAST_ENCODER_VALUES
HD_LAST_POSITION
HD_LAST_VELOCITY
HD_LAST_TRANSFORM
HD_LAST_ANGULAR_VELOCITY

HD_LAST_JOINT_ANGLES

HD_LAST_GIMBAL_ANGLES

3D Systems, Inc.

Description
Get last frame’s button state. Individual button
values can be retrieved by doing bitwise & with
HD_DEVICE_BUTTON_N (N=1,2,3, or 4).
Get last frame’s safety switch active status.
Get last frame’s inkwell switch active status.
Get last frame’s raw encoder values.
Get the last position of the device facing the
device base. Right is + x, up is +y, toward user is
+z.
Get the last velocity of the device. Note: this value
is smoothed to reduce high frequency jitter.
Get the last row-major transform of the device
end-effector.
Get the last Cartesian angular velocity of the
device gimbal.
Get the last joint angles of the device. These are
joint angles used for computing the kinematics
of the armature relative to the base frame of the
device. For Touch devices: Turet Left +, Thigh Up
+, Shin Up +
Get the last angles of the device gimbal. For
Touch devices: From Neutral position Right is +,
Up is -, CW is +

58

Number of
Arguments

Allowed
Types

1

HDint

1
1
6

HDboolean
HDboolean
HDlong

3

HDdouble,
HDfloat

3
16
3

HDdouble,
HDfloat
HDdouble,
HDfloat
HDdouble,
HDfloat

Units

mm
mm/s

rad

3

HDdouble,
HDfloat

rd

3

HDdouble,
HDfloat

rad/s

Table A-5: Get Safety Parameters
Parameter Name

HD_NOMINAL_MAX_STIFFNESS

HD_NOMINAL_MAX_DAMPING

HD_NOMINAL_MAX_FORCE
HD_NOMINAL_MAX_CONTINUOUS_
FORCE
HD_MOTOR_TEMPERATURE
HD_SOFTWARE_VELOCITY_LIMIT
HD_SOFTWARE _FORCE_IMPULSE_
LIMIT
HD_FORCE_RAMPING_RATE

Description
Get the maximum closed loop stiffness that is
recommended for the device, i.e. the spring
constant used in F=kx output where k is the
spring constant and x is the spring length.
Get the maximum level of damping that is
recommended for the device, i.e. the damping
constant used in F=kx-dv where d is the damping
constant and v is the velocity of the device.
Get the nominal maximum force, i.e. the amount
of force that the device can sustain when the
motors are at room temperature (optimal).
Get the nominal maximum continuous force, i.e.
the amount of force that the device can sustain
through a period of time.
Get the motor temperature, which is the
predicted temperature of all of the motors.

Number of
Arguments

Allowed
Types

Units

1

HDfloat,
HDdouble

0 to 1

1

HDfloat,
HDdouble

0 to 1

1

HDfloat,
HDdouble

N

1

HDfloat,
HDdouble

N

3 or 6

HDfloat,
HDdouble

0(coldest)
to
1(warmest)

HDfloat,
HDdouble

mm/s

HDfloat

N

HDfloat,
HDdouble

N/s

Number of
Arguments

Allowed
Types

Units

1

HDint

Hz

1

HDint

Hz

Get the software maximum velocity limit. This
1
does not replace the hardware limit of the device.
Get the software maximum force impulse limit.
This does not replace the hardware limit of the
1
device.
Get the force ramping rate, which is the rate that
the device ramps up forces when the scheduler 1
is started or after an error.

Table A-6: Get Scheduler Update Codes Parameters
Parameter Name
HD_UPDATE_RATE
HD_INSTANTANEOUS_UPDATE_
RATE

Description
Get the average update rate of the device,
i.e. the number of updates that the scheduler
performs per second.
Get the instantaneous update rate of the device,
i.e. I/T where T is the time in seconds since the
last update.

Set Parameters
Table A-7: Set Parameters
Parameter Name

Description

HD_USER_STATUS_LIGHT

Allows the user to set the LED status light.

3D Systems, Inc.

59

Number of
Arguments
1

Allowed
Types
HDint

Units

Table A-8: Set Forces Parameters
Parameter Name

HD_CURRENT_FORCE

HD_CURRENT_TORQUE

HD_CURRENT_MOTOR_DAC_
VALUES

HD_CURRENT_JOINT_TORQUE

HD_CURRENT_GIMBAL_TORQUE

Description
Set the current force as Cartesian coordinated
vector. This is the primary method for sending
forces to the device. Setting the current force
causes that force to be commanded at end of the
frame.
Set the current torque Cartesian coordinated
vector, for 6DOF devices This is the primary
method for sending torques to the device.
Setting the current torque causes that torque to
be commanded at end of the frame.
Set the current motor DAC values. This is the
primary method for commanding the amount
of motor torque counts. This method cannot
presently be used in combination with Cartesian
force or torque commands.
Set the current torque as a joint coordinated
vector for the first three joints of the Touch
device. Setting the current joint torque causes
that torque to be commanded at end of the
frame.
Set current gimbal torque as a joint coordinated
vector for the three gimbal joints of the Touch
6DOF device. Setting the current gimbal torque
causes that torque to be commanded at end of
the frame.

Number of
Arguments

Allowed
Types

Units

3

N

Hz

3

Nm

Hz

3 or 6

Inclusive
range of
“[-32767,
32766]”

3

mNm

3

mNm

Number of
Arguments

Allowed
Types
HDfloat,
HDdouble

Table A-9: Set Safety Parameters
Parameter Name
HD_SOFTWARE_VELOCITY_LIMIT
HD_SOFTWARE_FORCE_IMPULSE_
LIMIT
HD_FORCE_RAMPING_RATE

3D Systems, Inc.

Description

Set the software maximum velocity limit. This
1
does not replace the hardware limit of the device.
Sets the software maximum force impulse limit,
which is the maximum change in magnitude
1
and direction calculated by taking the difference
between the current and last commanded force.
Set the force ramping rate, which is the rate that
the device ramps up forces when the scheduler 1
is started or after an error.

60

Units
mm/s

HDfloat,
HDdouble

N/ms

HDfloat,
HDdouble

N/s

Capability Parameters
Table A-10: hdEnable, hdDisable Parameters
Parameter Name
HD_FORCE_OUTPUT
HD_MAX_FORCE_CLAMPING
HD_FORCE_RAMPING
HD_SOFTWARE_FORCE_LIMIT
HD_SOFTWARE_VELOCITY_LIMIT
HD_SOFTWARE_FORCE_IMPULSE_LIMIT
HD_ONE_FRAME_LIMIT
HD_USER_STATUS_LIGHT

Description
Enables or disables force output for the device. All motors are turned on or off.
Enables or disables max force clamping for the device. If enabled, this will clamp
the overall force output magnitude to the maximum achievable.
Enables or disables force ramping, i.e. whether the device ramps up forces when
the scheduler is turned on.
Enables or disables the software maximum force check, which returns an error if
the force magnitude commanded to the device exceeds the maximum force limit.
This is primarily to disable force kicking. Disable this at your own risk.
Enables or disables the software maximum velocity check, which returns an error
if the velocity magnitude commanded to the device exceeds the maximum velocity
limit. This is primarily to disable force kicking. Disable this at your own risk.
Enables or disables the software maximum force impulse check, which prevents
changes in force impulse and direction that exceed the change of impulse limit.
This is primarily to prevent device kicking. Disable this at your own risk.
Enables or disables the one frame limit check, which restricts the application to
one haptics frame per scheduler tick This should only be disabled if the developer
is running his own scheduler.
Enables or disables user specified setting of the LED status light on the device.

Codes
Table A-11: Calibration Return Codes
Parameter Name
HD_CALIBRATION_OK
HD_CALIBRATION_NEEDS_UPDATE
HD_CALIBRATION_NEEDS_MANUAL_INPUT

Description
Calibration is accurate.
Calibration needs an update. Call hdUpdateCalibration() to have the device
update its calibration.
Calibration needs manual input, such as having the user put the device in a reset
position or inkwell. Once the user does this, further calls should no longer return
that the calibration needs manual input.

Table A-12: Calibration Styles
Parameter Name

Description

HD_CALIBRATION_ENCODER_RESET
HD_CALIBRATION_AUTO

The device needs to be put in a reset position to be calibrated.
The device will gather new calibration information as the armature is moved.
Inkwell calibration. The device needs to put into a fixture, i.e. inkwell, before
calibration can be performed.

HD_CALIBRATION_INKWELL

Table A-13: Device Button Codes
Parameter Name

Description

HD_DEVICE_BUTTON_N (N=1,2,3, or 4)

Button states for current and last buttons. Use bitwise & to extract individual
button information.

3D Systems, Inc.

61

Table A-14: Scheduler Priority Codes
Parameter Name
HD_MAX_SCHEDULER_PRIORITY
HD_MIN_SCHEDULER_PRIORITY
HD_DEFAULT_SCHEDULER_PRIORITY

Description
Maximum priority for a scheduler callback. Setting a callback with this priority
means that the callback will be run first every scheduler tick in relation to other
callbacks.
Minimum priority for a scheduler callback. Setting a callback with this priority
means that the callback will be run last every scheduler tick in relation to other
callbacks.
Default scheduler priority. Set this for callbacks that do not care about when
they are executed during the scheduler tick. This value is between min and max
priority.

Table A-15: Device Error Codes
Parameter Name

Description

HD_SUCCESS

No error
Invalid parameter of capability specified for a function that requires an HDenum
as one of its inputs.

HD_INVALID_ENUM
HD_INVALID_VALUE

Invalid value specified for a function that is attempting to set a value.

HD_INVALID_OPERATION

The operation could not be performed.

HD_INVALID_INPUT_TYPE

The parameter or capability does not support the input type.

HD_BAD_HANDLE

The device handle passed into an operation is not valid.

HD_WARM_MOTORS

Device Warning: One or more of the device motors are warm. Wait until the
motors cool before commanding forces again.

HD_EXCEEDED_MAX_FORCE

Device warning: Device exceeded the maximum force limit.

HD_EXCEEDED_MAX_FORCE_IMPULSE

Device warning: Change in force magnitude and direction exceeds the maximum
force impulse limit.

HD_EXCEEDED_MAX_VELOCITY

Device warning: Device exceeded the maximum velocity limit.

HD_FORCE_ERROR

The device experienced an error in sending forces because forces of incompatible
types such as DAC and Cartesian were commanded simultaneously.

HD_DEVICE_FAULT

Device fault. Check that the device is connected properly and activated.

HD_DEVICE_ALREADY_INITIATED

The device name was already initialized.

HD_COMM_ERROR

Communication Error: Check the device connection and configuration.

HD_COMM_CONFIG_ERROR

Configuration Error: Check the base address and port/adapter number. Consult
the appropriate device drivers documentation.

HD_TIMER_ERROR

Unable to start or maintain the servo loop timer.

HD_ILLEGAL_BEGIN
HD_ILLEGAL_END
HD_FRAME_ERROR
HD_INVALID_PRIORITY

hdBeginFrame() for a device was called when already in that device’s frame, or
more than once during a single servo loop tick.
hdEndFrame() for a device was called without a matching hdBeginFrame() for
that device beforehand.
A function that is restricted to being called within a frame was called outside of
one.
The priority for a scheduler callback does not fall within the proper numerical
bounds defined by MIN and MAX scheduler priority.

HD_SCHEDULER_FULL

The scheduler has reached its limit of callbacks and cannot add the new callback.

HD_INVALID_LICENSE

The required license is invalid or missing.

3D Systems, Inc.

62

21 20HAPTIC LIBRARY API PARAMETERS
The following pages contain tables that list the names of the HLAPI parameters. For each parameter the table lists a description.
The parameters are grouped as follows:
Topic
State Maintenance Parameter
Shape Parameters
Material and Surface Parameters
Force Effect Parameters
Callback Parameters
Event Parameters
Proxy Parameters
Transform Parameters

Page
page 63
page 66
page 68
page 69
page 71
page 71
page 72
page 72

State Maintenance Parameters
Table B-1: hlGetBooleanv, hlGetIntegerv, hlGetDoublev
Parameter Name
HL_BUTTON1_STATE
HL_BUTTON2_STATE
HL_SAFETY_STATE
HL_INKWELL_STATE
HL_DEPTH_OF_PENETRATION
HL_DEVICE_FORCE
HL_DEVICE_POSITION
HL_DEVICE_ROTATION
HL_DEVICE_TORQUE
HL_DEVICE_TRANSFORM
HL_EVENT_MOTION_ANGULAR_
TOLERANCE
HL_EVENT_MOTION_LINEAR_
TOLERANCE

HL_GOLDEN_POSITION

3D Systems, Inc.

Description
Single Boolean value representing the first button on the haptic device. A value of true
means that the button is depressed.
Single Boolean value representing the second button on the haptic device. A value of true
means that the button is depressed.
Single Boolean value representing the safety switch on the haptic device, if on exists. A
value of true means that the switch is depressed.
Single Boolean value representing the inkwell switch on the haptic device, if on exists. A
value of true means that the switch is depressed.
Double precision value representing the depth of the penetration of the device in world
coordinates. This will return the depth of penetration for the current object being touched
by the proxy.
Vector of 3 doubles representing the last force, in world coordinates, sent to the haptic
device.
Vector of 3 doubles representing the position of the haptic device in world coordinates.
Vector of 4 doubles representing a quaternion that specifies the rotation of the haptic
device in world coordinates.
Vector of 3 doubles representing the last torque, in world coordinates, sent to the haptic
device.
Vector of 16 doubles representing a 4x4 transform matrix in column major order that
specifies the transform of the haptic device relative to world coordinates.
Double precision value representing the minimum rotation, in radians, that the proxy must
move before a motion event is triggered.
Double precision value representing the minimum distance, in device workspace
coordinates, that the proxy must move before a motion event is triggered.
A vector of 3 doubles representing the golden sphere center position in world coordinates.
The golden sphere is a bounding volume for the proxy and designates the space of
allowed proxy movement for a particular HL frame. The client is responsible for providing
geometry within this bounding volume. Typically, this bounding volume gets used for sizing
the graphic view volume when the haptic camera view is enabled. The adaptive viewport
optimization also references this golden sphere for determining how much of the depth
buffer to read back. Additionally, the golden sphere can be useful when implementing a
callback shape or performing bounding volume culling. The radius of the sphere may be
queried using HL_GOLDEN_RADIUS.

63

Parameter Name

HL_GOLDEN_RADIUS

HL_MODELVIEW

HL_PROXY_IS_TOUCHING
HL_PROXY_POSITION
HL_PROXY_ROTATION
HL_TOUCHABLE_FACE

HL_PROXY_TOUCH_NORMAL
HL_PROXY_TRANSFORM
HL_TOUCHWORKSPACE_MATRIX
HL_VIEWTOUCH

3D Systems, Inc.

Description
Double precision value representing the radius of the golden sphere in world coordinates.
The golden sphere is a bounding volume for the proxy and designates the space of
allowed proxy movement for a particular HL frame. The client is responsible for providing
geometry within this bounding volume. Typically, this bounding volume gets used for sizing
the graphic view volume when the haptic camera view is enabled. The adaptive viewport
optimization also references this golden sphere for determining how much of the depth
buffer to read back. Additionally, the golden sphere can be useful when implementing a
callback shape or performing bounding volume culling. The center of the sphere may be
queried using HL_GOLDEN_POSITION.
Array of sixteen doubles representing a 4x4 transform matrix in column major order that
specifies the transform from model coordinates to view coordinates. This matrix is only
applied when not using the OpenGL modelview (when
HL_USE_GL_MODELVIEW is disabled). When the OpenGL modelview is used, you
should use OpenGL functions to query the modelview matrix.
Single Boolean value set to true when the proxy is in contact with one or more shapes.
Vector of 3 doubles representing the position of the proxy in world coordinates.
Vector of 4 doubles representing a quaternion that specifies the rotation of the proxy in
world coordinates.
Get the touchable face for the model, which represents which side of the model can be
felt. See “Table B-10: hlMaterialf - face values” for a list of return values.
Gets the integer touch type, which represents how the proxy interacts with the model. See
“Table B-15: hlTouchModel” for a list of return values.
A vector of 3 doubles representing the surface normal at the point of contact with the set
of shapes in contact with the proxy. Only valid if
HL_PROXY_IS_TOUCHING is true.
Vector of 16 doubles representing a 4x4 transform matrix in column major order that
specifies the transform of the proxy relative to world coordinates
Array of sixteen doubles representing a 4x4 transform matrix in column major order that
specifies the transform from touch coordinates to workspace coordinates.
Array of sixteen doubles representing a 4x4 transform matrix in column major order that
specifies the transform from view coordinates to touch coordinates.

64

Table B-2: hlCacheGetBooleanv, hlCacheGetDoublev
Parameter Name
HL_BUTTON1_STATE
HL_BUTTON2_STATE
HL_SAFETY_STATE
HL_INKWELL_STATE
HL_DEVICE_FORCE
HL_DEVICE_POSITION
HL_DEVICE_ROTATION
HL_DEVICE_TORQUE
HL_DEVICE_TRANSFORM
HL_PROXY_IS_TOUCHING
HL_PROXY_POSITION
HL_PROXY_ROTATION
HL_PROXY_TOUCH_NORMAL
HL_PROXY_TRANSFORM

Description
Single Boolean value representing the first button on the haptic device. A value of true
means that the button is depressed.
Single Boolean value representing the second button on the haptic device. A value of true
means that the button is depressed.
Single Boolean value representing the safety switch on the haptic device, if on exists. A
value of true means that the switch is depressed.
Single Boolean value representing the inkwell switch on the haptic device, if on exists. A
value of true means that the switch is depressed.
Vector of 3 doubles representing the last force, in world coordinates, sent to the haptic
device.
Vector of 3 doubles representing the position of the haptic device in world coordinates.
Vector of 4 doubles representing a quaternion that specifies the rotation of the haptic
device in world coordinates.
Vector of 3 doubles representing the last torque, in world coordinates, sent to the haptic
device.
Vector of 16 doubles representing a 4x4 transform matrix in column major order that
specifies the transform of the haptic device relative to world coordinates.
Single Boolean value set to true when the proxy is in contact with one or more shapes.
Vector of 3 doubles representing the position of the proxy in world coordinates.
Vector of 4 doubles representing a quaternion that specifies the rotation of the proxy in
world coordinates.
A vector of 3 doubles representing the surface normal at the point of contact with the set of
shapes in contact with the proxy. Only valid if HL_PROXY_IS_TOUCHING is true.
Vector of 16 doubles representing a 4x4 transform matrix in column major order that
specifies the transform of the proxy relative to world coordinates.

Table B-3: hlGetError
Parameter Name

HL_DEVICE_ERROR

HL_INVALID_ENUM
HL_INVALID_OPERATION
HL_INVALID_VALUE
HL_NO_ERROR
HL_OUT_OF_MEMORY
HL_STACK_OVERFLOW
HL_STACK_UNDERFLOW

3D Systems, Inc.

Description
An error occurred with the haptic device. The errorInfo field of the HLerror struct will
contain a device specific error code. See hddefine.h for a list of device errors. This error
may be signaled even outside any API function calls if the device error is detected in the
haptic rendering engine running in a separate thread. The haptic device recovers in most
cases.
An invalid value for an enumerated type was passed to an API function. The function call
will have no effect other than to set the error.
An API function was called when the renderer was not in an appropriate state for that
function call. For example, hlBeginShape() was called outside an hlBeginFrame()/
hlEndFrame() pair, or hlBeginFrame() when no haptic rendering context was active. The
function call will have no effect other than to set the error.
A value passed to an API function is outside the valid range for that function. The function
call will have no effect other than to set the error.
No error. There were no errors from API function calls since the last time the error stack
was empty; the error stack can be empty if either no errors have ever occurred or all errors
have been already queried from the stack.
There is not enough memory to complete the last API function called. This function may
have partially completed leaving the haptic renderer in an undefined state.
An API function was called that would have caused an overflow of the matrix stack. The
function call will have no effect other than to set the error.
An API function was called that would have caused an underflow of the matrix stack, i.e.
a call to hlPopMatrix() when the stack is empty. The function call will have no effect other
than to set the error.

65

Table B-4: hlGetString
Parameter Name
HL_VENDOR
HL_VERSION

Description
Returns the name of the company responsible for the haptic renderer implementation.
Returns the version number of the haptic rendering library as a string of the form:
major_number.minor_number.build_number

Table B-5: hlHinti, hlHintb
Parameter Name
HL_SHAPE_DYNAMIC_SURFACE_
CHANGE
HL_SHAPE_FEEDBACK_BUFFER_
VERTICES

HL_SHAPE_PERSISTENCE

Description
A single Boolean value indicating whether or not shapes that follow should be treated as
dynamically changing surfaces. A value of true tells the haptic rendering engine to do extra
processing to ensure that the proxy does not fall through a dynamically changing surface.
A value of false tells the rendering engine to optimize haptic rendering for surfaces which
will not change.
A single integer value indicating to the haptic rendering engine approximately how many
vertices will be in the next feedback buffer shape so that it may reserve the correct amount
of memory.
A single boolean value indicating whether or not shapes that follow should persistent
beyond the current frame. A value of true tells the haptic renderer that the shape does not
need to be respecified during the next frame, but that it should be automatically included.
This is useful particularly for background objects, i.e. static objects that change rarely in the
scene, since those objects can just be specified once and left in the scene versus having
the scene recompute the object for each frame. To clear a persistent shape, set it as nonpersistent during any frame afterward.
LIMITATION: This feature will not work if HL_HAPTIC_CAMERA_VIEW is enabled.
NOTE: This is a minimally supported experimental feature for v2.0. It will most likely
be deprecated, removed, or replaced by alternate API command in the next release.

Shape Parameters
Table B-6: hlBegin Shape
Parameter Name
HL_SHAPE_CALLBACK

HL_SHAPE_DEPTH_BUFFER

HL_SHAPE_FEEDBACK_BUFFER

Description
Allows clients to create custom shapes not supported using the other shape types.
OpenGL commands are ignored for this shape type. No geometry is specified. Instead, the
current shape intersection and shape closest point callbacks are used for haptic rendering
of this shape.
OpenGL commands used following the hlBeginShape() call will generate an image in
the OpenGL depth buffer. When hlEndShape() is called, this image will be read out of
the depth buffer and sent to the haptic renderer. Any OpenGL commands that modify the
depth buffer may be used. Point and line constraints may not be specified using a depth
buffer shape.
OpenGL commands used following the hlBeginShape() call will generate a set of
geometric primitives (quads, triangles, points and lines) that will be sent to the OpenGL
feedback buffer. When hlEndShape() is called, these primitives will be read out of the
feedback buffer and sent to the haptic renderer. Feedback buffer shapes can be used to
specify triangles meshes as well as points and lines for constraints. For optimal memory
usage and performance, use hlHint() with
HL_SHAPE_FEEDBACK_BUFFER_VERTICES before hlBeginShape(), so that the size
of the feedback buffer may be optimally allocated.

Table B-7: hlGetShapeBooleanv, hlGetShapeDoublev
Parameter Name
HL_PROXY_IS_TOUCHING
HL_REACTION_FORCE

3D Systems, Inc.

Description
Single Boolean value. True means that the proxy is currently in contact with the shape.
Vector of 3 doubles representing the contribution of this shape to the overall reaction force
that was sent to the haptic device during the last frame. If the proxy was not in contact with
this shape last frame, this vector will be zero.

66

Table B-8: hlLocalFeature types
Parameter Name
HL_LOCAL_FEATURE_LINE
HL_LOCAL_FEATURE_PLANE
HL_LOCAL_FEATURE_POINT

Description
The local feature is a line segment whose start point and end point are given by the vectors
v1 and v2 respectively.
The local feature is a plane whose normal is given by the vector v1 and that passes
through the point v1.
The local feature is a single point whose position is given by the vector v.

Capability Parameters
Table B-9: hlEnable, hlDisable, hlIsEnabled
Parameter Name
HL_ADAPTIVE_VIEWPORT

HL_HAPTIC_CAMERA_VIEW

HL_PROXY_RESOLUTION
HL_USE_GL_MODELVIEW

3D Systems, Inc.

Description
If enabled, this feature serves as an optimization for single pass rendering of depth buffer
shapes. This feature adaptively sizes the read-back pixel dimensions of the viewport based
on the location and motion of the proxy. This feature is incompatible with haptic camera
view. This is disabled by default.
Enhances shape rendering by modifying the shape viewing transform based on the motion
of the proxy. This allows the user to feel depth buffer features that are occluded in the
primary camera view. The haptic camera view also serves as an optimization by sizing the
viewing volume and viewport so that the graphics pipeline only processes geometry that is
within a proximity to the proxy. This is disabled by default.
If enabled, use shape geometry to automatically update the proxy position. The computed
proxy position will be valid for all shapes specified each frame. If disabled, shapes will be
ignored and the proxy position will be set by the client program. This is enabled by default.
If enabled, apply the OpenGL model view matrix to all geometry for haptic rendering and
ignore the current HL_MODELVIEW setting. This should be disabled in HLAPI programs
that do not have a a valid OpenGL rendering context query. It is enabled by default.

67

Material and Surface Parameters
Table B-10: hlMaterialf - face values
Parameter Name
HL_FRONT
HL_BACK
HL_FRONT_AND_BACK
HL_POPTHROUGH

Description
Apply the material property only to the front face of shapes and to all faces of
constraints.
Apply the material property only to the back face of shapes and to all faces of
constraints.
Apply the material property to both front and back faces.
Popthrough controls the amount of force the user must apply to a shape before
the device pops through the shape to the other side. The larger the param value,
the higher the force required. A param value of o disables popthrough.

Table B-11: hlMaterialf - pname values
Parameter Name
HL_STIFFNESS
HL_DAMPING

HL_STATIC_FRICTION

HL_DYNAMIC_FRICTION

Description
Stiffness controls how hard surfaces feel. Param must be a value between 0
and 1 where 1 represents the hardest surface the haptic device is capable of
rendering and 0 represents the most compliant surface that can be rendered.
Damping reduces the springiness of the surface. Param must be between 0 and 1
where 0 represents no damping, i.e. a highly springy surface and 1 represents the
maximum level of damping possible
Static friction controls the resistance of a surface to tangential motion when the
proxy position is not changing i.e. how hard it is to slide along the surface starting
from a complete stop. A param value of 0 is a completely frictionless surface and
a value of 1 is the maximum amount of static friction the haptic device is capable
of rendering.
Dynamic friction controls the resistance of a surface to tangential motion when
the proxy position is changing i.e. how hard it is to slide along the surface once
already moving. A param value of 0 is a completely frictionless surface and a
value of 1 is the maximum amount of dynamic friction the haptic device is capable
of rendering.

Table B-12: hlGetMaterialfv - face values
Parameter Name

Description

HL_FRONT
HL_BACK

Query the material property of the front face of shapes and all constraints.
Query the material property of the back face of shapes and all constraints.

Table B-13: hlGetMaterialfv - pname values
Parameter Name
HL_STIFFNESS
HL_DAMPING

HL_STATIC_FRICTION

HL_DYNAMIC_FRICTION

3D Systems, Inc.

Description
Stiffness controls how hard surfaces feel. Param must be a value between 0
and 1 where 1 represents the hardest surface the haptic device is capable of
rendering and 0 represents the most compliant surface that can be rendered.
Damping reduces the springiness of the surface. Param must be between 0 and 1
where 0 represents no damping, i.e. a highly springy surface and 1 represents the
maximum level of damping possible.
Static friction controls the resistance of a surface to tangential motion when the
proxy position is not changing i.e. how hard it is to slide along the surface starting
from a complete stop. A param value of 0 is a completely frictionless surface and
a value of 1 is the maximum amount of static friction the haptic device is capable
of rendering.
Dynamic friction controls the resistance of a surface to tangential motion when
the proxy position is changing i.e. how hard it is to slide along the surface once
already moving. A param value of 0 is a completely frictionless surface and a
value of 1 is the maximum amount of dynamic friction the haptic device is capable
of rendering.

68

Parameter Name

Description

HL_POPTHROUGH

Popthrough controls the amount of force the user must apply to a shape before
the device pops through the shape to the other side. The larger the param value,
the higher the force required. Param must be between 0 and 1 where a value of 0
disables popthrough.

Table B-14: hlTouchableFace - mode values
Parameter Name

Description

HL_FRONT
HL_BACK
HL_FRONT_AND_BACK

Only front faces will be touchable.
Only back faces will be touchable.
All faces, both front and back, will be touchable.

Table B-15: hlTouchModel
Parameter Name
HL_CONTACT
HL_CONSTRAINT

Description
The proxy position is not allowed to pass through geometric primitives (triangles).
The proxy may move off the surface but it will remain on one side of it.
The proxy position is constrained to remain exactly on the surface of geometric
primitives and it may only be moved off of the surface if the distance between the
device position and the proxy is greater than the snap distance.

Table B-16: hlTouchModelIf
Parameter Name

Description

HL_SNAP_DISTANCE

Distance between the proxy position and the surface that must be exceeded
to pull off a constraint. Param should be a floating point value representing the
distance in millimeters in workspace coordinates. The default value is FLT_MAX
to always be active.

Force Effect Parameters
Table B-17: hlStartEffect - effect types
Parameter Name
HL_EFFECT_CONSTANT

HL_EFFECT_SPRING

HL_EFFECT_VISCOUS

HL_EFFECT_FRICTION

3D Systems, Inc.

Description
Adds a constant force vector to the total force sent to the haptic device. The
effect property HL_EFFECT_PROPERTY_DIRECTION specifies the direction
of the force vector. The effect property HL_EFFECT_PROPERTY_MAGNITUDE
specifies the magnitude of the force vector.
Adds a spring force to the total force sent to the haptic device. The spring force
pulls the haptic device towards the effect position and is proportional to the
product of the gain and the distance between the effect position and the device
position. Specifically, the spring force is calculated using the expression F =
k(P-X) where F is the spring force, P is the effect position, X is the current haptic
device position and k is the gain. The effect position is specified by the property
HL_EFFECT_PROPERTY_POSITION. The gain is specified by the property
HL_EFFECT_PROPERTY_GAIN. The magnitude of the effect force is capped at
the value of the effect property HL_EFFECT_MAGNITUDE.
Adds a viscous force to the total force sent to the haptic device. The viscous
force is based on the current velocity of the haptic device and is calculated to
resist the motion of the haptic device. Specifically the force is calculated using
the expression F = -kV where f is the spring force, V is the velocity and k is the
gain. The gain is specified by the property HL_EFFECT_PROPERTY_GAIN.
The magnitude of the effect force is capped at the value of the effect property
HL_EFFECT_MAGNITUDE.
Adds a friction force to the total force sent to the haptic device. Unlike friction
specified via hlMaterial() calls, this is friction both while touching objects and in
free space. The gain of the friction force is specified by the property HL_EFFECT_
PROPERTY_GAIN. The magnitude of the effect force is capped at the value of
the effect property HL_EFFECT_MAGNITUDE.
69

Parameter Name
HL_EFFECT_CALLBACK

Description
Allows for the user to create a custom effect by setting effect callbacks using
hlCallback().

Table B-18: hlTriggerEffect
Parameter Name
HL_EFFECT_CONSTANT

HL_EFFECT_SPRING

HL_EFFECT_VISCOUS

HL_EFFECT_FRICTION

HL_EFFECT_CALLBACK

Description
Adds a constant force vector to the total force sent to the haptic device. The
effect property HL_EFFECT_PROPERTY_DIRECTION specifies the direction
of the force vector. The effect property HL_EFFECT_PROPERTY_MAGNITUDE
specifies the magnitude of the force vector.
Adds a spring force to the total force sent to the haptic device. The spring force
pulls the haptic device towards the effect position and is proportional to the
product of the gain and the distance between the effect position and the device
position. Specifically, the spring force is calculated using the expression F =
k(P-X) where F is the spring force, P is the effect position, X is the current haptic
device position and k is the gain. The effect position is specified by the property
HL_EFFECT_PROPERTY_POSITION. The gain is specified by the property
HL_EFFECT_PROPERTY_GAIN. The magnitude of the effect force is capped at
the value of the effect property HL_EFFECT_MAGNITUDE.
Adds a viscous force to the total force sent to the haptic device. The viscous
force is based on the current velocity of the haptic device and is calculated to
resist the motion of the haptic device. Specifically the force is calculated using
the expression F = -kV where f is the spring force, V is the velocity and k is the
gain. The gain is specified by the property HL_EFFECT_PROPERTY_GAIN.
The magnitude of the effect force is capped at the value of the effect property
HL_EFFECT_MAGNITUDE.
Adds a friction force to the total force sent to the haptic device. Unlike friction
specified via hlMaterial() calls, this is friction both while touching objects and in
free space. The gain of the friction force is specified by the property HL_EFFECT_
PROPERTY_GAIN. The magnitude of the effect force is capped at the value of
the effect property HL_EFFECT_MAGNITUDE.
Allows for the user to create a custom effect by setting effect callbacks using
hlCallback().

Table B-19: hlEffectd, hlEffecti, hlEffectdv, hlEffectiv
Parameter Name
HL_EFFECT_PROPERTY_GAIN
HL_EFFECT_PROPERTY_MAGNITUDE
HL_EFFECT_PROPERTY_FREQUENCY
HL_EFFECT_PROPERTY_DURATION
HL_EFFECT_PROPERTY_POSITION
HL_EFFECT_PROPERTY_DIRECTION

Description
Used by spring, friction and viscous effect types. Higher gains will cause these
effects to generate larger forces.
Used by constant, spring, friction and viscous effect types. Represents a cap on
the maximum force generated by these effects.
Reserved for use by future effect types and callback effects.
Used for all effects started with a call to hlTriggerEffect(). The effect will
automatically be terminated when the duration has elapsed. Duration is specified
in milliseconds.
Used by spring effect. Represents the anchor position of the spring.
Used by constant effect. Represents direction of constant force vector.

Table B-20: hlEffectd, hlEffecti, hlEffectdv, hlEffectiv
Parameter Name
HL_EFFECT_PROPERTY_GAIN
HL_EFFECT_PROPERTY_MAGNITUDE
HL_EFFECT_PROPERTY_FREQUENCY
HL_EFFECT_PROPERTY_DURATION
HL_EFFECT_PROPERTY_POSITION
HL_EFFECT_PROPERTY_DIRECTION
3D Systems, Inc.

Description
Used by spring, friction and viscous effect types. Higher gains will cause these
effects to generate larger forces.
Used by constant, spring, friction and viscous effect types. Represents a cap on
the maximum force generated by these effects.
Reserved for use by future effect types and callback effects.
Used for all effects started with a call to hlTriggerEffect(). The effect will
automatically be terminated when the duration has elapsed. Duration is specified
in milliseconds.
Used by spring effect. Represents the anchor position of the spring.
Used by constant effect. Represents direction of constant force vector.
70

Parameter Name
HL_EFFECT_PROPERTY_ACTIVE
HL_EFFECT_PROPERTY_TYPE

Description
Used by all effects. Indicates whether the effect is currently running, i.e. has been
started via hlStartEffect().
Used by all effect. Represents the type of effect, such as HL_EFFECT_
CALLBACK, HL_EFFECT_SPRING.

Callback Parameters
Table B-21: hlCallback
Parameter Name

Description
Callback to intersect a line segment with a user defined custom shape. The
callback function must have the following signature:
HLboolean HLCALLBACK fn(const HLdouble startPt[3],
const HLdouble endPt[3], HLdouble intersectionPt[3],
HLdouble intersectionNormal[3], void *userdata)

HL_SHAPE_INTERSECT_LS

Where input parameters startPt and endPt are the endpoints of a line segment
to intersect with the custom shape, intersectionPt is used to return the point
of intersection of the line segment with the shape. In the case of multiple
intersections, intersectionPt should be the closest intersection to startPt.
IntersectionNormal is the surface normal of the custom shape at intersectionPt.
Userdata is the same userdata pointer passed to hlCallback(). The callback
function should return true if the line segment intersects the shape. All data is in
the local coordinate system of the custom shape.
Callback to find the closest point on the surface to an input point as well as one
ore more local features that approximate the surface in the vicinity of that point.
The callback function must have the following signature:
HLboolean HLCALLBACK fn(const HLdouble queryPt[3], const HLdouble
targetPt[3],

HL_SHAPE_CLOSEST_FEATURES

HLgeom *geom, HLdouble closestPt[3], void* userdata)
Where closest point should be set to the closest point on the surface of the
custom shape closest to the input parameter queryPt. Normal is the surface
normal of the custom shape at closestPt. Userdata is the same userdata pointer
passed to hlCallback(). All data is in the local coordinate system of the custom
shape.

Event Parameters
Table B-22: hlAddEventCallback, hlRemoveEventCallBack - event values
Parameter Name

HL_EVENT_MOTION

HL_EVENT_1BUTTONDOWN
HL_EVENT_1BUTTONUP
HL_EVENT_2BUTTONDOWN
HL_EVENT_2BUTTONUP
HL_EVENT_SAFETYDOWN
HL_EVENT_SAFETYUP
HL_EVENT_INKWELLDOWN
HL_EVENT_INKWELL_UP
HL_EVENT_TOUCH
3D Systems, Inc.

Description
Callback will be called when either the proxy has moved more than the
HL_EVENT_MOTION_LINEAR_TOLERANCE millimeters in workspace
coordinates from the position when the last motion event was triggered or when
the proxy has been rotated more than HL_EVENT_MOTION_ANGULAR_
TOLERANCE radians from the rotation of the proxy last time a motion event was
triggered.
Callback will be called when the first button on the haptic device is depressed.
Callback will be called when the first button on the haptic device is released.
Callback will be called when the second button on the haptic device is depressed.
Callback will be called when the second button on the haptic device is released.
Callback will be called when the safety switch, if available, is depressed.
Callback will be called when the safety switch, if available, is released.
Callback will be called when the inkwell switch, if available, is depressed.
Callback will be called when the inkwell switch, if available, is released.
Callback will be called when a shape in the scene has been touched (the proxy is
in contact with the shape).
71

Table B-23: hlAddEventCallback, hlRemoveEventCallback - thread values
Parameter Name
HL_CLIENT_THREAD
HL_COLLISION_THREAD

Description
Callback function will be called from client thread, when the client program calls
hlCheckEvents().
Callback function will be called from the internal collision thread running in the
haptic rendering engine. Most event callbacks should be handled in the client
thread, however there are some cases where collision thread callbacks are
needed due to timing requirements.

Table B-24: hlEventd - pname values
Parameter Name

Description
Sets the minimum distance in device workspace coordinates, that the linear
HL_EVENT_MOTION_LINEAR_TOLERANCE
translation of the proxy must change before a motion event is triggered. By default
this value is one millimeter.
Sets the minimum angular distance in, that orientation of the proxy must change
HL_EVENT_MOTION_ANGULAR_TOLERANCE
before a motion event is triggered. By default this value is 0.02 radians.

Proxy Parameters
Table B-25: hlProxydv
Parameter Name
HL_PROXY_POSITION

Description
Sets the position of the proxy in world coordinates. If proxy resolution is enabled,
this call will have no effect.

Transform Parameters
Table B-26: hlMatrix - mode values
Parameter Name
HL_VIEWTOUCH
HL_TOUCHWORKSPACE
HL_MODELVIEW

Description
All matrix manipulation commands will target the transform from view coordinates
to touch coordinates.
All matrix manipulation commands will target the transform from touch coordinates
to the local coordinates of the haptic device.
All matrix manipulation commands will target the transform from model
coordinates to view coordinates. The HL_MODELVIEW is only applied when
HL_USE_GL_MODELVIEW is disabled, otherwise the OpenGL modelview matrix
is used.

Table B-27: hlPushAttrib, hlPopAttrib
Parameter Name
HL_HINT_BIT
HL_MATERIAL_BIT
HL_TOUCH_BIT
HL_TRANSFORM_BIT
HL_EFFECT_BIT
HL_EVENTS_BIT

3D Systems, Inc.

Description
Affects all properties that are set by hlInt() command such as
HL_SHAPE_FEEDBACK_BUFFER.
Affects all properties that are specified by hlMaterial() commands such as
HL_STIFFNESS, HL_DYNAMIC_FRICTION.
Affects all properties that are specified by hlTouch() commands, such as
HL_SNAP_DISTANCE, HL_TOUCH_MODEL.
Affects all transform and camera attributes, such as HL_HAPTIC_CAMERA_
VIEW, HL_ADAPTIVE_VIEWPORT.
Affects all properties that are specified by hlEffect() commands, such as
HL_EFFECT_PROPERTY_GAIN, HL_EFFECT_PROPERTY_DURATION.
Affects all properties that are specified by event commands, such as HL_
EVENT_MOTION_LINEAR_THRESHOLD, HL_EVENT_MOTION_ANGULAR_
TOLERANCE.

72

Table B-28: Calibration Event Types
Parameter Name
HL_EVENT_CALIBRATION_UPDATE
HL_EVENT_CALIBRATION_INPUT

3D Systems, Inc.

Description
Triggers when valid calibration data has been found.
Triggers when the device requires user input, such as inserting the stylus into the
inkwell.

73

3D Systems, Inc.
333 Three D Systems Circle | Rock Hill, SC | 29730
www.3dsystems.com
©2014 3D Systems, Inc. All rights reserved.
The 3D Systems logo, 3D Systems, Geomagic and Geomagic
Product are registered trademarks of 3D Systems, Inc .
pn 391572-00Rev. A



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.7
Linearized                      : Yes
Tagged PDF                      : Yes
XMP Toolkit                     : Adobe XMP Core 5.6-c067 79.157747, 2015/03/30-23:40:42
Create Date                     : 2015:06:17 16:31:29-04:00
Metadata Date                   : 2015:06:17 16:31:38-04:00
Modify Date                     : 2015:06:17 16:31:38-04:00
Creator Tool                    : Adobe InDesign CC 2015 (Windows)
Instance ID                     : uuid:713c411e-1826-451a-b219-c6d7ad3ca87f
Original Document ID            : xmp.did:6f05dc00-8fb8-5642-a823-875f372c84ea
Document ID                     : xmp.id:82ca6e32-f3cf-7743-9d6a-379d1203fd54
Rendition Class                 : proof:pdf
Derived From Instance ID        : xmp.iid:8f105728-56c2-1c48-9cdd-8f4cf00dce80
Derived From Document ID        : xmp.did:d7fcdbfb-bdf3-f84d-9ed2-216d71b9e2e4
Derived From Original Document ID: xmp.did:6f05dc00-8fb8-5642-a823-875f372c84ea
Derived From Rendition Class    : default
History Action                  : converted
History Parameters              : from application/x-indesign to application/pdf
History Software Agent          : Adobe InDesign CC 2015 (Windows)
History Changed                 : /
History When                    : 2015:06:17 16:31:29-04:00
Format                          : application/pdf
Producer                        : Adobe PDF Library 15.0
Trapped                         : False
Page Count                      : 75
Creator                         : Adobe InDesign CC 2015 (Windows)

EXIF Metadata provided by EXIF.tools