Vous êtes sur la page 1sur 5

TrackdAPI™ Documentation

1 Introduction
The TrackdAPI is an API for reading data stored in a shared memory segment by the
tracker or controller daemon, trackd. Trackd is sometimes just referred to as the daemon.
The API was created in response to a need by third-party software wanting to run on a
CAVE , ImmersaDesk or other Spatially Immersive Display using the trackd daemon
software. Prior to the TrackdAPI, data from the daemons could only be accessed from
within a CAVELib application. The TrackdAPI gives users an interface to the
daemons’shared memory segments without the need to compile the CAVELib with the
third-party software.

The trackd was originally created to solve several issues. It allows interactions with
trackers and controllers to occur outside of the CAVELib software. By defining an
interface that all daemons adhere to, support of new devices can be added without the
need to upgrade the CAVELib or other source code. The trackd allows a tracker to
continue to run between starting and stopping CAVE applications. (Some tracking
systems required a power-cycle in between each application. The trackd, which runs
continually, eliminates the need for power-cycling tracker systems.)

2 Usage
2.1 Compatibility with trackd
TrackdAPI is designed for daemons from the CAVELib version 2.6 or later. If the
daemons were purchased along with the CAVELib check that the version is 2.6 or later,
this can easily be done by running a CAVE application. The configuration information
printed at the startup will include the CAVELib version number. Owners of the
CAVELib version 2.6 or later will have an additional binary application called
trackd_bc, in the /usr/local/CAVE/bin directory for use with version 2.5.6 CAVE
applications and earlier. The TrackdAPI will not work with the trackd_bc.

Daemons purchased without a CAVELib but as the “Tracker Package” are the correct
version, and will work with the TrackdAPI.
2.2 Shared memory keys
The TrackdAPI requires shared memory key(s) to read the tracker and/or controller data.
If the keys specified to the TrackdAPI do not match an existing shared memory segment
an error will occur, e.g.

ERROR: can't get tracker shared memory


shmget: No such file or directory
ERROR: can't attach tracker shared memory
shmat: Invalid argument

If the TrackdAPI attaches to a shared memory segment that is not the correct daemon’s
shared memory the actions are undefined. Note: most likely a bus error will occur.

The shared memory keys for the daemons are specified either on the command line or in
the configuration file with the configuration keywords ‘trackerDaemonKey’ and
‘controllerDaemonKey’. Owners of the CAVELib may have their shared memory
daemon keys specified in more then one configuration file, but only the last seen values
are used by the daemon. The daemon will attempt to read the standard order of CAVE
configuration files as specified in the CAVELib user’s guide. The daemon will also read
shared memory keys from the command line. Any shared memory keys listed on the
command line will be used in place of any values specified in a configuration file.

The value of the shared memory key specified in the configuration file or the command
line must also be used in the appropriate TrackdAPI function or constructor in order for
the software to work.

You can confirm which shared memory keys are in use by using the UNIX command
ipcs, which will list all of the shared memory segments in use, along with the
hexadecimal values of the shared memory keys. It is possible to convert a shared memory
key into decimal format and supply it to the TrackdAPI’s function or constructor. It is
common for two daemons to be running, one for the tracker and one for the controller.
(historically the controller’s shared memory key is one plus the value of the tracker
shared memory key, e.g. if the trackerDaemonKey is 3110 then the
controllerDaemonKey would be 3111).

Note: this technique is not guaranteed to work since there may be more then two shared
memory segments in use, and there is no way to determine which segments belong to the
tracker and/or controller.
3 API
To initialize or create a reader for a tracker or controller the correct shared memory key
must always be specified. When reading values from the tracker or controller, and an
index value for the sensor, buttons or valuators is specified, indexing always begins at 0.

3.1 C Functions

3.2 Tracker Functions


void* trackdInitTrackerReader(int shmKey)
Attaches a tracker pointer to the shared memory specified by shmKey and returns
that pointer as a void*. It returns NULL if it fails. This pointer must be passed to
the other TrackdAPI tracker functions to receive data values.

int trackdGetNumberOfSensors(void* tracker)


Returns the number sensors the tracker daemon is storing.

void trackdGetPosition(void* tracker, int id, float* pos)


Gets the raw tracker position values in feet for sensor[id]. The transmitter’s
coordinate system will be the same as that of the CAVE’s (+X right, +Y up, and
+Z back, a right hand coordinate system), although orthogonal to the transmitters
orientation. The transmitter’s translation and rotation offsets from the CAVE’s
origin and orientation will have to be accounted for to obtain values in CAVE
coordinates.

void trackdGetEulerAngles(void* tracker, int id, float* orn)


Gets the euler angle values for sensor[id]. Rotations follow the right hand rule,
with the right hand’s thumb along the axis, the fingers will curl along the
direction of positive rotations. Elevation is around the x-axis, azimuth is around
the y-axis and roll is around the z-axis.

void trackdGetMatrix(void* tracker, int id, float mat[4][4])


Gets the transformation matrix for sensor[id]. (Read the comments for the
functions trackdGetEulerAgles() and trackdGetPosition() for information
regarding position orientation values.)

3.3 Controller Functions


void* trackdInitControllerReader(int)
Attaches a controller pointer to the shared memory specified by shmKey and
returns that pointer as a void*. It returns NULL if it fails. This pointer must be
passed to the other TrackdAPI controller functions to receive data values.

int trackdGetNumberOfValuators(void* controller)


Returns the number of valuators the tracker daemon is storing.
int trackdGetNumberOfButtons(void* controller)
Returns the number of buttons the daemon is storing.

float trackdGetValuator(void* controller, int id)


Returns the float value of valuator[id] from the daemon. The valuators are
generally associated with joysticks or finger bend angles.

int trackdGetButton(void* controller, int id)


Returns the integer value of button[id] from the daemon. The buttons are
generally treated as boolean values, with 1 being on, and 0 being off.

3.4 C++ Class

3.4.1 TrackerReader Class


TrackerReader(int)
The constructor attaches a pointer to the tracker shared memory segment. To
create a tracker reader the decimal value of the daemon’s shared memory key
must be provided as an argument. Note: there is no default constructor available.

virtual ~TrackerReader()
Detaches from the tracker shared memory segment.

int trackdGetNumberOfSensors(void)
Returns the number of sensors the tracker daemon is storing.

void trackdGetPosition(int id, float* pos)


Returns the raw tracker position values in feet for sensor[id]. The transmitter’s
coordinate system will be the same as that of the CAVE’s (+X right, +Y up, and
+Z back, a right hand coordinate system), although orthogonal to the transmitters
orientation. The transmitter’s translation and rotation offsets from the CAVE’s
origin and orientation will have to be accounted for to obtain values in CAVE
coordinates.

void trackdGetEulerAngles(int id, float* orn)


Returns the euler angle values for sensor[id]. Rotations follow the right hand rule,
with the right hand’s thumb along the axis, the fingers will curl along the
direction of positive rotations. Elevation is around the x-axis, azimuth is around
the y-axis and roll is around the z-axis.

void trackdGetMatrix(int id, float mat[4][4])


Returns the transformations matrix of sensor[id]. (Read the comments for the
class methods trackdGetEulerAgles() and trackdGetPosition() for information
regarding position orientation values.)
3.4.2 ControllerReader Class
ControllerReader(int)
The constructor attaches a pointer to the controller shared memory segment. To
create a controller reader the decimal value of the daemon’s shared memory key
must be provided as an argument. Note: there is no default constructor available.

virtual ~ControllerReader()
Detaches from the controller shared memory segment.

int trackdGetNumberOfValuators()
Returns the number of valuators the daemon is storing

int trackdGetNumberOfButtons()
Returns the number of buttons the daemon is storing

float trackdGetValuator(int id)


Returns value of valuator[id] from the daemon. The valuators are generally
associated with joysticks or finger bend angles.

int trackdGetButton(int id)


Returns the value of button[id] from the daemon. The buttons are generally
treated as boolean values, with 1 being on, and 0 being off.

4 Summary
The TrackdAPI was meant to be a simple interface for retrieving data values from the
trackd tracker and controller daemons. The most common mistake made when using the
TrackdAPI is specifying the wrong shared memory segments, or using the wrong
daemon. The TrackdAPI does not do any transformations of data, it only reports on the
data stored by the daemons. The daemons will report trackers’raw data output to be +X
right, +Y up, and +Z back orthogonal to the transmitter’s orientation, which may or may
not be orthogonal to the display device’s orientation. The orientations follow the right
hand rule, with the right hand’s thumb along the axis, the fingers will curl along the
direction of positive rotations. Elevation is around the x-axis, azimuth is around the y-
axis and roll is around the z-axis.

Please send comments/questions to support@vrco.com.

Vous aimerez peut-être aussi