Functions
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])

static int	plGetError (polaris *pol)

static char *	plGetDeviceName (polaris *pol)

static PLFileHandle	plGetDeviceHandle (polaris *pol)

static int	plGetThreadMode (polaris *pol)

static int	plGetGXTransform (polaris *pol, int port, double transform[8])

static int	plGetGXPortStatus (polaris *pol, int port)

static int	plGetGXSystemStatus (polaris *pol)

static int	plGetGXToolInfo (polaris *pol, int port)

static int	plGetGXMarkerInfo (polaris *pol, int port, int marker)

static int	plGetGXSingleStray (polaris *pol, int port, double coord[3])

static unsigned long	plGetGXFrame (polaris *pol, int port)

static int	plGetGXNumberOfPassiveStrays (polaris *pol)

static int	plGetGXPassiveStray (polaris *pol, int i, double coord[3])

static int	plGetPSTATPortStatus (polaris *pol, int port)

static int	plGetPSTATToolInfo (polaris *pol, int port, char information[30])

static unsigned long	plGetPSTATCurrentTest (polaris *pol, int port)

static int	plGetPSTATPartNumber (polaris *pol, int port, char part[20])

static int	plGetPSTATAccessories (polaris *pol, int port)

static int	plGetPSTATMarkerType (polaris *pol, int port)

static int	plGetSSTATControl (polaris *pol)

static int	plGetSSTATSensors (polaris *pol)

static int	plGetSSTATTIU (polaris *pol)

static int	plGetIRCHKDetected (polaris *pol)

static int	plGetIRCHKNumberOfSources (polaris *pol, int side)

static int	plGetIRCHKSourceXY (polaris *pol, int side, int i, double xy[2])

Detailed Description

These functions are used to retrieve information that has been stored in the ndicapi object. None of these functions communicate with the device itself, and none of them cause the error indicator to be set.

The DeviceName and DeviceHandle are set when the device is first opened by ndiOpen().

All other information is set by sending the appropriate command to the device through ndiCommand() or through one of the command macros. The information persists until the next time the command is sent.

For example, if the TX command is sent to the device then the information returned by the methods that start with GetTX will be set and will subsequently remain unchanged until the next TX command is sent.

These functions are used to retrieve information that has been stored in the polaris object. None of these functions communicate with the POLARIS itself, and none of them cause the error indicator to be set.

The DeviceName and DeviceHandle are set when the device is first opened by plOpen().

All other information is set by sending the appropriate command to the POLARIS through plCommand() or through one of the command macros. The information persists until the next time the command is sent.

For example, if the PSTAT command is sent to the POLARIS then the information returned by the methods that start with GetPSTAT will be set and will subsequently remain unchanged until the next PSTAT command is sent.

Function Documentation

NDIFileHandle ndiGetDeviceHandle ( ndicapi * pol )

Get the device handle for the serial port that the device is attached to. This device handle is the value returned by the UNIX open() function or the Win32 CreateFile() function.

char* ndiGetDeviceName ( ndicapi * pol )

Get the name of the serial port device that the device is attached to.

int ndiGetError ( ndicapi * pol )

Get error code from the last command. An error code of NDI_OKAY signals that no error occurred. The error codes are listed in Error Codes.

NDIErrorCallback ndiGetErrorCallback ( ndicapi * pol )

Get the current error callback function, or NULL if there is none.

void* ndiGetErrorCallbackData ( ndicapi * pol )

Get the current error callback data, or NULL if there is none.

unsigned long ndiGetGXFrame	(	ndicapi *	pol,
		int	port
	)

Get the camera frame number for the latest transform.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' (active ports only)

Returns: a 32-bit frame number, or zero if no information was available

The frame number is only updated when the GX command is called with the NDI_FRAME_NUMBER (0x0008) bit, and then only for the ports specified by the NDI_PASSIVE (0x8000) and NDI_PASSIVE_EXTRA (0x2000) bits.

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

Get additional information about the tool markers.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'
marker	one of 'A' through 'T' for the 20 markers

Returns

status bits, or zero if there is no information available

NDI_MARKER_MISSING 0
NDI_MARKER_EXCEEDED_MAX_ANGLE 1
NDI_MARKER_EXCEEDED_MAX_ERROR 2
NDI_MARKER_USED 3

The tool marker information is only updated when the GX command is called with the NDI_ADDITIONAL_INFO (0x0002) mode bit set, and then only for the ports specified by the NDI_PASSIVE (0x8000) and NDI_PASSIVE_EXTRA (0x2000) bits.

int ndiGetGXNumberOfPassiveStrays ( ndicapi * pol )

Get the number of passive stray markers detected.

Parameters

pol	valid NDI device handle

Returns: a number between 0 and 20

The passive stray information is updated when a GX command is sent with the NDI_PASSIVE_STRAY (0x1000) and NDI_PASSIVE (0x8000) bits set in the reply mode. The information persists until the next time GX is sent with these bits set.

If no information is available, the return value is zero.

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

Copy the coordinates of the specified stray marker into the supplied array.

Parameters

pol	valid NDI device handle
i	a number between 0 and 19
coord	array to hold the coordinates

Returns

one of:

NDI_OKAY - information was returned in coord
NDI_DISABLED - no stray marker reporting is available
NDI_MISSING - marker number i is not visible

Use ndiGetGXNumberOfPassiveStrays() to get the number of stray markers that are visible.

The passive stray marker coordinates are updated when a GX command is sent with the NDI_PASSIVE_STRAY (0x1000) and NDI_PASSIVE (0x8000) bits set in the reply mode. The information persists until the next time GX is sent with these bits set.

int ndiGetGXPortStatus	(	ndicapi *	pol,
		int	port
	)

Get the 8-bit status value for the specified port.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'

Returns

status bits or zero if there is no information:

NDI_TOOL_IN_PORT 0x01
NDI_SWITCH_1_ON 0x02
NDI_SWITCH_2_ON 0x04
NDI_SWITCH_3_ON 0x08
NDI_INITIALIZED 0x10
NDI_ENABLED 0x20
NDI_OUT_OF_VOLUME 0x40
NDI_PARTIALLY_IN_VOLUME 0x80

The status of the ports is updated according to the same rules as specified for ndiGetGXTransform().

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

Get the coordinates of a stray marker on an active tool. This command is only meaningful for active tools that have a stray marker.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3'
coord	array to hold the three coordinates

Returns

the return value will be one of

NDI_OKAY - values returned in coord
NDI_DISABLED - port disabled or illegal port specified
NDI_MISSING - stray marker is not visible to the device

The stray marker position is only updated when the GX command is called with the NDI_SINGLE_STRAY (0x0004) bit set.

int ndiGetGXSystemStatus ( ndicapi * pol )

Get an 8-bit status bitfield for the system.

Parameters

pol	valid NDI device handle

Returns

status bits or zero if there is no information:

NDI_COMM_SYNC_ERROR 0x01
NDI_TOO_MUCH_EXTERNAL_INFRARED 0x02
NDI_COMM_CRC_ERROR 0x04

The system stutus information is updated whenever the GX command is called with the NDI_XFORMS_AND_STATUS (0x0001) bit set in the reply mode.

int ndiGetGXToolInfo	(	ndicapi *	pol,
		int	port
	)

Get additional information about the tool transformation.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'

Returns

status bits, or zero if there is no information available

NDI_BAD_TRANSFORM_FIT 0x01
NDI_NOT_ENOUGH_MARKERS 0x02
NDI_TOOL_FACE_USED 0x70 - 3 bits give 8 possible faces

The tool information is only updated when the GX command is called with the NDI_ADDITIONAL_INFO (0x0002) mode bit, and then only for the ports specified by the NDI_PASSIVE (0x8000) and NDI_PASSIVE_EXTRA (0x2000) bits.

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

Get the transformation for the specified port. The first four numbers are a quaternion, the next three numbers are the coodinates in millimetres, and the final number is a unitless error estimate.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'
transform	space for the 8 numbers in the transformation

Returns

one of the following:

NDI_OKAY if successful
NDI_DISABLED if tool port is nonexistent or disabled
NDI_MISSING if tool transform cannot be computed

If NDI_DISABLED or NDI_MISSING is returned, then the values in the supplied transform array will be left unchanged.

The transforms for ports '1', '2', '3' are updated whenever the GX comand is sent with the NDI_XFORMS_AND_STATUS (0x0001) bit set in the reply mode. The passive ports 'A', 'B', 'C' are updated if the NDI_PASSIVE (0x8000) bit is also set, and ports 'A' though 'I' are updated if both NDI_PASSIVE (0x8000) and NDI_PASSIVE_EXTRA (0x2000) are also set.

The transformation for any particular port will remain unchanged until it is updated by a GX command with an appropriate reply mode as specified above.

int ndiGetIRCHKDetected ( ndicapi * pol )

Check to see whether environmental infrared was detected.

Parameters

pol	valid NDI device handle

Returns: 1 if infrared was detected and 0 otherwise.

This information is only updated if the IRCHK command is called with the NDI_DETECTED (0x0001) format bit set.

int ndiGetIRCHKNumberOfSources	(	ndicapi *	pol,
		int	side
	)

Get the number of infrared sources seen by one of the two sensors.

Parameters

pol	valid NDI device handle
side	one of NDI_LEFT or NDI_RIGHT

return the number of infrared sources seen by the specified sensor

This information is valid only immediately after the IRCHK command has been called with the NDI_SOURCES (0x0002) format bit set. Otherwise, the return value will be zero.

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

Get the coordinates of one of the infrared sources seen by one of the two sensors.

Parameters

pol	valid NDI device handle
side	one of NDI_LEFT or NDI_RIGHT
xy	space to store the returned coordinates

return NDI_OKAY or NDI_MISSING

If there is no available information, then the xy array will be left unchanged and the value NDI_MISSING will be returned. Otherwise, the return value will be NDI_OKAY.

This information is valid only immediately after the IRCHK command has been called with the NDI_SOURCES (0x0002) format bit set.

int ndiGetPHINFAccessories ( ndicapi * pol )

Get the 8-bit value specifying the tool accessories.

Parameters

pol	valid NDI device handle

Returns

a an integer composed of the following bits:

NDI_TOOL_IN_PORT_SWITCH 0x01 - tool has tool-in-port switch
NDI_SWITCH_1 0x02 - tool has button 1
NDI_SWITCH_2 0x04 - tool has button 2
NDI_SWITCH_3 0x08 - tool has button 3
NDI_TOOL_TRACKING_LED 0x10 - tool has tracking LED
NDI_LED_1 0x20 - tool has LED 1
NDI_LED_2 0x40 - tool has LED 2
NDI_LED_3 0x80 - tool has LED 3

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero.

The return value is updated only when a PHINF command is sent with the NDI_ACCESSORIES (0x0008) bit set in the reply mode.

unsigned long ndiGetPHINFCurrentTest ( ndicapi * pol )

Return the results of a current test on the IREDS on an active POLARIS tool.

Parameters

ts	valid NDI device handle

Returns: 32-bit integer (see NDI documentation)

The information is updated only when a PHINF command is sent with the NDI_TESTING (0x0002) bit set in the reply mode.

int ndiGetPHINFGPIOStatus ( ndicapi * pol )

Get the 8-bit GPIO status for this tool.

Parameters

pol	valid NDI device handle

Returns: an 8-bit integer, see NDI documentation for more information.

The return value is updated only when a PHINF command is sent with the NDI_GPIO_STATUS (0x0040) bit set in the reply mode.

int ndiGetPHINFMarkerType ( ndicapi * pol )

Get an 8-bit value describing the marker type for the tool. The low three bits descibe the wavelength, and the high three bits are the marker type code.

Parameters

pol	valid NDI device handle

Returns

see NDI documentation for more information:

low bits:
- NDI_950NM 0x00
- NDI_850NM 0x01
high bits:
- NDI_NDI_ACTIVE 0x08
- NDI_NDI_CERAMIC 0x10
- NDI_PASSIVE_ANY 0x20
- NDI_PASSIVE_SPHERE 0x28
- NDI_PASSIVE_DISC 0x30

The return value is updated only when a PHINF command is sent with the NDI_MARKER_TYPE (0x0010) bit set in the reply mode.

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

Get a 20-byte string that contains the part number of the tool.

Parameters

pol	valid NDI device handle
part	array that part number is returned in (the resulting string is not null-terminated)

Returns

one of:

NDI_OKAY - information was returned
NDI_UNOCCUPIED - port is unoccupied or no information is available

If a terminated string is required, then set part[20] to '\0' before calling this function.

The information is updated only when a PHINF command is sent with the NDI_PART_NUMBER (0x0004) bit set in the reply mode.

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

Get a 14-byte description of the physical location of the tool on the system.

Parameters

pol	valid NDI device handle

Returns

see NDI documentation for more information:

8 chars: device number
1 char: 0 = POLARIS, 1 = AURORA
1 char: 0 = wired, 1 = wireless
2 chars: port number 01-12 or 0A-0I
2 chars: hexidecimal channel number

The return value is updated only when a PHINF command is sent with the NDI_PORT_LOCATION_TYPE (0x0020) bit set in the reply mode.

int ndiGetPHINFPortStatus ( ndicapi * pol )

Get the 8-bit status value for the port handle.

Parameters

pol	valid NDI device handle

Returns

a an integer composed of the following bits:

NDI_TOOL_IN_PORT 0x01 - there is a tool in the port
NDI_SWITCH_1_ON 0x02 - button 1 is pressed
NDI_SWITCH_2_ON 0x04 - button 2 is pressed
NDI_SWITCH_3_ON 0x08 - button 3 is pressed
NDI_INITIALIZED 0x10 - tool port has been initialized
NDI_ENABLED 0x20 - tool port is enabled for tracking
NDI_CURRENT_DETECT 0x80 - tool sensed through current detection

The return value is updated only when a PHINF command is sent with the NDI_BASIC (0x0001) bit set in the reply mode.

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

Get a 31-byte string describing the tool.

Parameters

piol	valid NDI device handle
information	array that information is returned in (the resulting string is not null-terminated)

Returns

one of:

NDI_OKAY - information was returned
NDI_UNOCCUPIED - port is unoccupied or no information is available

The returned string will not be null-terminated by default. You must set information[31] to 0 in order to terminate the string. If the port is unoccupied then the contents of the information string are undefined.

The information is updated only when a PHINF command is sent with the NDI_BASIC (0x0001) bit set in the reply mode.

int ndiGetPHRQHandle ( ndicapi * pol )

Get the port handle returned by a PHRQ command.

Parameters

pol	valid NDI device handle

Returns: a port handle between 0x01 and 0xFF

An SROM can be written to the port handle wit the PVWR command.

int ndiGetPHSRHandle	(	ndicapi *	pol,
		int	i
	)

Get one of the port handles returned by a PHSR command.

Parameters

pol	valid NDI device handle
i	a value between 0 and n where is the value returned by ndiGetPHSRNumberOfHandles().

Returns: a port handle between 0x01 and 0xFF

The PHINF command can be used to get detailed information about the port handle.

int ndiGetPHSRInformation	(	ndicapi *	pol,
		int	i
	)

Get the information for a port handle returned by a PHSR command.

Parameters

pol	valid NDI device handle
i	a value between 0 and n where is the value returned by ndiGetPHSRNumberOfHandles().

Returns

a 12-bit bitfield where the following bits are defined:

NDI_TOOL_IN_PORT 0x01 - there is a tool in the port
NDI_SWITCH_1_ON 0x02 - button 1 is pressed
NDI_SWITCH_2_ON 0x04 - button 2 is pressed
NDI_SWITCH_3_ON 0x08 - button 3 is pressed
NDI_INITIALIZED 0x10 - tool port has been initialized
NDI_ENABLED 0x20 - tool port is enabled for tracking
NDI_CURRENT_DETECT 0x80 - tool sensed through current detection

The PHINF command can be used to get detailed information about the port handle.

int ndiGetPHSRNumberOfHandles ( ndicapi * pol )

Get the number of port handles as returned by a PHSR command.

Parameters

pol	valid NDI device handle

Returns: an integer, the maximum possible value is 255

int ndiGetPSTATAccessories	(	ndicapi *	pol,
		int	port
	)

Get the 8-bit value specifying the accessories for the specified tool.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' (active ports only)

Returns

a an integer composed of the following bits:

NDI_TOOL_IN_PORT_SWITCH 0x01 - tool has tool-in-port switch
NDI_SWITCH_1 0x02 - tool has button 1
NDI_SWITCH_2 0x04 - tool has button 2
NDI_SWITCH_3 0x08 - tool has button 3
NDI_TOOL_TRACKING_LED 0x10 - tool has tracking LED
NDI_LED_1 0x20 - tool has LED 1
NDI_LED_2 0x40 - tool has LED 2
NDI_LED_3 0x80 - tool has LED 3

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero. The return value is always zero for passive ports.

The return value is updated only when a PSTAT command is sent with the NDI_ACCESSORIES (0x0008) bit set in the reply mode.

unsigned long ndiGetPSTATCurrentTest	(	ndicapi *	pol,
		int	port
	)

Return the results of a current test on the IREDS on the specified tool.

Parameters

ts	valid NDI device handle
port	one of '1', '2', '3'

Returns: 32-bit integer (see NDI documentation)

The information is updated only when a PSTAT command is sent with the NDI_TESTING (0x0002) bit set in the reply mode.

int ndiGetPSTATMarkerType	(	ndicapi *	pol,
		int	port
	)

Get an 8-bit value describing the marker type for the tool. The low three bits descibe the wavelength, and the high three bits are the marker type code.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' (active ports only)

Returns

see NDI documentation for more information:

low bits:
- NDI_950NM 0x00
- NDI_850NM 0x01
high bits:
- NDI_NDI_ACTIVE 0x08
- NDI_NDI_CERAMIC 0x10
- NDI_PASSIVE_ANY 0x20
- NDI_PASSIVE_SPHERE 0x28
- NDI_PASSIVE_DISC 0x30

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero.

The return value is updated only when a PSTAT command is sent with the NDI_MARKER_TYPE (0x0010) bit set in the reply mode.

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

Get a 20-byte string that contains the part number of the tool.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'
part	array that part number is returned in (the resulting string is not null-terminated)

Returns

one of:

NDI_OKAY - information was returned
NDI_UNOCCUPIED - port is unoccupied or no information is available

If a terminated string is required, then set part[20] to '\0' before calling this function.

The information is updated only when a PSTAT command is sent with the NDI_PART_NUMBER (0x0004) bit set in the reply mode.

int ndiGetPSTATPortStatus	(	ndicapi *	pol,
		int	port
	)

Get the 8-bit status value for the specified port.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'

Returns

a an integer composed of the following bits:

NDI_TOOL_IN_PORT 0x01 - there is a tool in the port
NDI_SWITCH_1_ON 0x02 - button 1 is pressed
NDI_SWITCH_2_ON 0x04 - button 2 is pressed
NDI_SWITCH_3_ON 0x08 - button 3 is pressed
NDI_INITIALIZED 0x10 - tool port has been initialized
NDI_ENABLED 0x20 - tool port is enabled for tracking
NDI_CURRENT_DETECT 0x80 - tool sensed through current detection

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero. The return value is updated only when a PSTAT command is sent with the NDI_BASIC (0x0001) bit set in the reply mode.

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

Get a 30-byte string describing the tool in the specified port.

Parameters

pol	valid NDI device handle
port	one of '1', '2', '3' or 'A' to 'I'
information	array that information is returned in (the resulting string is not null-terminated)

Returns

one of:

NDI_OKAY - information was returned
NDI_UNOCCUPIED - port is unoccupied or no information is available

The returned string will not be null-terminated by default. You must set information[30] to 0 in order to terminate the string. If the port is unoccupied then the contents of the information string are undefined.

The information is updated only when a PSTAT command is sent with the NDI_BASIC (0x0001) bit set in the reply mode.

int ndiGetSSTATControl ( ndicapi * pol )

Get the status of the control processor.

Parameters

pol	valid NDI device handle

Returns

an int with the following bit definitions for errors:

NDI_EPROM_CODE_CHECKSUM 0x01
NDI_EPROM_SYSTEM_CHECKSUM 0x02

This information is updated only when the SSTAT command is sent with the NDI_CONTROL (0x0001) bit set in the reply mode.

int ndiGetSSTATSensors ( ndicapi * pol )

Get the status of the sensor processors.

Parameters

pol	valid NDI device handle

Returns

an int with the following bit definitions for errors:

NDI_LEFT_ROM_CHECKSUM 0x01
NDI_LEFT_SYNC_TYPE_1 0x02
NDI_LEFT_SYNC_TYPE_2 0x04
NDI_RIGHT_ROM_CHECKSUM 0x10
NDI_RIGHT_SYNC_TYPE_1 0x20
NDI_RIGHT_SYNC_TYPE_2 0x40

This information is updated only when the SSTAT command is sent with the NDI_SENSORS (0x0002) bit set in the reply mode.

int ndiGetSSTATTIU ( ndicapi * pol )

Get the status of the sensor processors.

Parameters

pol	valid NDI device handle

Returns

an int with the following bit definitions for errors:

NDI_ROM_CHECKSUM 0x01
NDI_OPERATING_VOLTAGES 0x02
NDI_MARKER_SEQUENCING 0x04
NDI_SYNC 0x08
NDI_COOLING_FAN 0x10
NDI_INTERNAL_ERROR 0x20

This information is updated only when the SSTAT command is sent with the NDI_TIU (0x0004) bit set in the reply mode.

int ndiGetThreadMode ( ndicapi * pol )

Check the current theading mode. The default is 0 (no multithreading).

unsigned long ndiGetTXFrame	(	ndicapi *	pol,
		int	ph
	)

Get the camera frame number for the latest transform.

Parameters

pol	valid NDI device handle
ph	valid port handle in range 0x01 to 0xFF

Returns: a 32-bit frame number, or zero if no information was available

This information is updated each time that the TX command is sent to the device.

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

Get additional information about the tool markers.

Parameters

pol	valid NDI device handle
ph	valid port handle in range 0x01 to 0xFF
marker	one of 'A' through 'T' for the 20 markers

Returns

status bits, or zero if there is no information available

NDI_MARKER_MISSING 0
NDI_MARKER_EXCEEDED_MAX_ANGLE 1
NDI_MARKER_EXCEEDED_MAX_ERROR 2
NDI_MARKER_USED 3

The tool marker information is only updated when the TX command is called with the NDI_ADDITIONAL_INFO (0x0002) mode bit set.

int ndiGetTXNumberOfPassiveStrays ( ndicapi * pol )

Get the number of passive stray markers detected.

Parameters

pol	valid NDI device handle

Returns: a number between 0 and 20

The passive stray marker coordinates are updated when a TX command is sent with the NDI_PASSIVE_STRAY (0x1000) bit set in the reply mode.

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

Copy the coordinates of the specified stray marker into the supplied array.

Parameters

pol	valid NDI device handle
i	a number between 0 and 19
coord	array to hold the coordinates

Returns

one of:

NDI_OKAY - information was returned in coord
NDI_DISABLED - no stray marker reporting is available
NDI_MISSING - marker number i is not visible

Use ndiGetTXNumberOfPassiveStrays() to get the number of stray markers that are visible.

The passive stray marker coordinates are updated when a TX command is sent with the NDI_PASSIVE_STRAY (0x1000) bit set in the reply mode.

int ndiGetTXPortStatus	(	ndicapi *	pol,
		int	ph
	)

Get the 16-bit status value for the specified port handle.

Parameters

pol	valid NDI device handle
ph	valid port handle in range 0x01 to 0xFF

Returns

status bits or zero if there is no information:

NDI_TOOL_IN_PORT 0x0001
NDI_SWITCH_1_ON 0x0002
NDI_SWITCH_2_ON 0x0004
NDI_SWITCH_3_ON 0x0008
NDI_INITIALIZED 0x0010
NDI_ENABLED 0x0020
NDI_OUT_OF_VOLUME 0x0040
NDI_PARTIALLY_IN_VOLUME 0x0080

This information is updated each time that the TX command is sent to the device.

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

Get the coordinates of a stray marker on a wired POLARIS tool. This command is only meaningful for tools that have a stray marker.

Parameters

pol	valid NDI device handle
ph	valid port handle in range 0x01 to 0xFF
coord	array to hold the three coordinates

Returns

the return value will be one of

NDI_OKAY - values returned in coord
NDI_DISABLED - port disabled or illegal port specified
NDI_MISSING - stray marker is not visible to the device

The stray marker position is only updated when the GX command is called with the NDI_SINGLE_STRAY (0x0004) bit set.

int ndiGetTXSystemStatus ( ndicapi * pol )

Get an 16-bit status bitfield for the system.

Parameters

pol	valid NDI device handle

Returns

status bits or zero if there is no information:

NDI_COMM_SYNC_ERROR 0x0001
NDI_TOO_MUCH_EXTERNAL_INFRARED 0x0002
NDI_COMM_CRC_ERROR 0x0004
NDI_COMM_RECOVERABLE 0x0008
NDI_HARDWARE_FAILURE 0x0010
NDI_HARDWARE_CHANGE 0x0020
NDI_PORT_OCCUPIED 0x0040
NDI_PORT_UNOCCUPIED 0x0080

The system stutus information is updated whenever the TX command is called with the NDI_XFORMS_AND_STATUS (0x0001) bit set in the reply mode.

int ndiGetTXToolInfo	(	ndicapi *	pol,
		int	ph
	)

Get additional information about the tool transformation.

Parameters

pol	valid NDI device handle
ph	valid port handle in range 0x01 to 0xFF

Returns

status bits, or zero if there is no information available

NDI_BAD_TRANSFORM_FIT 0x01
NDI_NOT_ENOUGH_MARKERS 0x02
NDI_TOOL_FACE_USED 0x70 - 3 bits give 8 possible faces

The tool information is only updated when the TX command is called with the NDI_ADDITIONAL_INFO (0x0002) mode bit.

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

Get the transformation for the specified port. The first four numbers are a quaternion, the next three numbers are the coodinates in millimetres, and the final number is a unitless error estimate.

Parameters

pol	valid NDI device handle
ph	valid port handle in range 0x01 to 0xFF
transform	space for the 8 numbers in the transformation

Returns

one of the following:

NDI_OKAY if successful
NDI_DISABLED if tool port is nonexistent or disabled
NDI_MISSING if tool transform cannot be computed

If NDI_DISABLED or NDI_MISSING is returned, then the values in the supplied transform array will be left unchanged.

The transformations for each of the port handles remain the same until the next TX command is sent to device.

static PLFileHandle plGetDeviceHandle ( polaris * pol )

static

Get the device handle for the serial port that the POLARIS is attached to. This device handle is the value returned by the UNIX open() function or the Win32 CreateFile() function.

static char* plGetDeviceName ( polaris * pol )

static

Get the name of the serial port device that the POLARIS is attached to.

static int plGetError ( polaris * pol )

static

Get error code from the last command. An error code of PL_OKAY signals that no error occurred. The error codes are listed in Error Codes.

static unsigned long plGetGXFrame	(	polaris *	pol,
		int	port
	)

static

Get the camera frame number for the latest transform.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' (active ports only)

Returns: a 32-bit frame number, or zero if no information was available

The frame number is only updated when the GX command is called with the PL_FRAME_NUMBER (0x0008) bit, and then only for the ports specified by the PL_PASSIVE (0x8000) and PL_PASSIVE_EXTRA (0x2000) bits.

static int plGetGXMarkerInfo	(	polaris *	pol,
		int	port,
		int	marker
	)

static

Get additional information about the tool markers.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'
marker	one of 'A' through 'T' for the 20 markers

Returns

status bits, or zero if there is no information available

PL_MARKER_MISSING 0
PL_MARKER_EXCEEDED_MAX_ANGLE 1
PL_MARKER_EXCEEDED_MAX_ERROR 2
PL_MARKER_USED 3

The tool marker information is only updated when the GX command is called with the PL_ADDITIONAL_INFO (0x0002) mode bit set, and then only for the ports specified by the PL_PASSIVE (0x8000) and PL_PASSIVE_EXTRA (0x2000) bits.

static int plGetGXNumberOfPassiveStrays ( polaris * pol )

static

Get the number of passive stray markers detected.

Parameters

pol	pointer to a valid polaris object

Returns: a number between 0 and 20

The passive stray information is updated when a GX command is sent with the PL_PASSIVE_STRAY (0x1000) and PL_PASSIVE (0x8000) bits set in the reply mode. The information persists until the next time GX is sent with these bits set.

If no information is available, the return value is zero.

static int plGetGXPassiveStray	(	polaris *	pol,
		int	i,
		double	coord[3]
	)

static

Copy the coordinates of the specified stray marker into the supplied array.

Parameters

pol	pointer to a valid polaris object
i	a number between 0 and 19
coord	array to hold the coordinates

Returns

one of:

PL_OKAY - information was returned in coord
PL_DISABLED - no stray marker reporting is available
PL_MISSING - marker number i is not visible

Use plGetGXNumberOfPassiveStrays() to get the number of stray markers that are visible.

The passive stray marker coordinates are updated when a GX command is sent with the PL_PASSIVE_STRAY (0x1000) and PL_PASSIVE (0x8000) bits set in the reply mode. The information persists until the next time GX is sent with these bits set.

static int plGetGXPortStatus	(	polaris *	pol,
		int	port
	)

static

Get the 8-bit status value for the specified port.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'

Returns

status bits or zero if there is no information:

PL_TOOL_IN_PORT 0x01
PL_SWITCH_1_ON 0x02
PL_SWITCH_2_ON 0x04
PL_SWITCH_3_ON 0x08
PL_INITIALIZED 0x10
PL_ENABLED 0x20
PL_OUT_OF_VOLUME 0x40
PL_PARTIALLY_IN_VOLUME 0x80

The status of the ports is updated according to the same rules as specified for plGetGXTransform().

static int plGetGXSingleStray	(	polaris *	pol,
		int	port,
		double	coord[3]
	)

static

Get the coordinates of a stray marker on an active tool. This command is only meaningful for active tools that have a stray marker.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3'
coord	array to hold the three coordinates

Returns

the return value will be one of

PL_OKAY - values returned in coord
PL_DISABLED - port disabled or illegal port specified
PL_MISSING - stray marker is not visible to the POLARIS

The stray marker position is only updated when the GX command is called with the PL_SINGLE_STRAY (0x0004) bit set.

static int plGetGXSystemStatus ( polaris * pol )

static

Get an 8-bit status bitfield for the system.

Parameters

pol	pointer to a valid polaris object

Returns

status bits or zero if there is no information:

PL_COMM_SYNC_ERROR 0x01
PL_TOO_MUCH_EXTERNAL_INFRARED 0x02
PL_COMM_CRC_ERROR 0x04

The system stutus information is updated whenever the GX command is called with the PL_XFORMS_AND_STATUS (0x0001) bit set in the reply mode.

static int plGetGXToolInfo	(	polaris *	pol,
		int	port
	)

static

Get additional information about the tool transformation.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'

Returns

status bits, or zero if there is no information available

PL_BAD_TRANSFORM_FIT 0x01
PL_NOT_ENOUGH_MARKERS 0x02
PL_TOOL_FACE_USED 0x70 - 3 bits give 8 possible faces

The tool information is only updated when the GX command is called with the PL_ADDITIONAL_INFO (0x0002) mode bit, and then only for the ports specified by the PL_PASSIVE (0x8000) and PL_PASSIVE_EXTRA (0x2000) bits.

static int plGetGXTransform	(	polaris *	pol,
		int	port,
		double	transform[8]
	)

static

Get the transformation for the specified port. The first four numbers are a quaternion, the next three numbers are the coodinates in millimetres, and the final number is a unitless error estimate.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'
transform	space for the 8 numbers in the transformation

Returns

one of the following:

PL_OKAY if successful
PL_DISABLED if tool port is nonexistent or disabled
PL_MISSING if tool transform cannot be computed

If PL_DISABLED or PL_MISSING is returned, then the values in the supplied transform array will be left unchanged.

The transforms for ports '1', '2', '3' are updated whenever the GX comand is sent with the PL_XFORMS_AND_STATUS (0x0001) bit set in the reply mode. The passive ports 'A', 'B', 'C' are updated if the PL_PASSIVE (0x8000) bit is also set, and ports 'A' though 'I' are updated if both PL_PASSIVE (0x8000) and PL_PASSIVE_EXTRA (0x2000) are also set.

The transformation for any particular port will remain unchanged until it is updated by a GX command with an appropriate reply mode as specified above.

static int plGetIRCHKDetected ( polaris * pol )

static

Check to see whether environmental infrared was detected.

Parameters

pol	pointer to a valid polaris object

Returns: 1 if infrared was detected and 0 otherwise.

This information is only updated if the IRCHK command is called with the PL_DETECTED (0x0001) format bit set.

static int plGetIRCHKNumberOfSources	(	polaris *	pol,
		int	side
	)

static

Get the number of infrared sources seen by one of the two sensors.

Parameters

pol	pointer to a valid polaris object
side	one of PL_LEFT or PL_RIGHT

return the number of infrared sources seen by the specified sensor

This information is valid only immediately after the IRCHK command has been called with the PL_SOURCES (0x0002) format bit set. Otherwise, the return value will be zero.

static int plGetIRCHKSourceXY	(	polaris *	pol,
		int	side,
		int	i,
		double	xy[2]
	)

static

Get the coordinates of one of the infrared sources seen by one of the two sensors.

Parameters

pol	pointer to a valid polaris object
side	one of PL_LEFT or PL_RIGHT
xy	space to store the returned coordinates

return PL_OKAY or PL_MISSING

If there is no available information, then the xy array will be left unchanged and the value PL_MISSING will be returned. Otherwise, the return value will be PL_OKAY.

This information is valid only immediately after the IRCHK command has been called with the PL_SOURCES (0x0002) format bit set.

static int plGetPSTATAccessories	(	polaris *	pol,
		int	port
	)

static

Get the 8-bit value specifying the accessories for the specified tool.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' (active ports only)

Returns

a an integer composed of the following bits:

PL_TOOL_IN_PORT_SWITCH 0x01 - tool has tool-in-port switch
PL_SWITCH_1 0x02 - tool has button 1
PL_SWITCH_2 0x04 - tool has button 2
PL_SWITCH_3 0x08 - tool has button 3
PL_TOOL_TRACKING_LED 0x10 - tool has tracking LED
PL_LED_1 0x20 - tool has LED 1
PL_LED_2 0x40 - tool has LED 2
PL_LED_3 0x80 - tool has LED 3

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero. The return value is always zero for passive ports.

The return value is updated only when a PSTAT command is sent with the PL_ACCESSORIES (0x0008) bit set in the reply mode.

static unsigned long plGetPSTATCurrentTest	(	polaris *	pol,
		int	port
	)

static

Return the results of a current test on the IREDS on the specified tool.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3'

Returns: 32-bit integer (see NDI POLARIS documentation)

The information is updated only when a PSTAT command is sent with the PL_TESTING (0x0002) bit set in the reply mode.

static int plGetPSTATMarkerType	(	polaris *	pol,
		int	port
	)

static

Get an 8-bit value describing the marker type for the tool. The low three bits descibe the wavelength, and the high three bits are the marker type code.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' (active ports only)

Returns

see NDI POLARIS documentation for more information:

low bits:
- PL_950NM 0x00
- PL_850NM 0x01
high bits:
- PL_NDI_ACTIVE 0x08
- PL_NDI_CERAMIC 0x10
- PL_PASSIVE_ANY 0x20
- PL_PASSIVE_SPHERE 0x28
- PL_PASSIVE_DISC 0x30

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero.

The return value is updated only when a PSTAT command is sent with the PL_MARKER_TYPE (0x0010) bit set in the reply mode.

static int plGetPSTATPartNumber	(	polaris *	pol,
		int	port,
		char	part[20]
	)

static

Get a 20-byte string that contains the part number of the tool.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'
part	array that part number is returned in (the resulting string is not null-terminated)

Returns

one of:

PL_OKAY - information was returned
PL_UNOCCUPIED - port is unoccupied or no information is available

If a terminated string is required, then set part[20] to '\0' before calling this function.

The information is updated only when a PSTAT command is sent with the PL_PART_NUMBER (0x0004) bit set in the reply mode.

static int plGetPSTATPortStatus	(	polaris *	pol,
		int	port
	)

static

Get the 8-bit status value for the specified port.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'

Returns

a an integer composed of the following bits:

PL_TOOL_IN_PORT 0x01 - there is a tool in the port
PL_SWITCH_1_ON 0x02 - button 1 is pressed
PL_SWITCH_2_ON 0x04 - button 2 is pressed
PL_SWITCH_3_ON 0x08 - button 3 is pressed
PL_INITIALIZED 0x10 - tool port has been initialized
PL_ENABLED 0x20 - tool port is enabled for tracking
PL_CURRENT_DETECT 0x80 - tool sensed through current detection

If there is no available information for the specified port, or if an illegal port specifier value is used, the return value is zero. The return value is updated only when a PSTAT command is sent with the PL_BASIC (0x0001) bit set in the reply mode.

static int plGetPSTATToolInfo	(	polaris *	pol,
		int	port,
		char	information[30]
	)

static

Get a 30-byte string describing the tool in the specified port.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'
information	array that information is returned in (the resulting string is not null-terminated)

Returns

one of:

PL_OKAY - information was returned
PL_UNOCCUPIED - port is unoccupied or no information is available

The returned string will not be null-terminated by default. You must set information[30] to 0 in order to terminate the string. If the port is unoccupied then the information string will read "UNOCCUPIED".

The information is updated only when a PSTAT command is sent with the PL_BASIC (0x0001) bit set in the reply mode.

static int plGetSSTATControl ( polaris * pol )

static

Get the status of the control processor.

Parameters

pol	pointer to a valid polaris object

Returns

an int with the following bit definitions for errors:

PL_EPROM_CODE_CHECKSUM 0x01
PL_EPROM_SYSTEM_CHECKSUM 0x02

This information is updated only when the SSTAT command is sent with the PL_CONTROL (0x0001) bit set in the reply mode.

static int plGetSSTATSensors ( polaris * pol )

static

Get the status of the sensor processors.

Parameters

pol	pointer to a valid polaris object

Returns

an int with the following bit definitions for errors:

PL_LEFT_ROM_CHECKSUM 0x01
PL_LEFT_SYNC_TYPE_1 0x02
PL_LEFT_SYNC_TYPE_2 0x04
PL_RIGHT_ROM_CHECKSUM 0x10
PL_RIGHT_SYNC_TYPE_1 0x20
PL_RIGHT_SYNC_TYPE_2 0x40

This information is updated only when the SSTAT command is sent with the PL_SENSORS (0x0002) bit set in the reply mode.

static int plGetSSTATTIU ( polaris * pol )

static

Get the status of the sensor processors.

Parameters

pol	pointer to a valid polaris object

Returns

an int with the following bit definitions for errors:

PL_ROM_CHECKSUM 0x01
PL_OPERATING_VOLTAGES 0x02
PL_MARKER_SEQUENCING 0x04
PL_SYNC 0x08
PL_COOLING_FAN 0x10
PL_INTERNAL_ERROR 0x20

This information is updated only when the SSTAT command is sent with the PL_TIU (0x0004) bit set in the reply mode.

static int plGetThreadMode ( polaris * pol )

static

Check the current theading mode. The default is 0 (no multithreading).

Functions

Detailed Description

Function Documentation