Académique Documents
Professionnel Documents
Culture Documents
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.
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
virtual ~TrackerReader()
Detaches from the tracker shared memory segment.
int trackdGetNumberOfSensors(void)
Returns the number of sensors the tracker daemon is storing.
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
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.