ndicapi.h

Go to the documentation of this file.

/*=======================================================================

  Program:   NDI Combined API C Interface Library
  Module:    $RCSfile: ndicapi.h,v $
  Creator:   David Gobbi <dgobbi@atamai.com>
  Language:  C
  Author:    $Author: dgobbi $
  Date:      $Date: 2005/07/01 22:52:05 $
  Version:   $Revision: 1.5 $

==========================================================================

Copyright (c) 2000-2005 Atamai, Inc.

Use, modification and redistribution of the software, in source or
binary forms, are permitted provided that the following terms and
conditions are met:

1) Redistribution of the source code, in verbatim or modified
   form, must retain the above copyright notice, this license,
   the following disclaimer, and any notices that refer to this
   license and/or the following disclaimer.  

2) Redistribution in binary form must include the above copyright
   notice, a copy of this license and the following disclaimer
   in the documentation or with other materials provided with the
   distribution.

3) Modified copies of the source code must be clearly marked as such,
   and must not be misrepresented as verbatim copies of the source code.

THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS"
WITHOUT EXPRESSED OR IMPLIED WARRANTY INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  IN NO EVENT SHALL ANY COPYRIGHT HOLDER OR OTHER PARTY WHO MAY
MODIFY AND/OR REDISTRIBUTE THE SOFTWARE UNDER THE TERMS OF THIS LICENSE
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA OR DATA BECOMING INACCURATE
OR LOSS OF PROFIT OR BUSINESS INTERRUPTION) ARISING IN ANY WAY OUT OF
THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

=======================================================================*/

#ifndef NDICAPI_H
#define NDICAPI_H 1

#define NDICAPI_MAJOR_VERSION 3
#define NDICAPI_MINOR_VERSION 1

#include "ndicapi_serial.h"

#ifdef __cplusplus
extern "C" {
#endif

#include <stdarg.h>

struct ndicapi;
typedef struct ndicapi ndicapi;

/*=====================================================================*/
char *ndiDeviceName(int i);

int ndiProbe(const char *device);

ndicapi *ndiOpen(const char *device);

void ndiClose(ndicapi *pol);

void ndiSetThreadMode(ndicapi *pol, int mode);

char *ndiCommand(ndicapi *pol, const char *format, ...);

char *ndiCommandVA(ndicapi *pol, const char *format, va_list ap);

typedef void (*NDIErrorCallback)(int errnum, char *description, void *userdata);

void ndiSetErrorCallback(ndicapi *pol, NDIErrorCallback callback,
                         void *userdata);

/*=====================================================================*/
/*\{*/
#define ndi3D(p,ph,mode) ndiCommand((p),"3D:%02X%d",(ph),(mode))

#define ndiBEEP(p,n) ndiCommand((p),"BEEP:%i",(n))

#define ndiCOMM(p,baud,dps,h) ndiCommand((p),"COMM:%d%03d%d",(baud),(dps),(h))

#define ndiDSTART(p) ndiCommand((p),"DSTART:")

#define ndiDSTOP(p) ndiCommand((p),"DSTOP:")

#define ndiGX(p,mode) ndiCommand((p),"GX:%04X",(mode))

#define ndiINIT(p) ndiCommand((p),"INIT:")

#define ndiIRATE(p,rate) ndiCommand((p),"IRATE:%d",(rate))

#define ndiIRCHK(p,mode) ndiCommand((p),"IRCHK:%04X",(mode))

#define ndiIRED(p,ph,sig) ndiCommand((p),"IRED:%02X%08X",(ph),(sig))

#define ndiIRINIT(p) ndiCommand((p),"IRINIT:")

#define ndiLED(p,ph,led,s) ndiCommand((p),"LED:%02X%d%c",(ph),(led),(s))

#define ndiPDIS(p,ph) ndiCommand((p),"PDIS:%02X",(ph))

#define ndiPENA(p,ph,mode) ndiCommand((p),"PENA:%02X%c",(ph),(mode))

#define ndiPFSEL(p,ph,tf) ndiCommand((p),"PFSEL:%02X%02X",(ph),(tf))

#define ndiPHF(p,ph) ndiCommand((p),"PHF:%02X",(ph))

#define ndiPHINF(p,ph,format) ndiCommand((p),"PHINF:%02X%04X",(ph),(format))

#define ndiPHRQ(p,num,sys,tool,port,chan) ndiCommand((p),"PHRQ:%-8.8s%1.1s%1.1s%2.2s%2.2s",(num),(sys),(tool),(port),(chan))

#define ndiPHSR(p,mode) ndiCommand((p),"PHSR:%02X",(mode))

#define ndiPINIT(p,ph) ndiCommand((p),"PINIT:%02X",(ph))

#define ndiPPRD(p,ph,addr) ndiCommand((p),"PPRD:%02X%04X",(ph),(addr))

#define ndiPPWR(p,ph,a,x) ndiCommand((p),"PPWR:%02X%04X%.128s",(ph),(a),(x))

#define ndiPSEL(p,ph,id) ndiCommand((p),"PSEL:%02X%s",(ph),(id))

#define ndiPSOUT(p,ph,a,b,c) ndiCommand((p),"PSOUT:%02X%c%c%c",(ph),(a),(b),(c))

#define ndiPSRCH(p,ph) ndiCommand((p),"PSRCH:%02X",(ph))

#define ndiPSTAT(p,format) ndiCommand((p),"PSTAT:%04X",(format))

#define ndiPURD(p,ph,addr) ndiCommand((p),"PURD:%02X%04X",(ph),(addr))

#define ndiPUWR(p,ph,a,x) ndiCommand((p),"PPWR:%02X%04X%.128s",(ph),(a),(x))

#define ndiPVCLR(p,port) ndiCommand((p),"PVCLR:%c",(port))

#define ndiPVTIP(p,port,tip,np) ndiCommand((p),"PVTIP:%c%d%d",(port),(tip),(np))

#define ndiPVWR(p,ph,a,x) ndiCommand((p),"PVWR:%02X%04X%.128s",(ph),(a),(x))

#define ndiRESET(p) ndiCommand((p),NULL)

#define ndiSFLIST(p,mode) ndiCommand((p),"SFLIST:%02X",(mode))

#define ndiSSTAT(p,format) ndiCommand((p),"SSTAT:%04X",(format))

#define ndiTCTST(p,ph) ndiCommand((p),"TCTST:%02X",(ph))

#define ndiTSTART(p) ndiCommand((p),"TSTART:")

#define ndiTSTOP(p) ndiCommand((p),"TSTOP:")

#define ndiTTCFG(p,ph) ndiCommand((p),"TTCFG:%02X",(ph))

#define ndiTX(p,mode) ndiCommand((p),"TX:%04X",(mode))

#define ndiVER(p,n) ndiCommand((p),"VER:%d",(n))

#define ndiVSEL(p,n) ndiCommand((p),"VSEL:%d",(n))

int ndiPVWRFromFile(ndicapi *pol, int ph, char *filename);
/*\}*/

/*=====================================================================*/
int ndiGetError(ndicapi *pol);

char *ndiGetDeviceName(ndicapi *pol);

NDIFileHandle ndiGetDeviceHandle(ndicapi *pol);

int ndiGetThreadMode(ndicapi *pol);

NDIErrorCallback ndiGetErrorCallback(ndicapi *pol);

void *ndiGetErrorCallbackData(ndicapi *pol);

int ndiGetPHRQHandle(ndicapi *pol);

int ndiGetPHSRNumberOfHandles(ndicapi *pol);

int ndiGetPHSRHandle(ndicapi *pol, int i);

int ndiGetPHSRInformation(ndicapi *pol, int i);

int ndiGetPHINFPortStatus(ndicapi *pol);

int ndiGetPHINFToolInfo(ndicapi *pol, char information[31]);

unsigned long ndiGetPHINFCurrentTest(ndicapi *pol);

int ndiGetPHINFPartNumber(ndicapi *pol, char part[20]);

int ndiGetPHINFAccessories(ndicapi *pol);

int ndiGetPHINFMarkerType(ndicapi *pol);

int ndiGetPHINFPortLocation(ndicapi *pol, char location[14]);

int ndiGetPHINFGPIOStatus(ndicapi *pol);

int ndiGetTXTransform(ndicapi *pol, int ph, double transform[8]);

int ndiGetTXPortStatus(ndicapi *pol, int ph);

unsigned long ndiGetTXFrame(ndicapi *pol, int ph);

int ndiGetTXToolInfo(ndicapi *pol, int ph);

int ndiGetTXMarkerInfo(ndicapi *pol, int ph, int marker);

int ndiGetTXSingleStray(ndicapi *pol, int ph, double coord[3]);

int ndiGetTXNumberOfPassiveStrays(ndicapi *pol);

int ndiGetTXPassiveStray(ndicapi *pol, int i, double coord[3]);

int ndiGetTXSystemStatus(ndicapi *pol);

int ndiGetGXTransform(ndicapi *pol, int port, double transform[8]);

int ndiGetGXPortStatus(ndicapi *pol, int port);

int ndiGetGXSystemStatus(ndicapi *pol);

int ndiGetGXToolInfo(ndicapi *pol, int port);

int ndiGetGXMarkerInfo(ndicapi *pol, int port, int marker);

int ndiGetGXSingleStray(ndicapi *pol, int port, double coord[3]);

unsigned long ndiGetGXFrame(ndicapi *pol, int port);

int ndiGetGXNumberOfPassiveStrays(ndicapi *pol);

int ndiGetGXPassiveStray(ndicapi *pol, int i, double coord[3]);

int ndiGetPSTATPortStatus(ndicapi *pol, int port);

int ndiGetPSTATToolInfo(ndicapi *pol, int port, char information[30]);

unsigned long ndiGetPSTATCurrentTest(ndicapi *pol, int port);

int ndiGetPSTATPartNumber(ndicapi *pol, int port, char part[20]);

int ndiGetPSTATAccessories(ndicapi *pol, int port);

int ndiGetPSTATMarkerType(ndicapi *pol, int port);

int ndiGetSSTATControl(ndicapi *pol);

int ndiGetSSTATSensors(ndicapi *pol);

int ndiGetSSTATTIU(ndicapi *pol);

int ndiGetIRCHKDetected(ndicapi *pol);

int ndiGetIRCHKNumberOfSources(ndicapi *pol, int side);

int ndiGetIRCHKSourceXY(ndicapi *pol, int side, int i, double xy[2]);

/*=====================================================================*/
char *ndiErrorString(int errnum);

unsigned long ndiHexToUnsignedLong(const char *cp, int n);

long ndiSignedToLong(const char *cp, int n);

char *ndiHexEncode(char *cp, const void *data, int n);

void *ndiHexDecode(void *data, const char *cp, int n);

/*=====================================================================*/
/*\{*/
#define NDI_OKAY            0x00  
#define NDI_INVALID         0x01  
#define NDI_TOO_LONG        0x02  
#define NDI_TOO_SHORT       0x03  
#define NDI_BAD_COMMAND_CRC 0x04  
#define NDI_INTERN_TIMEOUT  0x05  
#define NDI_COMM_FAIL       0x06  
#define NDI_PARAMETERS      0x07  
#define NDI_INVALID_PORT    0x08  
#define NDI_INVALID_MODE    0x09  
#define NDI_INVALID_LED     0x0a  
#define NDI_LED_STATE       0x0b  
#define NDI_BAD_MODE        0x0c  
#define NDI_NO_TOOL         0x0d  
#define NDI_PORT_NOT_INIT   0x0e  
#define NDI_PORT_DISABLED   0x0f  
#define NDI_INITIALIZATION  0x10  
#define NDI_TSTOP_FAIL      0x11  
#define NDI_TSTART_FAIL     0x12  
#define NDI_PINIT_FAIL      0x13  
#define NDI_CAMERA          0x14  
#define NDI_INIT_FAIL       0x15  
#define NDI_DSTART_FAIL     0x16  
#define NDI_DSTOP_FAIL      0x17  
#define NDI_IRCHK_FAIL      0x18  
#define NDI_FIRMWARE        0x19  
#define NDI_INTERNAL        0x1a  
#define NDI_IRINIT_FAIL     0x1b 
#define NDI_IRED_FAIL       0x1c  
#define NDI_SROM_FAIL       0x1d  
#define NDI_SROM_READ       0x1e  
#define NDI_SROM_WRITE      0x1f  
#define NDI_SROM_SELECT     0x20  
#define NDI_PORT_CURRENT    0x21  
#define NDI_WAVELENGTH      0x22 
#define NDI_PARAMETER_RANGE 0x23  
#define NDI_VOLUME          0x24  
#define NDI_FEATURES        0x25  
#define NDI_ENVIRONMENT     0xf1  
#define NDI_EPROM_READ      0xf6  
#define NDI_EPROM_WRITE     0xf5  
#define NDI_EPROM_ERASE     0xf4  
/* error codes returned by the C api */

#define NDI_BAD_CRC         0x0100  
#define NDI_OPEN_ERROR      0x0200  
#define NDI_BAD_COMM        0x0300  
#define NDI_TIMEOUT         0x0400  
#define NDI_WRITE_ERROR     0x0500  
#define NDI_READ_ERROR      0x0600  
#define NDI_RESET_FAIL      0x0700  
#define NDI_PROBE_FAIL      0x0800  
/*\}*/


/* ndiCOMM() baud rates */
/*\{*/
#define  NDI_9600     0          
#define  NDI_14400    1 
#define  NDI_19200    2
#define  NDI_38400    3
#define  NDI_57600    4
#define  NDI_115200   5
#define  NDI_921600   6
#define  NDI_1228739  7
/*\}*/

/* ndiCOMM() data bits, parity and stop bits */
/*\{*/
#define  NDI_8N1      0              /* 8 data bits, no parity, 1 stop bit */
#define  NDI_8N2      1              /* etc. */
#define  NDI_8O1     10
#define  NDI_8O2     11
#define  NDI_8E1     20
#define  NDI_8E2     21
#define  NDI_7N1    100
#define  NDI_7N2    101
#define  NDI_7O1    110
#define  NDI_7O2    111
#define  NDI_7E1    120
#define  NDI_7E2    121 
/*\}*/

/* ndiCOMM() hardware handshaking */
/*\{*/
#define  NDI_NOHANDSHAKE  0
#define  NDI_HANDSHAKE    1
/*\}*/

/* PHSR() handle types */
/*\{*/
#define  NDI_ALL_HANDLES            0x00
#define  NDI_STALE_HANDLES          0x01
#define  NDI_UNINITIALIZED_HANDLES  0x02
#define  NDI_UNENABLED_HANDLES      0x03
#define  NDI_ENABLED_HANDLES        0x04
/*\}*/

/* ndiPENA() tracking modes */
/*\{*/
#define  NDI_STATIC      'S'    /* relatively immobile tool */ 
#define  NDI_DYNAMIC     'D'    /* dynamic tool (e.g. probe) */
#define  NDI_BUTTON_BOX  'B'    /* tool with no IREDs */
/*\}*/

/* ndiGX() reply mode bit definitions */
/*\{*/
#define  NDI_XFORMS_AND_STATUS  0x0001  /* transforms and status */
#define  NDI_ADDITIONAL_INFO    0x0002  /* additional tool transform info */
#define  NDI_SINGLE_STRAY       0x0004  /* stray active marker reporting */
#define  NDI_FRAME_NUMBER       0x0008  /* frame number for each tool */
#define  NDI_PASSIVE            0x8000  /* report passive tool information */
#define  NDI_PASSIVE_EXTRA      0x2000  /* add 6 extra passive tools */
#define  NDI_PASSIVE_STRAY      0x1000  /* stray passive marker reporting */
/*\}*/

/* return values that give the reason behind missing data */
/*\{*/
#define NDI_DISABLED        1  
#define NDI_MISSING         2  
#define NDI_UNOCCUPIED      3
/*\}*/

/* ndiGetTXPortStatus() and ndiGetPSTATPortStatus() return value bits */
/*\{*/
#define  NDI_TOOL_IN_PORT        0x01
#define  NDI_SWITCH_1_ON         0x02
#define  NDI_SWITCH_2_ON         0x04
#define  NDI_SWITCH_3_ON         0x08
#define  NDI_INITIALIZED         0x10
#define  NDI_ENABLED             0x20
#define  NDI_OUT_OF_VOLUME       0x40 /* only for ndiGetGXPortStatus() */
#define  NDI_PARTIALLY_IN_VOLUME 0x80 /* only for ndiGetGXPortStatus() */ 
#define  NDI_CURRENT_DETECT      0x80 /* only for ndiGetPSTATPortStatus() */
/*\}*/

/* ndiGetTXSystemStatus() return value bits */
/*\{*/
#define  NDI_COMM_SYNC_ERROR            0x0001
#define  NDI_TOO_MUCH_EXTERNAL_INFRARED 0x0002
#define  NDI_COMM_CRC_ERROR             0x0004
#define  NDI_COMM_RECOVERABLE           0x0008
#define  NDI_HARDWARE_FAILURE           0x0010
#define  NDI_HARDWARE_CHANGE            0x0020
#define  NDI_PORT_OCCUPIED              0x0040
#define  NDI_PORT_UNOCCUPIED            0x0080
/*\}*/

/* ndiGetGXToolInfo() return value bits */
/*\{*/
#define  NDI_BAD_TRANSFORM_FIT   0x01
#define  NDI_NOT_ENOUGH_MARKERS  0x02
#define  NDI_TOOL_FACE_USED      0x70
/*\}*/

/* ndiGetTXMarkerInfo() return value bits */
/*\{*/
#define  NDI_MARKER_MISSING             0
#define  NDI_MARKER_EXCEEDED_MAX_ANGLE  1
#define  NDI_MARKER_EXCEEDED_MAX_ERROR  2
#define  NDI_MARKER_USED                3
/*\}*/

/* ndiLED() states */
/*\{*/
#define  NDI_BLANK 'B'    /* off */
#define  NDI_FLASH 'F'    /* flashing */
#define  NDI_SOLID 'S'    /* on */
/*\}*/

/* ndiPSTAT() reply mode bits */
/*\{*/
#define  NDI_BASIC           0x0001
#define  NDI_TESTING         0x0002
#define  NDI_PART_NUMBER     0x0004
#define  NDI_ACCESSORIES     0x0008
#define  NDI_MARKER_TYPE     0x0010
#define  NDI_PORT_LOCATION   0x0020
#define  NDI_GPIO_STATUS     0x0040
/*\}*/

/* ndiGetPSTATAccessories() return value bits */
/*\{*/
#define  NDI_TOOL_IN_PORT_SWITCH   0x01  /* tool has tool-in-port switch */
#define  NDI_SWITCH_1              0x02  /* tool has button #1 */
#define  NDI_SWITCH_2              0x04  /* tool has button #2 */
#define  NDI_SWITCH_3              0x08  /* tool has button #3 */
#define  NDI_TOOL_TRACKING_LED     0x10  /* tool has tracking LED */
#define  NDI_LED_1                 0x20  /* tool has LED #1 */
#define  NDI_LED_2                 0x40  /* tool has LED #2 */
#define  NDI_LED_3                 0x80  /* tool has LED #3 */
/*\}*/
  
/* ndiGetPSTATMarkerType() return value, the first 3 bits */
/*\{*/
#define NDI_950NM            0x00
#define NDI_850NM            0x01
/*\}*/

/* ndiGetPSTATMarkerType() return value, the last 5 bits */
/*\{*/
#define NDI_NDI_ACTIVE       0x08
#define NDI_NDI_CERAMIC      0x10
#define NDI_PASSIVE_ANY      0x20
#define NDI_PASSIVE_SPHERE   0x28
#define NDI_PASSIVE_DISC     0x30
/*\}*/

/* tool type specifiers */
/*\{*/
#define NDI_TYPE_REFERENCE   0x01
#define NDI_TYPE_POINTER     0x02
#define NDI_TYPE_BUTTON      0x03
#define NDI_TYPE_SOFTWARE    0x04
#define NDI_TYPE_MICROSCOPE  0x05
#define NDI_TYPE_DOCK        0x08
#define NDI_TYPE_CARM        0x0A
#define NDI_TYPE_CATHETER    0x0B
/*\}*/

/* ndiSSTAT() reply format bits */
/*\{*/
#define NDI_CONTROL         0x0001  /* control processor information */
#define NDI_SENSORS         0x0002  /* sensor processors */
#define NDI_TIU             0x0004  /* TIU processor */
/*\}*/

/* ndiGetSSTATControl() return value bits */
/*\{*/
#define NDI_EPROM_CODE_CHECKSUM     0x01
#define NDI_EPROM_SYSTEM_CHECKSUM   0x02
/*\}*/

/* ndiGetSSTATSensor() return value bits */
/*\{*/
#define NDI_LEFT_ROM_CHECKSUM   0x01
#define NDI_LEFT_SYNC_TYPE_1    0x02
#define NDI_LEFT_SYNC_TYPE_2    0x04
#define NDI_RIGHT_ROM_CHECKSUM  0x10
#define NDI_RIGHT_SYNC_TYPE_1   0x20
#define NDI_RIGHT_SYNC_TYPE_2   0x40
/*\}*/

/* ndiGetSSTATTIU() return value bits */
/*\{*/
#define NDI_ROM_CHECKSUM        0x01
#define NDI_OPERATING_VOLTAGES  0x02
#define NDI_MARKER_SEQUENCING   0x04
#define NDI_SYNC                0x08
#define NDI_COOLING_FAN         0x10
#define NDI_INTERNAL_ERROR      0x20
/*\}*/

/* ndiIRCHK() reply mode bits */
/*\{*/
#define  NDI_DETECTED   0x0001   /* simple yes/no whether IR detected */
#define  NDI_SOURCES    0x0002   /* locations of up to 20 sources per camera */
/*\}*/

/* ndiGetIRCHKNumberOfSources(), ndiGetIRCHKSourceXY() sensor arguments */
/*\{*/
#define  NDI_LEFT   0            /* left sensor */
#define  NDI_RIGHT  1            /* right sensor */
/*\}*/

#ifdef __cplusplus
}
#endif

#endif /* NDICAPI_H */