Bob's Anatomy

Bob is split into several sections:

1) Main control and user interface (bob.c)
2) Initial setup (setup.c)
3) Reading and manipulating the voxels (vox.c)
4) Drawing Voxels and other geometry (draw.c)

In addition, there are some libraries:

1) General utilities (util.c)
2) X and Xt utilities (xtutil.c)
3) SGI Gl utilities, vector operations, and Trackball (glutil.c)
4) Skip lists (skip.c)
5) Simple text parser (parse.c)

All .c files have a companion .h file, where the external functions and
data structures are defined for other module's use.


##################### Library #####################

-- util.c --

MIN, MAX and ABS macros.

Simple macros for allocating memory and checking to see if a valid
pointer is returned.  Bob does not attempt to recover from out of
memory conditions - a malloc failure is fatal.

A basic string duplicator.

A version of atol() that understands the characters 'k' and 'm'.

Simple integer functions for rounding up a number and factoring.

A timer that returns milliseconds between calls.


-- skip.c --

Skip lists are an extension of linked lists that have O(log(n)) search
time, like balanced trees.  The original papers are by Bill Pugh.  I
use SkipLists and their ordered cousin, SkipStacks, whenever I need a
sorted list, array or stack of pointers (i.e. objects).


-- xtutil.c --

Several misc funtions for centering dialogs, determining the shell and
top level widget given any widget, and getting and setting resources
cleanly (supplanted in X11R4 by XtVaSetValues...).

Colormap opperations.

Handy callbacks to manage, unmanage, and sensitize widgets.

Most important, the automatic widget tree builder.  To save programming
labor, the widget tree is built from a table instead of hundreds of
calls to XmCreate....

All of the widget attribute information that can be in the application
defaults file *is* in that file.  For stand alone operation, the
app-defaults file is pre-processed into a list of strings, to be used
as fallback resources in the code.

The function GetWidget is frequently used to lookup a widget based on
its name.  This makes for cleaner code - widgets are always refered to
by name.


-- glutil.c --

Lots of small functions for manipulating 3D vectors, like vadd, vsub,
vcross....

Some quaternion counterparts to the vector funtions.

The Trackball data structure and library, which implements a virtual
trackball using quaternion rotations.

A few GL utilities: dumping window to a file, getting the total view
matrix, dtermining the primary view axis, and setting up Stereo.


-- parse.c --

Simply parses a line from a stdio FILE into a SkipList of strings.
Handles quotes, comments and line continuations.



##################### Bob #####################

-- setup.c --

The main() function is in bob.c, but the first thing it does is call
SetupBob() in setup.c.

SetupBob gets the program off the ground.  It starts up Xt, parses the
command line, builds the widget tree, reads and parses a defaults file
if needed, reads in list of volume files and optional colormap file,
reads from the first file into a volume, and sets the interface to
match the state of the program.

bob.c may, while the program is running, use the defaults file reading
routines and file list reading routines if neeed.

Bob usies the GLX widget.  For the most part Bob is a standard Motif
program.  During Init and Expose callbacks to GLX widgets however
SGI gl rendering calls are permitted.


-- bob.h --

All of the global data inthe program is held in one (too large)
structure, BobApp, and is accessible via the global pointer bob->?.

There is a list of files and a list of frames, with one volume
per frame and possible more than one frame per file.  Each file
entry has a file name, offset, data size, device block size
(for raw disk reading), number of frames in that file, and the
number of the first frame.

Each frame has a pointer back to its file, and a total byte offset
into that file from whence to read.

The estimated rate at which the hardware can draw polygons is kept
in fastRate.  This ideally should be computed on the fly.  The 
standard view variables, like field of view and stereo separation,
are variables so that they can be adjusted fromthe command line/
defaults file.

There are three rendering windows where gl calls are made:  the main
voxel window (vwin), the stero window (swin), and the finder window
(fwin).  The voxel and finder windows have their own Trackballs 
that are ganged for rotation (but not zoom and translation).
The stereo view shares the voxel view's Trackball.

At any time there is a pointer to the current frame, which determines
which file and offset to read from.  The current voxel data is stored
in cdata, with three total copies (one for each principal direction).

The animation feature requires a bunch of state variables to be kept
around, all not very interesting.

The current color and opacity tables are kept in ctab and atab.


-- bob.c --

Much of the main bob file is concerned with handing the interface
widgets.  

The Xt selection mechanism is used to communicate the colormap
from icol to bob.

Animation is fairly simple, a work procedure keeps the volume rotating,
and changing data if needed, and signals the drawing code to save the
image after rendering (but before swapbuffer()!).


