Hdal Api
Hdal Api
Hdal Api
API Reference
VERSION 2.1.3
August 14, 2008
-1-
Copyright Notice
2005-2008. Novint Technologies, Inc. All rights reserved. Printed in the USA. Except as permitted by license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means electronic, mechanical, recording or otherwise, without prior written consent of Novint Technologies.
Trademarks
Novint, Novint Technologies, e-Touch, Falcon, and HDAL are trademarks or registered trademarks of Novint Technologies, Inc. Other brand and product names are trademarks of their respective holders.
Questions or Comments
If you have any questions for our technical support staff, please contact us at support@novint.com. You can also phone 1-866-298-4420. If you have any questions or comments about the documentation, please contact us at support@novint.com.
Corporate Headquarters
Novint Technologies, Inc. PO Box 66956 Albuquerque, NM 87193 Phone: 1-866-298-4420 E-mail: support@novint.com Internet: http://www.novint.com
-2-
Preface
This manual is a reference to the Haptic Device Abstraction Layer produced by Novint Technologies. It contains reference pages to all the HDAL API functions, constants, and types. This manual was current as of the release of the corresponding version of HDAL. The technical content of this document was mechanically generated from HDAL source code by Doxygen, a general-purpose utility for documenting C and C++ code. For more information on Doxygen, see http://www.doxygen.org. .
-3-
Table of Contents
Preface................................................................................................................................. 3 Table of Contents ................................................................................................................ 4 Overview ............................................................................................................................. 5 Files ................................................................................................................................. 5 Units ................................................................................................................................ 5 Coordinate Frame............................................................................................................ 5 HDAL Reference ................................................................................................................ 6 include/hdl/hdl.h File Reference ..................................................................................... 6 Defines ........................................................................................................................ 6 Typedefs ...................................................................................................................... 7 Functions ..................................................................................................................... 7 Detailed Description ................................................................................................... 9 Typedef Documentation.............................................................................................. 9 Function Documentation ............................................................................................. 9 include/hdl/hdlConstants.h File Reference ................................................................... 16 Defines ...................................................................................................................... 16 Typedefs .................................................................................................................... 16 Enumerations ............................................................................................................ 17 Detailed Description ................................................................................................. 17 Typedef Documentation............................................................................................ 17 Enumeration Type Documentation ........................................................................... 17 include/hdl/hdlErrors.h File Reference ......................................................................... 17 Defines ...................................................................................................................... 17 Typedefs .................................................................................................................... 18 Detailed Description ................................................................................................. 19 Typedef Documentation............................................................................................ 19 include/hdlu/hdlu.h File Reference ............................................................................... 19 Functions ................................................................................................................... 19 Detailed Description ................................................................................................. 19 Function Documentation ........................................................................................... 19 HDAL API Page Documentation...................................................................................... 20 Deprecated List ............................................................................................................. 20 Index ................................................................................................................................. 21
-4-
Overview
Files
The HDAL API is represented in two files. include\hdl\hdl.h is the primary interface to HDALs functionality. It is complete, in that entire applications can be built from it. include\hdlu\hdlu.h is a utility interface, presenting functions that may be useful to the developer. HDAL can be used effectively without these utility interface functions.
Units
The units of measure for the HDAL interface are: Distance meters Force newtons Time seconds The nominal cycle time is approximately one millisecond. However, since operating systems are not able to control intervals with precision adequate to many applications, a more precise time measure may be needed. For precise time calculations, the application should use some precision clock, such as the Windows QueryPerformanceCounter function.
Coordinate Frame
The coordinate system used by HDAL is a right hand coordinate system: X increases to the right Y increases upward Z increases toward the user. The origin (X = 0, Y = 0, Z = 0) is approximately at the center of the device workspace.
-5-
HDAL Reference
include/hdl/hdl.h File Reference
Main API for HDAL services. #include <hdl/hdlExports.h> #include <hdl/hdlErrors.h> #include <hdl/hdlConstants.h>
Defines
#define false 0 #define HDAL_ISREADY 0
-6-
#define HDL_SERVOOP_CONTINUE 1
Typedefs
typedef unsigned char bool
define bool type and values for C programmers to use with certain functions
typedef int HDLDeviceHandle
Functions
HDLAPI __int64 HDLAPIENTRY HDL_BUILD_VERSION (HDL_VERSION_INFO_TYPE versionInfo)
-7-
Make a specific haptic device current (Allows application to send forces to a specific device).
HDLAPI void HDLAPIENTRY hdlSetToolForce (double force[3])
-8-
Detailed Description
Main API for HDAL services. Copyright 2005-2008 Novint Technologies, Inc. All rights reserved. Available only under license from Novint Technologies, Inc. Haptic Device Abstraction Layer Low level, cross-platform, general purpose interface.
Handle to differentiate between multiple installed devices. Handle is an abstraction returned by the initialization routine.
Definition at line 46 of file hdl.h.typedef HDLServoOpExitCode __cdecl HDLServoOp(void *pParam)
-9-
See also: hdlGetVersion(). Errors: None. HDLAPI int HDLAPIENTRY HDL_MAJOR_VERSION (HDL_VERSION_INFO_TYPE versionInfo)
Schedule an operation (callback) to run in the servo loop. Operation is either blocking (client waits until completion) or non-blocking (client continues execution).
Parameters: pServoOp Pointer to servo operation function pParam Pointer to data for servo operation function bBlocking Flag to indicate whether servo loop blocks
- 10 -
Returns: Handle to servo operation entry Errors: None See also: hdlDestroyServoOp, hdlInitNamedDevice, hdlInitIndexedDevice HDLAPI void HDLAPIENTRY hdlDestroyServoOp (HDLOpHandle hServoOp)
Retrieve the workspace of the device, measured in meters. Call this function to retrieve the workspace of the current device. Since not all devices have the same physical workspace dimensions, the application must account for different device workspaces. The workspace is defined in the device reference coordinate frame. It is up to the user to transform positions in this coordinate frame into the application's coordinate frame. See hdluGenerateHapticToAppWorkspaceTransform for a utility function to assist in this. Dimension order: minx, miny, minz, maxx, maxy, maxy (left, bottom, far, right, top, near) (minx, miny, minz) are the coordinates of the left-bottom-far corner of the device workspace. (maxx, maxy, maxz) are the coordinates of the right-top-near corner of the device workspace.
Parameters: workspaceDimensions See explanation above. Returns: Nothing Errors: manufacturer specific
- 11 -
- 12 -
Parameters: deviceID ID of haptic device Returns: Handle to haptic device Errors: manufacturer specific could not load device specific dll Deprecated: Only supports a single device, deviceID is ignored. Included to support older apps. Use hdlInitNamedDevice instead. See also: hdlInitNamedDevice HDLAPI HDLDeviceHandle HDLAPIENTRY hdlInitIndexedDevice (const int index, const char * configPath)
Teardown sequence:
hdlDestroyServoOp(...); hdlStop(); hdlUninitDevice(...);
See also: hdlInitNamedDevice, hdlStart, hdlStop, hdlCreateServoOp, hdlDestroyServoOp, hdlUninitDevice Note: In C++ programs, configPath is optional, with a default value of (const char *) 0. C programs must pass (const char *) 0 to use default configPath HDLAPI HDLDeviceHandle HDLAPIENTRY hdlInitNamedDevice (const char * deviceName, const char * configPath)
- 13 -
Parameters: deviceName Name of haptic device. configPath Path/file for ini file. configPath search order: 1. relative to executable directory 2. relative to executable directory's parent if executable directory is Debug or Release 3. config directory in path specified by NOVINT_DEVICE_SUPPORT Returns: Handle to haptic device Errors: manufacturer specific could not load device specific dll Note: Support multiple devices via deviceName string. Setup sequence:
hdlInitNamedDevice(...); hdlStart(); hdlCreateServoOp(...);
Teardown sequence:
hdlDestroyServoOp(...); hdlStop(); hdlUninitDevice(...);
See also: hdlInitIndexedDevice, hdlStart, hdlStop, hdlCreateServoOp, hdlDestroyServoOp, hdlUninitDevice Note: In C++ programs, configPath is optional, with a default value of (const char *) 0. C programs must pass (const char *) 0 to use default configPath HDLAPI void HDLAPIENTRY hdlMakeCurrent (HDLDeviceHandle hHandle)
Make a specific haptic device current (Allows application to send forces to a specific device).
Parameters: hHandle Haptic device handle Returns: Nothing Errors: manufacturer specific hHandle invalid HDLAPI void HDLAPIENTRY hdlSetToolForce (double force[3])
Set the force to be generated by the device, measured in newtons. Forces are in device coordinates. Dimension order: x, y, z
Parameters: force Measured in Newtons; x, y, z order Returns: Nothing Errors: manufacturer specific no current device
- 14 -
Return current state of tool button(s). For multi-button devices, if any button is pressed, pButton* is set to true.
Parameters: pButton Pointer to bool to hold button state Returns: Nothing Errors: None HDLAPI void HDLAPIENTRY hdlToolButtons (int * pButton)
Return current state of tool buttons. Returned value is a bitmask of buttons, with the least significant bit associated with button "0".
Parameters: pButton Pointer to an int to hold button states
- 15 -
Returns: Nothing Errors: None HDLAPI void HDLAPIENTRY hdlToolPosition (double position[3])
Defines
#define HDL_VERSION_INVALID -1
vesion is invalid
#define HDL_VERSION_NOT_APPLICABLE -2
Typedefs
typedef __int64 HDL_VERSION_INFO_TYPE
- 16 -
Enumerations
enum HDL_VERSION_REQUEST { HDL_HDAL = 0x11, HDL_DEVICE = 0x21, HDL_DEVICE_SDK = 0x22, HDL_DEVICE_COMMS = 0x23, HDL_DEVICE_OS = 0x24, HDL_GRIP = 0x33 }
Detailed Description
Constants for HDAL. Copyright 2005-2008 Novint Technologies, Inc. All rights reserved. Available only under license from Novint Technologies, Inc.
HDL_HDAL version of HDAL HDL_DEVICE device hardware in current device context HDL_DEVICE_SDK SDK version of current device. HDL_DEVICE_COMMS communications version of current device HDL_DEVICE_OS version of device OS HDL_GRIP grip in current device context
Defines
#define HDL_ERROR_INIT_FAILED 0x10
- 17 -
Typedefs
typedef int HDLError
- 18 -
Detailed Description
Error codes returned from HDAL. Copyright 2005-2008 Novint Technologies, Inc. All rights reserved. Available only under license from Novint Technologies, Inc.
HDAL API Errors. Client application queries HDAL errors using hdlGetError(). hdlGetError() returns an error type.
Definition at line 19 of file hdlErrors.h.
Functions
HDLAPI void HDLAPIENTRY hdluGenerateHapticToAppWorkspaceTransform (double hapticWorkspace[6], double gameWorkspace[6], bool useUniformScale, double tranformMat[16])
Detailed Description
Utility functions for HDAL applications. Copyright 2005-2008 Novint Technologies, Inc. All rights reserved. Available only under license from Novint Technologies, Inc. Haptic Device Abstraction Layer Low level, cross-platform, general purpose interface.
Generate transform for mapping between haptic and game workspace. Inputs specify the minimum and maximum coordinate values of rectangular paralleliped bounding boxes, measured in meters. The function computes and returns (in transformMat) the transform matrix that will convert the device position into workspace coordinates. See hdlDeviceWorkspace for the HDAL function to retrieve the device's workspace.
- 19 -
Parameters: hapticWorkspace minx, miny, minz, maxx, maxy, maxz gameWorkspace minx, miny, minz, maxx, maxy, maxz useUniformScale If true, scale uniformly across the workspace tranformMat Transformation from haptic to game workspace Returns: Nothing
Errors: None
HDLAPI double hdluGetSystemTime (void)
- 20 -
Index
hdl.h HDL_BUILD_VERSION, 9 HDL_MAJOR_VERSION, 10 HDL_MINOR_VERSION, 10 hdlCountDevices, 10 hdlCreateServoOp, 10 hdlDestroyServoOp, 11 HDLDeviceHandle, 9 hdlDeviceModel, 11 hdlDeviceWorkspace, 11 hdlGetError, 12 hdlGetState, 12 hdlGetVersion, 12 hdlInitDevice, 12 hdlInitIndexedDevice, 13 hdlInitNamedDevice, 13 hdlMakeCurrent, 14 HDLServoOp, 9 hdlSetToolForce, 14 hdlStart, 15 hdlStop, 15 hdlToolButton, 15 hdlToolButtons, 15 hdlToolPosition, 16 hdlUninitDevice, 16 HDL_BUILD_VERSION hdl.h, 9 HDL_DEVICE hdlConstants.h, 17 HDL_DEVICE_COMMS hdlConstants.h, 17 HDL_DEVICE_OS hdlConstants.h, 17 HDL_DEVICE_SDK hdlConstants.h, 17 HDL_GRIP hdlConstants.h, 17 HDL_HDAL hdlConstants.h, 17 HDL_MAJOR_VERSION hdl.h, 10 HDL_MINOR_VERSION hdl.h, 10 HDL_VERSION_INFO_TYPE hdlConstants.h, 17 HDL_VERSION_REQUEST hdlConstants.h, 17 hdlConstants.h HDL_DEVICE, 17 HDL_DEVICE_COMMS, 17 HDL_DEVICE_OS, 17 HDL_DEVICE_SDK, 17 HDL_GRIP, 17 HDL_HDAL, 17 HDL_VERSION_INFO_TYPE, 17 HDL_VERSION_REQUEST, 17 hdlCountDevices hdl.h, 10 hdlCreateServoOp hdl.h, 10 hdlDestroyServoOp hdl.h, 11 HDLDeviceHandle hdl.h, 9 hdlDeviceModel hdl.h, 11 hdlDeviceWorkspace hdl.h, 11 HDLError hdlErrors.h, 19 hdlErrors.h HDLError, 19 hdlGetError hdl.h, 12 hdlGetState hdl.h, 12 hdlGetVersion hdl.h, 12 hdlInitDevice hdl.h, 12 hdlInitIndexedDevice hdl.h, 13 hdlInitNamedDevice hdl.h, 13 hdlMakeCurrent hdl.h, 14 HDLServoOp hdl.h, 9 hdlSetToolForce hdl.h, 14 hdlStart hdl.h, 15 hdlStop hdl.h, 15 hdlToolButton hdl.h, 15 hdlToolButtons hdl.h, 15 hdlToolPosition hdl.h, 16 hdlu.h
- 21 -
- 22 -