
     Frequently asked questions about GNU Maverik.

The latest version of this document can be found online at 
http://aig.cs.man.ac.uk/systems/Maverik/FAQ.html

Last changed: 19th March 99

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

Hardware Support:

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>?

Running:

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.

General:

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?

Documentation:

Q19: Why are some of the later chapters in the MPG missing?
Q20: Why are some of the functional specifications poorly documented
     or blank?
Q21: Why do the man pages look horrible on SGI's?


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

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

Maverik is available as source code and should compile on any UNIX
system that has OpenGL (and/or IrisGL on SGI's) or Mesa (version 3.0
or above) and X11 libraries.

Maverik is known to run on GNU/Linux; Irix 5.3, 6.3 and 6.5; and SunOS
5.7. This list simply reflects operating systems we, or others, have
access to and tried Maverik with - ports to other UNIX platforms
should be fairly trivial. Since we at the University of Manchester do
not have access to a SunOS machine, new releases of Maverik cannot be
tested to ensure they will compile error-free on this platform.

A while ago we also successfully compiled Maverik for Window95, but
this support has lapsed since we work exclusively on UNIX based
machines. Re-porting Maverik to this platform should be relatively
easy, but is not a priority for us.
  
Feel free to contact us if you want more details of exactly what
porting it to other platforms would involve.

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

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

A standard compilation of Maverik only provides supports for a desktop
mouse, keyboard and screen at the moment. But since Maverik is
designed to be expandable, there may be new peripheral support in the
future.

Code is included in the distribution to support Polhemus 6 DOF
trackers, Division 3D mice, Spacetec SpaceBalls and, with
modification, other similar specification 6 DOF input devices/tracking
technology. This 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.

Furthermore, here at University of Manchester we have written support
for a wide range of other peripherals: IBM ViaVoice speech recognition
system; Microsoft SideWinder Force-Feedback joystick and our homebuilt
MIDI server. These are relatively uncommon devices and so are not
suitable for inclusion 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>?

This is an OpenGL issue since Maverik ultimately makes OpenGL calls to
perform its rendering. Therefore, if the version of OpenGL you are
using on your system is 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://www.mesa3d.org]. However, we have only
verified it with Voodoo and Voodoo2 based boards. Note that Mesa's
support for these boards is in a preliminary state. See the
README.3DFX file in the Mesa distribution for what is needed and how
to compile Mesa to take advantage of these graphics boards.

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

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-4.3/lib

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

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-4.3

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, linking your program with -lmaverik (which uses OpenGL)
could lead to poor performance. To link your program with IrisGL,
replace "-lmaverik" with "-lmav_objects -lmav_navigation
-lmav_windows -lmav_sms -lmav_callbacks -lmav_kernel
-lmav_gfxIrisGL". Not as neat as just "-lmaverik", but we have
optimized the linking for the common case of using OpenGL. Look at
Makefile in the top level source directory for how the single Maverik
library is made. Its trivial to modify this to use IrisGL.

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

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

In order to handle keyboard events correctly, Maverik needs to disable
the keyboard repeat whilst it's running. If the application closes
down correctly, i.e. via the exit command, Maverik will restore the
repeat. If your application crashes in some way, or is killed off in
such as way that the exit handler isn't called cleanly, then you'll
find that the keyboard repeat isn't restored. You can do it by hand
using "xset r" from a command shell though.

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

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, a Maverik application can make use of GUI toolkits, such as
xforms, to provide this functionality (there is an example of this in
the examples/misc/xforms directory). With a bit more work Maverik can
be more tightly integrated with xforms so that its uses the xform
OpenGL canvas widget as the Maverik rendering window.

Similarly, Maverik can be customized to use GLUT to open its rendering
window, and thus make use of its pull-down menus etc..

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

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 two - VRML97 [http://www.vrml.org] and AC3D
[http://www.comp.lancs.ac.uk/computing/users/andy/ac3d.html].

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 is compiled using the _REENTRANT
libraries and header files, so if you put your own protection around
the Maverik calls, it is 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 in 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.

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

Q19: 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.

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

Q20: 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.

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

Q21: 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.

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