
     Frequently asked questions about GNU Maverik.

The latest version of this document can be found online at 
http://aig.cs.man.ac.uk/maverik/faq.htm

Last changed: 10th January 02

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

Q1: Will Maverik run on <Insert your OS here>?
Q2: Does Maverik support the <Insert Peripheral Here>?
Q3: Does Maverik support the <Insert Graphics Card Here>?
Q4: My Maverik program doesn't seem to work.
Q5: I get a "error in loading shared libraries" or "rld: Fatal
    Error: Cannot Successfully Map soname" error.
Q6: I get a "MAV_HOME environment variable not set" error.
Q7: I get a "can't open avatar curve file walking.cset" error message
    when running the avatar example.
Q8: Why does Maverik run slowly on my old SGI?
Q9: Sometimes after my Maverik application has finished, the keyboard
    repeat is disabled.
Q10: Where are the pull-down menus, sliders and other widgets?
Q11: Why is there no collision detection?
Q12: Can read in objects defined in <Insert File Format Here>?
Q13: My objects appear to be clipped to planes that don't coincide
     with the view frustum - I'm getting objects disappearing when
     they get near the edge of the window.
Q14: Where is Spot The Dog?
Q15: Is Maverik thread-safe?
Q16: What about multi-distributed users?
Q17: Why are there 'get' functions, but no complimentary 'set' functions?
     For example, there is a mav_callbackGetMatrixExec but no equivalent 
     mav_callbackSetMatrixExec?
Q18: I sometimes see a colour banding effect on objects - I get a
     saw-tooth pattern around the edges of objects?
Q19: How are MAV_matrix's implemented/ordered?
Q20: Are applications written for Maverik version 4.x compatible with
     version 5.x?
Q21: How do I recompile modified Maverik soure code, examples, or demos?
Q22: Why are some of the later chapters in the MPG missing?
Q23: Why are some of the functional specifications poorly documented
     or blank?
Q24: Why do the man pages look horrible on SGI's?
Q25: I get an "ld: cannot open -lGL: No such file or directory" error
     when compiling Maverik
Q26: Why does mav_matrixRPYGet give the wrong results?
Q27: Why are the numbers returned by mav_fps and mav_fps_avg incorrect?
Q28: What are the issues when dealing with semi-transparent objects?
Q29: Are applications written for Maverik version 5.x compatible with
     version 6.x?

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

Q1: Will Maverik run on <Insert your OS here>?

Maverik is available as source code and should compile under Windows,
MacOS and on UNIX systems - essentially any system that has OpenGL,
Mesa (version 3.1 or above), IrisGL or DirectX (version 8). However,
while it is possible to use any of these libraries, OpenGL/Mesa is
currently the best supported library for Maverik to use.

Maverik is known to run on RedHat 5.2 and 6.x; FreeBSD 3.2; SuSE 7.1,
Irix 5.3, 6.3 and 6.5; SunOS 5.7; MacOS and Windows 98, 2k and
NT. This list is not intended to be exhaustive but simply reflects
operating systems that we, or others, have access to and tried Maverik
with. Ports to other UNIX platforms should be fairly trivial and we
belive the code to work on Window 95.

Since we at the University of Manchester do not have access to
SunOS, SuSE, FreeBSD, or MacOS; new releases of Maverik cannot be
tested to ensure they will compile error-free on these platforms.

Feel free to contact us if you want more details of exactly what
porting to other platforms would involve.

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

Q2: Does Maverik support the <Insert Peripheral Here>?

A standard compilation of Maverik provides supports for a desktop
mouse, keyboard and screen. This makes it easy to try out the examples
and demonstrations.

The configuration of 3D peripherals used in VR labs tends to be site
specific. Code is included in the distribution to support 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; 5DT data gloves; and a serial
Logitech Marble Mouse. With modification other similar specification 6
DOF input devices/tracking technology can be supported. Code to support 
IBM's ViaVoice speech recognition engine is also provided. This code is
not compiled by default since it is not relevant to everyone and
requires some manual configuration. See the README in the src/extras
directory for more information.

We have also supported more peculiar peripherals in our own lab:
Microsoft SideWinder Force-Feedback joystick and our homebuilt MIDI
server. These are relatively uncommon devices and so are not included
in a "standard" Maverik release. However, if your interested in this
code drop us an e-mail.

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

Q3: Does Maverik support the <Insert Graphics Card Here>?

Maverik ultimately makes calls to a well supported graphics library
(OpenGL, IrisGL or DirectX) to perform its rendering. Therefore, if
these libraries are hardware accelerated by your graphics card, then
Maverik will be accelerated.

For SGI machines this process is seamless. Unfortunately, for PC's
things get a little more complicated. Mesa, the freely available
OpenGL work-a-like, supports hardware acceleration for a number of
graphics boards [see http://mesa3d.sourceforge.net]. Alternatively,
the graphic card vendor may supply drivers. We have verified Maverik
with the following cards: Voodoo, Voodoo2, TNT, TNT2, GeForce 256,
GeForce2 and GeForce 3 based boards. See the Mesa web page for more
information and the README.3DFX file in the Mesa distribution for how
to compile Mesa to take advantage of Voodoo based graphics boards.

Maverik should automatically detect that a Voodoo based card is
present and that hardware acceleration has been requested (it
determines this from the MESA_GLX_FX environment variable). Under
these circumstances, the default window size is changed to a Voodoo
compatible 640x480 and the mouse pointer is restricted, by default,
to stay within the graphics window.

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

Q4: My Maverik program doesn't seem to work.

That's not a question.

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

Q5: I get a "error in loading shared libraries" or "rld: Fatal
    Error: Cannot Successfully Map soname" error.

Maverik libraries are dynamically loaded and therefore you may need to
include their location in the dynamic library search path environment
variable LD_LIBRARY_PATH (or possibly LD_LIBRARYN32_PATH on
Irix6). E.g. 

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/maverik-6.5/lib

You may also need to include the location of the TDM libraries, if
used, in the LD_LIBRARY_PATH.

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

Q6: I get a "MAV_HOME environment variable not set" error.

Errr, like it says, your MAV_HOME environment variable is not
set. Some Maverik applications require this environment variable to
be set to point to the location of the Maverik distribution. E.g.

export MAV_HOME=/usr/local/maverik-6.5

Its good practice to set it regardless of whether your application
requires it or not.

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

Q7: I get a "can't open avatar curve file walking.cset" error message
    when running the avatar example.

Your MAV_HOME environment variable is incorrectly set.

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

Q8: Why does Maverik run slowly on my old SGI?

For older SGI machines (e.g. a Crimson) which are optimized for IrisGL
you need to run the Maverik setup script specifying the IrisGL option:
"setup --IrisGL" to generate a version of Maverik based on this
graphics library.

Note: IrisGL is no longer actively supported and its functionality may
differ from the OpenGL version of Maverik.

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

Q9: Sometimes after my Maverik application has finished, the keyboard
    repeat is disabled.

This problem has been fixed in version 5.4. Thanks to Miklos Szeredi
for providing the patch.

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

Q10: Where are the pull-down menus, sliders and other widgets? 

Maverik is intended to be used to display a 3D "VR world" efficiently
and flexibly. As such, providing GUI functionality for an application
is outside of its scope.

That said, some GUI toolkits provide an OpenGL canvas widget which
Maverik can use as its rendering window. GTK+ and Qt are two such
toolkits (support for other toolkits should be possible). Support for
either of these must be specified to the setup script when compiling
Maverik. See README-GTK and README-QT for more information. There are
examples of using GTK+ and Qt in the examples/misc/GTK and
examples/misc/Qt directories (only compiled if the relevant support is
enabled).

Maverik has also been used with xforms. Here the Maverik rendering
area and the GUI are separate windows - rather than Maverik being a
sub-window forming part of a larger GUI window. There is an example of
using xforms in the examples/misc/xforms directory (not compiled by
default because it need the xform path specifying).

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

Q11: Why is there no collision detection?

At first it may appear strange that the standard Maverik navigation
does not perform collision detection. What you should remember is that
Maverik is a toolkit - it provides you with the functionality to
easily detect if a collision has occurred, but does not dictate what
happens as a result, that bit is upto you.

Its straightforward to implement navigation which performs collision
detection to stop the users movement (an example of this is
implemented in the programmers guide). The advantage of Maverik being
a C toolkit is that it allows you to apply any additional constraints
you wish. For example, collision with an object would only stop the
user if:

(1) its volume was greater than some threshold.
(2) its of a certain shape or colour.
(3) its after 5pm on alternate Thursday's.

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

Q12: Can read in objects defined in <Insert File Format Here>?

Maybe... There are a great number of modelers and file formats out
there, but its not our job to support all of these. In fact, we
support just three - VRML97 [http://www.vrml.org], Lightwave and AC3D
[http://www.ac3d.org].

The VMRL97 parser 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.

AC3D is geometry modeler which, as well as creating and editing
objects, can import them from a number of common 3D file formats
(including 3DS, DXF, Lightwave and VRML1). Other packages, such as
Crossroads and 3DC [there are links to these from the AC3D page], can
translate between many different 3D file formats and the AC3D
format. Thus, supporting AC3D provides a means of easily
creating/editing objects and also indirect support for many common 3D
file formats. Here's the rub - a fully working version of AC3D cost
$40 US.

Of course, there is nothing stopping you writting your own support for
your favorite file format.

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

Q13: My objects appear to be clipped to planes that don't coincide
     with the view frustum - I'm getting objects disappearing when
     they get near the edge of the window.

Your view direction or view up vectors probably aren't normalised. 

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

Q14: Where is Spot The Dog?

Usually under the table. Have a good look.

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

Q15: Is Maverik thread-safe?

Yes and no. The Maverik kernel is not currently re-entrant. It does
not attempt to protect its own data structures from being damaged by
multiple threads attempting to access them at once. So in this sense,
it's not theadable.

However, on GNU/Linux the system could be compiled using the _REENTRANT
libraries and header files, so if you put your own protection around
the Maverik calls, it would be safe to use them in threaded programs.

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

Q16: What about multi-distributed users?

Maverik was designed to provides the management of all the graphics
and peripheral driving capabilities *for a single user* in a flexible,
customizable and efficient manner.

A complementary system under development, Deva, provides a networked
multi-user environment on top of Maverik, with the ability to specify
multiple active environments, laws etc.

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

Q17: Why are there 'get' functions, but no complimentary 'set' functions?
     For example, there is a mav_callbackGetMatrixExec but no equivalent 
     mav_callbackSetMatrixExec?

Maverik doesn't hold it's own copies of data structures, so once
you've 'got' a structure, that really is it. You can do whatever you
like with that structure, and Maverik will just use that. There's no
need to 'put it back' into Maverik.

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

Q18: I sometimes see a colour banding effect on objects - I get a
     saw-tooth pattern around the edges of objects?

These effects are probably due to limited depth buffer resolution and
are particularly noticeable when using, but not limited to, Voodoo
based cards and Mesa.

There are a limited number of bits comprises the depth buffer with the
result that the depth values calculated for two objects whose distance
from the eye is large but similar (or indeed the front and back faces
of the same object if backface culling has not been enabled) can get
quantized to the same value. The result of this is the object or faces
may not be correctly depth buffered leading to one "poking through"
the other. This "poking through" pattern moves around with the eye
point as the depth values of the object/faces get quantized
differently.

There are two ways in which you can reduce this effect:

1) Enable backface culling.
2) Reduce the depth range of your model thus allowing it to be more
accurately represented with the limited number of bits available. This
is achieved through the near and far clip distance set with the
function mav_windowPersepectiveSet. It is more beneficial to increase
the near clip plane distance that to reduce the far clip plane.

The near and far clip distances can be dynamically modified at run
time by pressing Ctrl-F5 to Ctrl-F8 (press Shift-F12 for more
information).

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

Q19: How are MAV_matrix's implemented/ordered?

Easy answer: its unimportant *provided* that you manipulate matrices
via the functions Maverik provides and that you use the results of
these operations as graphical transformations.

Complex answer: 

OpenGL, Maverik and most graphics textbooks use a convention of
postmultiplying by column vectors, i.e. v' = M.v

Maverik stores the matrix, M, as a 4x4 array of floats. Maverik
follows the standard C convention and uses row-majored access to a 2
dimensional array, i.e. M[i][j] refers to row i column j. Thus, the X
translation term of a matrix, the top-right element, is accessed as
as M[0][3].

However, OpenGL expects to receive matrices as column-majored, and
therefore a 2 dimensional matrix implemented in C needs to be
transposed before being passed to OpenGL (see OpenGL programmers
guide). Maverik automatically performs this transpose.

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

Q20: Are applications written for Maverik version 4.x compatible with
     version 5.x?

Possibly. Version 5 handles matrices in the manner described above,
i.e. row majored whereas version 4 used column majored. If you set
matrices via the functions Maverik provides, rather than accessing
individual elements, then this internal change should not prevent
back compatibility. If you do access individual elements, then you
will need to transpose the element indices to make a version 4
application work with version 5, i.e. m.mat[2][1] becomes
m.mat[1][2].

Also, version 5 fixed a bug in which roll and yaw angles were left
rather than right handed. So while the code will still compile and
execute, objects may no longer be oriented as before. Replacing
mav_matrixSet with mav_matrixSetOld will fix this, but it is
recommended that you correct the angles supplied to the 
mav_matrixSet and mav_matrixRPYSet functions.

In version 4 the avatar's hands were specified relative to his body,
version 5 requires them in World coordinates.

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

Q21: How do I recompile modified Maverik soure code, examples, or demos?

The top level Makefile in the Maverik distribution defines various
environment variables before traversing the sub-directories
performing a "make" in each. The Makefiles in the sub-directories rely
on these environment variables and so will not operate correctly if
they are directly executed.

So, if you modify the Maverik source code or examples then to
recompile them you must either: 

(1) type "make" in the top level directory of the Maverik
    distribution, or
(2) Manually set the environment variables and type "make" in the
    sub-directory containing the modifications.

We suggest the first. Traversing the sub-directories where no changes
have been made is a fairly quick process.

The examples rely only on two environment variables, MAV_HOME and CC,
to indicate where Maverik is installed and what complier options to
use (this is documented in the MPG). The demos additionally rely on
the OPENGLINCL and OPENGLLIBS environment variables to indicate how to
include the OpenGL header files and how to link with the
libraries. The Makefiles for the Maverik source code rely on many more
environment variables and setting these by hand in not recommended.

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

Q22: Why are some of the later chapters in the MPG missing?

Maverik is a large system and fully documenting it will take some
time. So far we have concentrated our efforts on the MPG and in
particular what a beginner to the system needs to know. Advanced
usage, such as adding support for new input devices or creating
your own types of SMS, has yet to be documented - its coming though.

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

Q23: Why are some of the functional specifications poorly documented
     or blank?

See above. We have place holders for all of the functions and types in
the MFS, but simply haven't had the time to fully document, and
importantly, cross-link them all. As with the MPG, we have
concentrated on documenting the most common functions. The others are
being steadily added.

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

Q24: Why do the man pages look horrible on SGI's?

Dunno. If I had to guess I'd say something like they use a different
version of groff than pod2man, which created the man pages, was
expecting. Live with it or use the HTML versions until this problem is
fixed.

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

Q25: I get an "ld: cannot open -lGL: No such file or directory" error
     when compiling Maverik

Maverik 5.2 and before linked with -lMesaGL under Linux and
FreeBSD. Version 5.3 and later link with -lGL. This change coincides
with Mesa changing the name of the library it generates (libMesaGL.so
before version 3.1, simply libGL.so after). So, if Maverik can not
find libGL.so upgrade to version 3.1 of Mesa or soft link libGL.so to
be libMesaGL.so

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

Q26: Why does mav_matrixRPYGet give the wrong results?

A. It doesn't, it give the correct answer - probably just not the one
you want :)

The conversion from an orientation matrix to a set of roll, pitch and
yaw values is inherently ill-defined. That is to say there are
multiple sets of RPY values which describe a given orientation - there
is no one-to-one mapping. For example, a RPY of (0, 0, 145) is
mathematically identical to one of (180, 180, 35) in that they both
give the same orientation.

mav_matrixRPYGet returns just one of the many possible RPY values
which can describe a given orientation. This may or may not be the
most "intuitive" set.

If you use all three RPY values together there should not be a
problem. What you cant do is modify one of the values in isolation and
expect to get sensible behaviour.

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

Q27: Why are the numbers returned by mav_fps and mav_fps_avg incorrect?

A: mav_fps is based on the elapsed wall-clock time between the start
of mav_frameBegin and end of mav_frameEnd. (mav_fps_avg is simply
mav_fps averaged over a number of frames).

However, since an OpenGL implementation can buffer commands in several
different locations - including network buffers and the graphics
accelerator itself - the time recorded by mav_fps may not accurately
reflect the time it would take for the commands to complete.

In order to get an accurate time mav_frameEnd must wait until the
effects of all previously called OpenGL commands are completed. This
can be achieved by setting mav_opt_finish to MAV_TRUE.

Also, this buffering effect needs to be taken into account if you are
timing a sequence of graphics commands, for example in order to abort
rendering after a given elapsed time. The mav_gfxFinish command can be
called to flush the command buffers and wait until their effects have
been realised.

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

Q28: What are the issues when dealing with semi-transparent objects?

A: In order to correctly deal with semi-transparent objects the
application must set the mav_opt_trans variable to MAV_TRUE before
initialising Maverik.

With this enabled a check is made before each object is rendered to
determine if it is semi-transparent. If it is not, the object is
rendered immediately; if it is semi-transparent then the object is not
rendered but stored in a list for processing later.

At the end of the frame, after all opaque objects have been rendered,
the list of semi-transparent objects is traversed. These objects are
rendered in back-to-front order - that is the furthest object from
the eye point is rendered first, the closest to the eye point last.

In order for Maverik to determine if an object is semi-transparent it
executes the getSurfaceParams callback on it. Similarly, the BB
callback is executed to obtain the object's bounding box (and hence
position) in order to perform the depth sorting. A user-defined class
of object would need to provide both of these callbacks if the object
is to be correctly treated when semi-transparent.

Note that semi-transparent objects which overlap in space may not
appear correctly since the depth sorting effectively treats each
object as a point.

Backface culling should be enabled when using semi-transparent objects
to avoid the "far-side" of the object being visible.

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

Q29: Are applications written for Maverik version 5.x compatible with
     version 6.x?

A: No, but the changes you need to make to a 5.x application in order
for it to work with Maverik 6.x are quite small and mechanical:

1. Initialisation - mav_initialise in 5.x has been renamed to be
mav_initialiseNoArgs in 6.x and mav_initialiseArgs in 5.x has been
renamed to mav_initialise in 6.x.

2. Frame functions - The prototype of MAV_frameFn changed in 6.x to
allow arbitrary data to be passed to the function. The easiest way to
upgrade any such functions from 5.x to 6.x is to make them take an
ignored void * parameter and to call the mav_frameNAdd/Rmv functions
with a NULL argument. So, 

  void fn(void)
  mav_frameFn0Add(fn);

in 5.x becomes:

  void fn(void *ignored)
  mav_frameFn0Add(fn, NULL);

in 6.x.

3. TDM - TDM libraries are now specified at run time and dynamically
loaded rather than being statically linked into Maverik. See
examples/misc/TDM/tdm.c for an example of how the library is
specified.
