Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members

InSpace Documentation


InSpace 3.0 VR Library Release Notes

InSpace is a library of GL graphics utilities that are commonly used, primarily in the Sci-Vis group at Brown University, for graphics research projects. The goals for the library are:

1. To take care of setting up and managing head tracked displays on several types of VR environments: Cave, Fishtank, Powerwall, Immersadesk. Also, to make it easy to run VR programs on a desktop for testing, or just write a standard desktop program.

2. Offer useful higher level abstractions for common graphics tasks. Textures, Meshes, Fonts, Sound, all these things fall into this category and are not provided directly by GL.

3. Avoid limitations of systems like World Toolkit, etc.. that make it hard for programmers to write their own GL code to take advantage of the latest gfx card capabilities.

4. Adapt to work with other systems as they become available. For example, InSpace currently can be built on top of Glut or G3D. If required, it could be built on top of VRJuggler, or pretty much any other OpenGL based grahics system through the ISVREngine abstraction.

Version numbers

Major version numbers increase when changes are BIG enough to significantly break the compilations of programs using the library or when a major organization or philosopy in the code changes.

Minor version numbers (after decimal point) increase when header interfaces change to not be backward compatible. i.e. change in such a way as to break someone else's code.

Code is updated via CVS but version numbers generally don't change when a bug fix is committed to the CVS repository or limited additional functionality is added that remains backward compatible.

Changes since version 2.0

Version 3.0 was created because major code changes were required in order to run InSpace on top of G3D that would break code that uses the 2.0 headers. The major thing that changed was putting everything in the library inside the namespace InSpace.

G3D Integration

Version 3.0 of Inspace incorporates the ability to use the graphics library G3D ( as the back end for InSpace. To make this happen in your code, use this call to start up a G3DEngine rather than a GlutEngine.

  // create a G3D VR Engine - this sets ISVREngine's instance variable

To draw objects with G3D calls inside your DrawObj's, implement the method drawG3D(). This is a new method in this release. To remain compatible with older non-G3D code, the drawG3D() method defaults to calling the usual draw() method that you've used with inspace in the past, but it wraps it in appropriate glPush/Pop commands to keep G3D happy. So, the long and short of this is, you're old stuff should work without modification. If you write new stuff that takes advantage of G3D, do it inside the drawG3D() method rather than the draw() method.

New features so far, if you use G3D: The texture class can load and save .jpg and .bmp.


To compile with G3D support USE_G3D must be specified in the DEFINES line in the Makefile. If it is not specified InSpace will compile and can be used as usual with Glut support.

Use namespace InSpace!!!!!

To prevent namespace conflicts with G3D, particularly within the Texture class, all InSpace classes are now contained within the namespace InSpace. Therefore, every file that uses InSpace in your project now needs to tell the compiler that it uses this namespace with the command:

  // InSpace includes here..
  #include <DrawMgr.H>

  // use the InSpace namespace
  using namespace InSpace;

  // now we have access to DRAWMGR::foo()
  // or, access this function as InSpace::DRAWMGR::foo()

Notes and changes since version 1.2

$G (GfxTools)

InSpace is meant to work with the $G software organization. If you're new to $G, check out the documentation in $G/shared/man/get-started.txt, which is at /map/gfx0/tools/shared/man/get-started.txt in the Brown CS dept.

If you're setting up inspace for the first time under $G, then a quick way to make sure you have all your dependencies setup is to run the init-test-inspace-2.0 script, which will check out, compile, and install everything needed to run the test-inspace-2.0 project. This script should be in your path once $G is setup. The source is in $G/shared/src/gfxscripts.

No VRJuggler needed

InSpace no longer relies on VRJuggler. Any GL-based system can now be used to open and handle GL windows in InSpace through the ISVREngine abstraction. InSpace gets all its info about the display from the base class ISVREngine. Each windowing system implements a subclass of ISVREngine. For example, there is a GlutEngine that uses the glut library to interface with GL. Soon, there will be a VRJugEngine that does the same with VRJuggler as the back end. There could also be a G3D (Morgan's library) Engine.

ContextData and Multi-Pipe Issues

Currently, the GlutEngine cannot handle a situation where you're on a SGI multi-pipe computer, like at the Cave. VRJuggler is good at this. Part of what makes it good is its vjGlContextData<> template. There is now an InSpace wrapper around this template called isGlContextData<>. Once a VRJugEngine is implemented, you can use this template, and it will act exactly as vjGlContextData<> does in VRJuggler. When you're not using VRJuggler as a back end, then the interface to the template remains the same, but there's no funky context specific data management going on underneath. So, to make your program portable, you should always use the isGlContextData type. That way, if you want to run it on a multi-pipe SGI at some point with VRJuggler, you can.

Specifying Display Settings

The ISVREngine reads in the display settings from glueconfig values. There are currently several glueconfig files that setup proper display values for common displays. All of these are in the $G/src/inspace-2.0/config directory, which gets installed to $G/shared/lib/inspace-2.0/config. Note, that there are also device specific glueconfig files for common setups in this directory. Here's a common way to start your inspace program:

   Example: program -f $G/shared/lib/inspace-2.0/config/glueconfig-desktop-display \
                    -f $G/shared/lib/inspace-2.0/config/glueconfig-desktop-devices \
                    -c DISPLAY=desktopfullscreen 

The first two -f arguments tell gluebase to parse those glueconfig files. The -c argument tells gluebase to override the glueconfig variable named DISPLAY and set its value to desktopfullscreen. The glueconfig-desktop-display file sets up two possible displays, one for running in a 640x480 window, and one for running fullscreen. It defaults to the desktopwindow setup, but you can override this as was done here. InSpace will look for information on how to setup the display (number of tiles, resolution, stereo/mono, etc..) based on the value of the DISPLAY glueconfig variable. Look at the example glueconfig files in the config directory for more info.

Creating a new Application

Use $G/src/test-inspace-2.0/ as an example. Copy this and modify it to fit your needs. The TestApp class is what you want to change to be your application.

GLUE Config File Usage

Glue no longer automatically loads certain config files. You have to specify exactly which config files you want to load on the command line. You can also specify individual name=value pairs on the command line. Run any program with a "--" argument to see a usage message. Here's one:

   test-inspace-2.0-d [-f filename [-f filename...]] [-c name=value [-c name=value...]]
   options:            (defaults in [...]'s )
      -f filename      Specifies a GLUE-style config file to process. [null]
      -c name=value    Specifies a GLUE config name=value pair to process. [null]
                       'value' overrides any values for 'name'
                       specified in glueconfig files.

Argument Parsing (ggargs)

The args package that is part of dhl's libgg from CalTech is now used to do argument parsing. I took it out of libgg and put it in its own library called ggargs for now so that I could tweak it to compile on windows. I would recommend using this package as a standard for program argument parsing from now on. It's very powerful and convenient. This adds a dependency to inspace.

InSpace dependencies

InSpace depends on the gluebase, ggargs, GL libraries, and glut. Optionally, it depends on openal for integrated sound.

In turn, gluebase depends on vrpn-6.02 for some devices.

So, if you want everything for a VR setup, you need:

Generated on Thu Jul 8 15:19:28 2004 for inspace by doxygen 1.3.4