R3vis Corporation - RM Scene Graph and the CAVE library

CAVELib is [tm] the University of Illinois, and commericially distributed by VRCO.

2 September 2000

OpenRM and CAVELib[tm]

OpenRM Scene Graph and CAVELib are complementary technologies: CAVELib is an API providing a framework for creating cross-platform virtual reality (VR) applications, and OpenRM is an API that provides cross-platform scene management and rendering services. CAVELib gathers VR device events, and computes view transformations for all visible display surfaces in a spatially immersive display environment, invoking application-supplied "draw code" for each display surface. OpenRM Scene Graph provides cross-platform "draw code" in the form of a developer-extensible scene graph model. Used together, these technologies complement each other, producing a powerful technology base for high performance and cross-platform applications development.

Obtaining OpenRM Scene Graph and CAVELib

OpenRM Scene Graph may be downloaded for free from the OpenRM website. The CAVELib software is commercially licensed by VRCO.

Some Technical Details

The following is taken from the OpenRM FAQ, and outlines some technical issues related to creating hybrid OpenRM and CAVELib applications. For additional information, please read the OpenRM/CAVELib Applications White Paper.

What is the CAVE library?

This information is copied from VRCO's website:

The CAVELib(tm) is an Application Programmers Interface (API) that provides general support for building virtual environments for Spatially Immersive Displays and head-mounted displays including desk-type devices, cubic displays, multi-piped curved displays, and some dome styled displays. The CAVELib is not an application, it's a building block used to create applications for a variety of virtual environments.

The CAVELib configures the display device, synchronizes processes, draws stereoscopic views, creates a viewer-centered perspective and provides basic networking between remote Virtual Environments. The CAVELib allows a single program to be available on a wide variety of virtual display devices without rewriting or recompiling. The CAVELib uses a resource configuration file that can be modified to change display and input devices, making the programs written on the CAVELib portable to a wide-variety of display devices.

The CAVELib is an API of functions that can be used by programmers to create robust programs for virtual display devices or desktops. The CAVELib is not the product of choice for the non-programmers and end-users simply wanting to interact with a virtual environment. For those customers there are a variety of applications available including the VRCO's VRScape[tm] model viewer.

Can one create apps that use OpenRM for rendering, and the CAVElibrary?

Yes. R3vis and VRCO have both created a number of applications that use both OpenRM and CAVELib. These applictions use VR input devices, and render to stereo-capable tiled surface displays. See the CAVE demonstration section (below) for more details about demonstration versions of these programs.

What are the basic issues with OpenRM and CAVE applications?

While a complete description of the technical issues that have bearing upon OpenRM and CAVELib applications is beyond the scope of this FAQ, a summary of the most important issues follow.

Architecture of CAVELib and OpenRM Applications.
One way to characterize applications built using only CAVELib for device management is to think of the application as consisting of a main() that first initializes CAVELib, then yields control to the CAVELib event loop management subsystem. The CAVELib event manager will invoke an application callback on a per-frame basis to perform draw operations. After the application draw callback completes, execution control is returned to CAVELib. CAVELib provides event management, including support for a variety of virtual reality input devices, and relieves applications of the burden of computing view transformations, including the sheared-frustum transformations required for tiled surface display systems.

By itself, CAVELib provides no rendering services. All rendering (raw OpenGL calls) and scene management (lights, material properties, etc.) must be performed by the application. This is where OpenRM and CAVELib complement one another. Applications can use OpenRM to perform scene management and rendering services, thereby accelerating development by making use of a portable and extensible infrastructure layer for scene management. The primary design requirements of an OpenRM + CAVELib application include correctly initializing the CAVELib, building a scene graph with OpenRM calls, and when the per-frame application draw function is invoked by CAVELib, invoke the OpenRM rendering method. Except for a few OpenRM configutation details, that's really all there is to it.
Management of the OpenGL Matrix Stack.
Upon entry to the application-supplied per-frame draw callback, CAVELib has set the GL_MODELVIEW and GL_PROJECTION matrices to reflect the current view transformation for the given eye position. Applications may further modify these matrices, but are advised to use glPushMatrix() and glMultMatrix(). Any application matrices will be effectively pre-multiplied with the values on the matrix stack, causing application transformations to be applied prior to those specified by the CAVELib. This result is what is expected and necessary for applications that perform modeling (such as articulation of parts, instancing, and so forth). In conflict with CAVELib matrix stack management, OpenRM also performs matrix stack management. However, a minor change to OpenRM allows applications to lightly alter the OpenRM matrix stack management policy. This change is needed for compatibility between OpenRM and CAVELib. Please refer to the next section for OpenRM API details.
Management of the OpenGL Rendering Context.
In addition to management of the matrix stack, CAVELib performs management of the OpenGL rendering context, including buffer-swapping after all rendering has been completed. Like CAVELib, OpenRM provides the infrastructure to support binoncular stereo or monoscopic views, along with the buffer-swapping management to produce smooth, double-buffered stereo. In order to provide compatibility with CAVELib, applications can use a method within the OpenRM API, described in the next section, which will lightly alter the OpenRM rendering context management policy.

What are the specific areas in OpenRM apps that require attention for use with CAVELib?

If we assume a standalone OpenRM application, such as one of the OpenRM demonstration programs, the following list of changes are required to enable compatibility with CAVELib.

Changes to main(), including CAVELib initialization and event management.

The following code snippet shows a baseline set of calls that will initialize the CAVELib, and register application initialization and draw callbacks with CAVELib.

int
main(int argc,
     char *argv[])
{
    CAVEConfigure(&argc, argv, NULL);
    CAVEInit();
 
    CAVEInitApplication(appInitGL, 0); /* register gfx init func with CAVE.
                                          this callback invoked only once. */

    CAVEDisplay(appDrawFunc, 0);       /* register draw function with CAVE. 
                                        invoked once per frame. */

    CAVEFrameFunction(mySpinFunc, 0);  /* register per frame processing callback.
                                        also invoked once per frame */

    while (!CAVEgetbutton(CAVE_ESCKEY)) /* loop until user presses ESC key */
	usleep(1000);		/* sleep 1000 microseconds (1msec) */
    
    CAVEExit();
}

Set the OpenRM policy for matrix stack and rendering context management.

Within the appInitGL() callback (invoked exactly once in the OpenRM + CAVELib application), two important changes are required. First is to set the OpenRM matrix stack policy. This change is needed to honor the viewing transformation computed and assigned by the CAVELib. The second is to set the OpenRM rendering context management policy. The only change needed is to disable buffer-swapping within OpenRM, as CAVELib provides that service.

void
appInitGL(void)
{
    RMenum status;
    int myWidth, myHeight, myOriginX, myOriginY;

    rmInit(); /* initialize OpenRM */

    myPipe = rmPipeNew();  /* create an OpenRM pipe */

    /* for OpenRM + CAVELib apps, always use an RM_MONO_CHANNEL. see
     the OpenRM + CAVELib White Paper for caveats. */
    rmPipeSetChannelFormat(myPipe, RM_MONO_CHANNEL); 

    /* turn off OpenRM initialization of the OpenGL matrix stack. */
    rmPipeSetInitMatrixStackMode(myPipe, RM_FALSE);

    /* turn off swapbuffers - CAVElib handles that. */
    rmPipeSetSwapbuffersFunc(myPipe, NULL);

    /* obtain the OpenGL context from CAVElib, assign that to the pipe */
    rmxPipeSetContext(myPipe, CAVEGLXContext());
    rmxPipeSetDisplay(myPipe, CAVEXDisplay());

    /* obtain and assign window geometry */
    CAVEGetWindowGeometry(&myOriginX, &myOriginY, &myWidth, &myHeight);
    rmPipeSetWindow(myPipe, CAVEXWindow(), myWidth, myHeight);
	
    rmPipeMakeCurrent(myPipe);

    /* build the model which will later be rendered during the per-frame
       CAVELib draw callback. */
    buildInitialSceneGraph();
}

Draw callback.
Once per frame, CAVELib invokes an application-supplied draw callback. In the OpenRM+CAVELib application, the following code snippet represents the draw callback registered in the sample main() (above). All this callback does is invoke the general purpose OpenRM frame drawing method.
```
void
appDrawFunc(void)
{
    rmFrame();
}
```

Where can I find lots of in-depth technical information about OpenRM + CAVELib apps?

At this time (Sept 2000), this FAQ and the example code are your best sources of information. Visit the VRCO website to obtain technical information about the CAVE library, and study the example programs available from the OpenRM download page. We are working on a White Paper that examines technical issues in more detail, but it is not finished at this time.

Are there any example programs that show how to use OpenRM and the CAVE library?

Yes. Visit the OpenRM download page to obtain the OpenRM+CAVELib demonstration programs. These examples use CAVELib to gather VR device information, and OpenRM for rendering.

CAVELib Trademark Information

CAVELib is a registered trademark of the University of Illinois.