
This directory contains the source code to supporting modules which
are (hopefully) useful but which are not part of the "core" Maverik
system.

These module may require manual configuration and/or the presence of
additional software.

----------------------------------------------------------------------

Avatar - the Maverik avatar.

This module does not require any configuration and is compiled by
default. An example of its use and the features it provides can be
found in examples/misc/avatar.

----------------------------------------------------------------------

TDM - Three D Mice support.

This module contains source code to provide (hopefully) generic
support for 6 DOF input devices/tracking technology, collectively
called "Three D Mice". 

The code in this module is independent of the input device used,
i.e. given the status of a device; the maths of mapping it's position
into the world coordinate frame; and, where applicable, rendering a
cursor at this position; setting the orientation of the view direction
to match that of the device; creating callbacks to allow objects to
respond to events generated by the devive; determining which object
the device is pointing at etc...

The interface to the device to obtain it's status is provide by a
separate dynamically loaded library which defines the following 4
functions: TDM_init, TDM_getPosition, TDM_getButtons and
TDM_getEvent. These function respectively initialize the device, get
it's position/orientation, button status and check for button events.

These routines could be little more than wrappers to the MR tookit
with the "getButtons" and "getEvent" calls doing nothing if the
device has no associated buttons. Alternatively, this functionality
could be provided by some existing library or by something that came
from the device's manufacturer.

Our home-made implementation of these functions is available for
download from our ftp site and supports Polhemus FASTRAK and ISOTRAK
II six degree of freedom trackers (optionally coupled to Division 3D
mice); Ascension Flock of birds (ERC only); Spacetec SpaceBalls and
SpaceOrb360s; Magellan Space Mouse; InterSense InterTrax 30 gyroscopic
trackers; and a serial Logitech Marble Mouse. This code is designed to
work with our setup -- you will need to modify it for your site setup
even if you have the same equipment, e.g. serial port and baud rates,
transmitter orientation, number of Polhemus trackers, which trackers
are associated with the mice? etc...

The main Maverik setup script takes the arguments --TDMPATH to
indicate where TDM is installed. For example:

  --TDMPATH=/usr/local/TDM-2.0

The mav_opt_TDMLib variable indicates which TDM library to dynamically
load. For example:

  mav_opt_TDMLib= "/usr/local/TDM-2.0/lib/libtdm-polhemus.so";

An example of using TDM can be found in examples/misc/TDM.

----------------------------------------------------------------------

TR - Tiled Rendering support.

Brian Paul's OpenGL Tile Rendering Library is a mechanism for generating
arbitrary resolution images without the need to allocate a
full-sized image buffer in main memory. It works by subdividing the
source image into an arbitrary number of tiles each of which is
rendered at full window resolution. An application can process, for
example, write to disk, each of the separate tiles.

Maverik can use this library to produce anti-aliased images by scaling
the individual tiles and stitching them together to form an image the
same size as the original. Alternatively, it can generate an arbitrary
resolution image file.

The Tile Rendering Library is available via ftp from
ftp.mesa3d.org/mesa/misc/ 

To use the Tile Rendering library with Maverik you will first need to
create a library file from the object file the TR compilation
produces, i.e. you will need to do something like "ar rvs libtr.a tr.o".

The main Maverik setup script takes the arguments --TRINCL and
--TRLIBS to indicate where to find the TR include and library
file. For example:

--TRINCL=-I/home/people/cookj/tr-1.1
--TRLIBS=-L/home/people/cookj/tr-1.1 -ltr

An example of its use may be found in examples/misc/TR. To take a snap
shot press Ctrl-F11 and follow the instructions.

This module is one of the few that can be meaningfully dynamically
loaded into an existing application via the Ctrl-F12 key press.

----------------------------------------------------------------------

VRAD - VRAD support.

This module provides support for displaying models that have been
processed with the VRAD radiosity code [http://www.cs.man.ac.uk/~gibsons]

Since this code is in-house, this module is of little interest to
anyone else. An example of the type of model produced by VRAD can be
found in demos/AIGLab (if you downloaded it).

----------------------------------------------------------------------

VRML97 - VRML97 support

This module provides support for defining composite objects from
VRML97 files. The code uses the free CyberVRML97 for C++ library by
Satoshi Konno (http://www.cyber.koganei.tokyo.jp/top/index.html). 
VRML97 support is *not* enabled by default - you must specify its use
when installing Maverik. See INSTALL file for more details. Only the
geometry of VRML97 files is read, no attempt is made to parse scripts,
URL's, viewpoints etc... Furthermore, not all of the numerous ways in
which the geometry can be defined are supported, e.g. concave
polygons, colour-per-vertex.

----------------------------------------------------------------------

hud - a head up display

This module implements a simple head up display. See the corresponding
example in the misc directory for how to use it.

----------------------------------------------------------------------

lwo - Lightwave support

This module provides support for defining composite objects from
Lightwave files. The following features are currently un-supported:
doublesided surfaces, textures and smoothing thresholds.

----------------------------------------------------------------------
