Virtual Reality Homebrewer's Handbook/vr.iso/vr386/vr386.doc

Text File | 1996-03-19 | 13KB | 274 lines

WHAT IS VR-386?

VR-386 is a freeware VR program for the IBM PC (386 and higher)
compatibles.  It supports many VR devices, including stereo
flicker glasses, HMDs, the Nintendo PowerGlove, joysticks, and
so on.  VR-386 has the fastest drawing speed of any VR software
in its class, exceeding 20,000 polygons per second.

VR-386 is being developed by Dave Stampe, and is an ongoing project
which hopefully will bring in other programmers to contribute small
sections of the functionality (see the programmer's notes later).
VR-386 is descended from REND386, which was developed by Dave Stampe
and Bernie Roehl, which is documented in the book "Virtual Reality
Creations", published by Waite Group Press.  VR-386 supports most of
the features in the VRC release (version 5), and adds new features.

NEW FEATURES

Some of the new features of VR-386 include its better timebase for
timing and control, its better internal organization for future
upgrades, and its simplified programmer interface.  Perhaps most
important VR-386 supports EMM386 for up to 4 megabytes of memory for
object storage.  This compensates for the large memory use of VR-386
caused by its extensive use of caching to increase rendering speeds.

Many future enhancements are planned, as listed below.  Most important,
VR-386 represents a new beginning and new commitment to programmers
after the problems of REND386.


INTERNAL REWRITES

Where VR-386 differs from REND386 is in its internals.  While REND386
explored new ideas in VR and developed techiques for high-speed
software implementation of graphics and interfaces for VR, it was very
difficult to program with.  Full source code availablilty wasn't enough.
VR-386 begins the process of reorganizing and cleaning up the code to
make it accessible to programmers.

About 90% of the old code has been rewritten by Dave Stampe, who
developed most of the original algortihms for REND386.  This rewrite is
aimed at cleaning up many of the programming style problems with the
original code.  By removing much of the inline assembler, the
dependance on Borland C will be lessened.  By using special API data
types (discussed later) it should be easier to use libraries in many
C compilers and to eventually port the code to 32-bit comilers such as
Watcom C32.

Internally, the super-fast integer/fixed-point math routines have been
expanded and split off into a seperate library.  This unit is completely
stand-alone, so may be used in other projects.  The renderer code has
bee completely rewritten, with all in-line assembler split off into
seperate .ASM files and the code reorganized for clarity.  The renderer
requires only simple support (drawing) routines from the video drivers
and integer math library to function.  It should be much easier to add
extensions to the renderer now.

The PC interface and devices have been rewritten to be more robust
in operation and to use new methods for joystick and timer control.
New devices such as a key-status monitor improve the responsiveness
of the user interface.


THE API

One of the difficulties for programmers with REND386 was its many
data structures and the complex relationships between them.  While
this maximized efficiency of execution, it made learning to program
tough.  Also, upgrading was made complex because many function calls
depended on data structure capabilities.  Finally, the extensive
interdependencies of modules made modification or creation of new
programs very difficult.

To solve this, and to make adding future extensions possible, an
API (application programming interface) was used as the basis for
the VR-386 function prototypes.  The API hides much of the
implementation of VR-386 from programmers (it is still available,
of course, by direct programming).  At this moment, the API is
not yet fixed: the final form of the API is open for input.

The API uses a few simple types to implement common operations.  These
are the most important new types:

OBJECT:  combines visible objects (fixed and moveable) and invisible
moveable "objects" (old segments) into linked object structures.
OBJECTs can have types, be related and so on.

POSE:  rather than trying to handle position and motion by six
variables per object, the POSE structure handles all motions and
positions in the world.  This structure will be crucial for thee
animation part of the API (under development).

CAMERAS:  these encapsulate the entire idea of drawing, stereoscopy,
and viewpoints.  CAMERAs have many characteristics, can be attached to
objects, moved to a POSE, and so on.  They are much like objects.
Screen updating has been split off into several user-modifiable
modules to preclear and add overlays to the screen after rendering.
Stereoscopic cameras are supported transparently, and stereo
rendering is even more flexible.

LIGHTS:  are an object-like item as well.  They should be very extendable,
and are supported by user-modifieable parts of the VR-386 code.  For
now, a single list of lights per world is supported, but future versions may
expand this.  Three types of lights are supported: ambient, point
(which may be positioned), and directional spot lights (which are
rotated).  These lights may be moved or attached to objects as well.

TELEPORTS:  User movement is very important for flexible use of
virtual worlds.  The user's body is now built in to VR-386 as
the default, with the body consisting of a rotatable head for
head-tracker support for HMDs, and moveable hand for glove or
manipulator support.  The body may be attached to and moved by objects
in the world as well.  By default, the body is invisible, but objects
may be attached to it if desired.
  The TELEPORT is a way of formalizing jumps in user position.  This is used
to implement the old "cameras" in REND386.  CAMERAS are now disembodied
viewpoints, which may be attached to visible objects if desired.  The
TELEPORTs act to record and restore user positions in the world, and
also restore body connections to omoving objects the body may have been
"riding".  In the future, teleports will also be able to switch between
WORLDS.

WORLDS:  Development of WORLDs is just beginning in this preliminary release.
A world consists of visible objects, invisible objects, SPLITS
for subdivision and visibility control, and inactive (hidden) objects.
The idea of inactive objects is to remove objects from all world drawing and
support, yet keep them available for quick adding and deleting.  In the
future, multiple WORLDs will be loadeable, and entire WORLDS may be deleted
from memory with with one call.  The development of SPLITs from a
minor visibility control role to an important role in world design
and motion control will be important in future releases as well.


USER INTERFACE:

The user interface has been rewritten to make updates easier.  The menu
interface has been streamlined with a more modular key processing structure,
better methods for cursor and screen restoration, and so on.  The ability to
select objects with the mouse has been greatly simplified, and object
vertices may be selected as well.

Movement of the user via keys, joystick, and other devices has been
integrated.  All motion is now done with POINTER devices and a
navigation processor.  These POINTER devices are common to 2D and 3D
manipulation, and are simple to write.  Future releases will integrate
3D navigation devices as well.

In general, look at MAIN.C and KEYBOARD.C to see how to change the
user interface.


MODIFICATION OF SOFTWARE:

The most important goal of VR-386 was to make it easy to create new programs
that share most of the features of VR-386 while making it easy to
drop or change unwanted features.  You can see an example of this in
the MINIDEMO project, which has only a few changed modules.  These
changes mostly drop support for the PowerGlove, simplify the menu
interface, and automatically load and switch figures in and out of the
world.  Only a few modules are changed, and this entire project was
done in less than 2 hours.

To start using the VR-386 code in your programs, read the VR_API.H
file.  This documents all of the API functions in more or less detail.
Print out and read this file-- you'll be glad you did!

If you want to use the renderer core, print out RENDERER.H, and INTMATH.H
for documentation of the integer/fixed/matrix/trig library.


DEVELOPMENT:

This release of VR-386 is meant for evaluation only.  The idea is to
gather comments on the API interface, to list future expansions and
so on.  If you write code with it, remeber that some parts of the API may
change soon.  After this, API changes will only be addition of new
functions.

There are severasl steps to be done before final release.  These include
more commenting, use of the API types throughout the code, and adding
some functionality.  Changing of syntax of DOS C functions to Microsoft
standard (i.e. disable() becomes _disable() ) will increase portability
between compilers.

The development of VR-386 will be more strict than REND386 was, to make
it possible to integrate new capabilities into VR-386.  If you ever want
your code to remain compatible with (and possibly to be integrated with
main releases of) VR-386, follow these rules:

- NEVER modify any modules that are hidden by or part of the VR-386
API.  You can change MAIN, KEYBOARD, and USCREEN, USERVID and COLORMAP
if needed, but remember to rename these first.  ANY other modules
that are changes should be renamed, and any functions in them
that are modified renamed as well.  Best of all, have ONLY changed
routines in new modules.  The idea is to be able to trace changes and
their dependancies.

- If you want to add basic features to VR-386, talk to Dave Stampe
([e-mail]) first.  Someone else may be working on
such a feature.  It is also important to use an interface that matches
the API, which should be designed and approved in advance.  It's
amazing how interface specification affects how code is written.

- Be efficient!  There has been a lot of effort spent in VR-386 to
use the fastest possible algorithms.  If your code slows down
VR-386, it will not be included or will be rewritten or replaced.
Sorry, but there have to be standards.  If in doubt, discuss your
kernal code with me first.
Also, please be concise with your code.  There is no reason to
create huge modules that duplicate existing functionality.  Use
the integer/matrix math library where possible.

- Debugging:  be sure your code is tested and causes NO crashes,
and has no known bugs.  I don't really have time to debug code:
in fact the hardest part of and development effort is in puzzling
out other's code.


COPYRIGHT AND LICENSE:

 This code is part of the VR-386 project, created by Dave Stampe.
 VR-386 is a desendent of REND386, created by Dave Stampe and
 Bernie Roehl.  Almost all the code has been rewritten by Dave
 Stampe for VR-386.

 Copyright (c) 1994 by Dave Stampe:

 CONTACT: [e-mail]

 Dave Stampe ([e-mail], [e-mail])
 is completing his doctorate at University of Toronto, and does a
 lot of contract programming and development.  Most of this is in
 other fields than VR, but there is a lot of knowledge transfer
 to and from REND386.  Dave is maintaining the VR-386 project for
 programmers.  Send any code or comments to him.


LICENSE:

 May be freely used to write software for release into the public domain
 or for educational use; all commercial endeavours MUST contact Dave Stampe
 ([e-mail]) for permission to incorporate any part of
 this software or source code into their products!  Usually there is no
 charge for under 50-100 items for low-cost or shareware products, and terms
 are reasonable.  Any royalties are used for development, so equipment is
 often acceptable payment.

 ATTRIBUTION:  If you use any part of this source code or the libraries
 in your projects, you must give attribution to VR-386 and Dave Stampe,
 and any other authors in your documentation, source code, and at startup
 of your program.  Let's keep the freeware ball rolling!

 DEVELOPMENT: VR-386 is a effort to develop the process started by
 REND386, improving programmer access by rewriting the code and supplying
 a standard API.  If you write improvements, add new functions rather
 than rewriting current functions.  This will make it possible to
 include you improved code in the next API release.  YOU can help advance
 VR-386.  Comments on the API are welcome.


AVAILABILITY:

Currently, VR-386 is available on a trial basis by anonymous
FTP from psych.toronto.edu, in the ~ftp/pub/vr-386 directory.
The development package is vr386.zip.  Many new video drivers are
available in video.zip including source code.  A driver for the
Cyberscope is available as cyber.zip.

This University of Toronto site has a much wider bandwidth than the Waterloo site:
please let me know IMMEDIATELY of any problems!

- Dave Stampe
([e-mail])