
Functions the library needs to provide
======================================

A TDM library needs to provide the following functions: TDM_init,
TDM_getPosition, TDM_getButtons and TDM_getEvent. These function
respectively initialize the device; gets the position/orientation of a
single "tracker" (a device consist of up to TDM_MAX_TRACKERS
(currently 10) independent trackers); get the button status (each
tracker can have up to TDM_MAX_BUTTONS (currently 10) buttons); and to
check for button events. The prototypes to these functions can be
found in the tdm.h include file.

The TDM_init function is executed when the Maverik TDM module is
initialised. TDM_init should return a TRUE value for successful
initialisation, a FALSE value otherwise.

At the start of each frame, TDM_getPosition is called for each of the
TDM_MAX_TRACKERS trackers. 

mav_eventsCheck calls TDM_getEvent to determine if any button events
have occurred. TDM_getEvent should return a TRUE value if an event has
occurred and the event should be detailed in the data structure passed
to it. If no events are oustanding than TDM_getEvent should return a
FALSE value. mav_eventsCheck arranges for any relevant callbacks to be
executed.

TDM_getButtons is executed only in response to mav_TDMButtonQuery been
called by the application.

The TDM library specified by the mav_opt_TDMLib variable in the
Maverik application is dynamically loaded when the Maverik TDM module
is initialised.



Maverik variables (should really be in the Maverik documentation)
=================

Maverik uses the above functions to maintain 3 global variables:

1) mav_TDM_pos - an array of type MAV_TDMPos and size TDM_MAX_TRACKERS
   which holds the raw information on each tracker, i.e. their
   position/orientation in their own coordinate frame. Orientation
   comes in 3 forms, directional vectors, matrix and quaternion for
   ease of use.

2) mav_TDM_matrix - an array of type MAV_matrix and size
   TDM_MAX_TRACKERS which holds the position/orientation of each
   tracker in the world coordinate frame (see below for mapping).
   Setting an object's matrix to one of these value will make the object
   follow the position and orientation of a tracker.

3) mav_TDM_vp - an array of type MAV_viewModifierFn and size 
   TDM_MAX_TRACKERS which holds a view modifier function for each
   tracker, i.e. setting a view parameter's mod field to one of
   these functions modifies the view so that it takes on the
   tracker's world coordinate position and orientation -- a HMD
   look-around facility.

The Maverik TDM include file (mav_tdm.h) contains #defines to
translate the tracker numbers in something more meaningful:

#define MAV_TDM_RED  0
#define MAV_TDM_BLUE 1
#define MAV_TDM_HMD  2
#define MAV_TDM_VEL  3

since in our setup we have a red 3D mouse associated with Polhemus
tracker 0, a blue 3D mouse associated with Polhemus tracker
number 1, our head mounted display uses Polhemus tracker number 2 and
we have a spare Polhemus tracker, number 3, attached to a piece of
Velcro. Obviously you can edit these to reflect your site setup.



World coordinate position (should really be in the Maverik documentation)
=========================

Maverik calculates a tracker's world coordinate position as follows:

The local coordinate position is subtracted from an origin and then
independently scaled for each axis. The resulting X,Y,Z values 
are used as offsets, from the eye position, along the view right vector,
view up vector and negative view direction vector respectively. An
additional offset along the view direction vector is then applied to
give the tracker's world coordinate position. 

The defaults are: origin (0,0,20), scaling factor (1,1,1) and offset (20). 
These values reflect our Polhemus setup where an intuitive origin for
a tracker is to position it 20 inches (half of its usable range)
away from the center of the transmitter along the positive Z axis. The
offset is such that with the tracker at this origin, its world
coordinate position is 20 units from the eye point along the view
direction. With the tracker at 40 inches from the transmitter (its
effective accurate range) the world coordinate position maps to the
eye point.

A cursor can be rendered at the tracker's world coordinate position as
demonstrated in ${MAV_HOME}/examples/misc/TDM/tdm. This cursor is also
rendered with a certain scaling factor, the default being 1.

However, consider the effect of halving the position scaling, offset
and rendering scaling factors. This cursor will be positioned half as
close to the eye point and with half the offsets along the viewing
vectors, and since the cursor is drawn at half its previous size, on
screen it will appear exactly as before. The important difference
being that now the cursor is draw 10 units away from the eye instead
of 20. 

The various scaling and offset factors can be used to position the
cursor closer to or further away from the eye point without effecting
it's apparent size or position on screen. This allows applications to
define cursors which can "go inside" objects or, by using a small as
possible scaling factor, are always rendered in front of the
application objects.

All of these factors are user-definable, see mav_tdm.h.
