
   GNU Maverik - a system for managing display and interaction in 
                 Virtual Environment applications.

                     Advanced Interfaces Group
                 The University of Manchester (UK)
                      http://aig.cs.man.ac.uk
		      maverik@aig.cs.man.ac.uk

Caveat:
  Maverik is not an end-user application. If you are looking for a 3D
  game to run, you will be disappointed with Maverik. If you want to
  develop a range of VR applications, then Maverik may be what you want.



Introduction
============

In its simplest form, GNU Maverik is a C toolkit for managing
display and interaction in stand-alone (that is, non-networked)
single-user Virtual Environment applications. A complementary system
under development, Deva, provides a networked multi-user,
multi-environment layer on top of Maverik, with the ability to
efficiently specify behaviour, laws etc. As of release 4.3, Maverik is
an official component of the Free Software Foundation's GNU Project
located in Boston, USA.

There are numerous other "VR toolkits" available, ranging from very
low-level libraries of functions for drawing three-dimensional
graphics and interacting with peripherals, to fully-blown "systems"
that describe virtual environments in much higher level terms. Maverik
lies somewhere in between these extremes. It provides an application
with the tools needed to create, manage, view, interact with, and
navigate around graphically complex Virtual Environments while making
the minimum number of assumptions about the nature of the application.

Maverik does not dictate the use of any fixed object/scene
representations or viewing/interaction techniques. Rather, it has the
ability, where needed, to directly link into and exploit an
application's own data structures and algorithms. This novel aspect of
Maverik allows it to easily take advantage of representations,
optimisations, and techniques that are highly application specific
giving the resulting virtual environment a behaviour which is
customized to, and consistent with, the nature of the application.

Maverik's flexible design means that applications with widely
differing requirements can be supported.

Maverik has two components:

1) a micro kernel, which provides the framework within which
applications are built;

2) a collection of supporting modules, which provide optimised display
management, culling, spatial management, interaction and navigation
techniques, control of input and output devices etc. These modules are
distributed as source code and act as a basis for customization.

It is important to appreciate that Maverik is not an "end-user
application": there are no graphical user interfaces or "world
editors" - it is strictly a programming tool.

See FAQ for a list of supported platforms and peripherals.



License
=======

This software is distributed under the terms of the GNU General Public
License, see the COPYING file for details. However, as the copyright
holders of the original Maverik source we are able to distribute
non-GPL'd versions of (our version of) Maverik under a commercial
license. See http://aig.cs.man.ac.uk/maverik/non-gpl.php for
more details.



Obtaining the software
======================

Maverik is available for download from http://aig.cs.man.ac.uk/maverik/download.php
and is distributed in two parts:

1) maverik-6.2.tar.gz - which contains the source code, include files,
documentation and example code for the system.

2) maverik-demos-6.2.tar.gz - which is optional, but recommended, and
contains a number of demonstration programs.

Zipped versions are also available for compiling on Windows.



Building and testing the system
===============================

See the INSTALL file.



Contact
=======

Comments, questions and feedback are actively encouraged and should be
addressed to us personally at maverik@aig.cs.man.ac.uk, or to the
Maverik user's mailing list (see http://aig.cs.man.ac.uk/contact.php for
details).



Reporting bugs
==============

Before reporting a bug make sure that you are using the latest version
of Maverik and that you have checked the FAQ and list of known bugs
(see below).

If, after this, you are still experiencing the problem then report the
bug to bug-maverik@aig.cs.man.ac.uk, or to the Maverik user's mailing
list (see above).



Known bugs/features/limitations/work-arounds
============================================

See http://aig.cs.man.ac.uk/maverik/bugs.php for the latest
information.

(1) On Solaris if you compile with gcc you may get an undefined
    reference to __eprintf. Changing the linker defined in the setup
    script from "ld -G" to "gcc -G" should overcome this problem.

(2) The VRML97 parser can sometimes lock up while trying to free
    memory. Set mav_opt_VRML97CleanUp to MAV_FALSE to prevent this.

(3) Some graphics cards have problems allowing multiple windows (eg
    stereo) to share a single graphics context. Try setting
    mav_opt_shareContext to MAV_FALSE to overcome this.

(4) Some versions of the NVIDIA drivers have problems in defining
    fonts (which results in an immediate core dump when running
    Maverik). Make sure you are using the latest drivers. If this
    fails to fix the problem make mav_gfxWindowFontSet in
    src/gfx/mav_gfxWMOpenGLX11.c immediately return -1 to stop it
    attempting to use fonts.

(5) PNGs can loose their transparency if convert is used to resize them.

(6) In order for HUD objects to be intersected correctly (for event
    callbacks to be triggered) the window in which they are in needs
    to be the active rendering window (see mav_windowSet). This limits
    then use in multi-window applications.

(7) Some versions of gcc-2.96 can fail to compile Maverik, they give
    the error "excess elements in scalar initializer". Make sure you
    are using the latest version of this compiler, which at the time
    of writing is 2.96-69.



Authors and contributors
========================

The following people are responsible for the design, development and
implementation of Maverik (in alphabetical order): Jon Cook, Tim
Davis, Simon Gibson, Toby Howard, Roger Hubbold, Martin Keates, Alan
Murta, Steve Pettifer, Adrian West. We are also indebted to the many
valuable contributions of the following research students: Mat Brooks,
Mashhuda Glencross, James Marsh, Gary Ng, Dan Oram, James Pearce,
James Sinnott and Dongbo Xiao.

We would like to thank the following people for contributing to
Maverik:

Robert Belleman - Solaris support.
Shamus Smith - ISOTRAK II support.
Joerg Anders - Windows support.
Alex - MacOS support.
Joe Topjian - FreeBSD support.
Jake Burkholder - FreeBSD support.
Rob G - FreeBSD support.
Daniel Amos - Ascension Flock of Birds support
Alessandro De Luca - SpaceOrb360 and 5DT data glove support

and to everyone who mailed us with bug reports and fixes.



Thanks
======

The authors would like to take this opportunity to thank the UK
Engineering and Physical Sciences Research Council (EPSRC) for funding
the VRLSA (GR/K99701) and REVEAL (GR/M14531) projects; the ESPRIT
programme for funding eSCAPE (ESPRIT 25377); our academic research
partners at the Universities of Manchester, Lancaster and Nottingham,
the Swedish Institute of Computer Science, and ZKM in Karlsruhe; our
industrial partners CADCentre Ltd, Sharp Laboratories of Europe Ltd,
Brown & Root, Greater Manchester Police and Harlequin Ltd.
