Vrui

Vrui VR integration library

Vrui is a VR integration library from the University of California at Davis' KeckCAVEs facility. Vrui takes the approach of providing a framework into which applications are integrated and can take advantage of many different plugin tools and navigation controls that are independently created from the application.

There are pre-existing Vrui_Applications written at UC-Davis and DRI/INL as part of our immersive visualization ensemble. But before using a Vrui application, one must first install and configure Vrui.

Vrui Versions

There are currently two branches of Vrui (the 1.0 line and the 2.x line). There are some significant differences, including many changes to the API, as well as to the DeviceDaemon protocol.

If you have applications written for both the 1.x and 2.x lines of Vrui, then you will need to have both installed. Fortunately, this is rather easy to do, and following these directions will ensure that your system will work with multiple versions of Vrui installed.

Vrui Dependencies

Basic Vrui depends only on two packages which are generally installed on any self-respecting computer:

• OpenGL
• X-windows

There are also a number of highly-recommended packages that will enhance Vrui:

• zlib-devel
• libpng-devel
• libjpeg-devel
• libtiff-devel
• libasound2-dev
• bluez-libs-devel

Installing Vrui

These instructions have been tested with Vrui version 1.0-068 (the latest of the 1.0 line), but should generally work for other versions of Vrui.

1. Download Vrui

   Download from the Vrui Download page

2. Untar in a local directory

   % tar -zxf Vrui-1.0-068.tar.gz

   % cd Vrui-1.0-068

3. Adjust the makefile

   % $EDITOR makefile

   • set INSTALLDIR to "/opt/VR/Vrui-1.0-068"

     NOTE: adding the build-version to INSTALLDIR helps avoid issues when upgrading

   • add "-b" to the "@install ... Share/Vrui.cfg ..." line

     (this will save you much grief in the future -- when you might otherwise wonder what happened to the config files you made)

     NOTE: after the first install, commenting out this line entirely is recommended

4. Fix a bug (update tracking for single tracker)

   % $EDITOR VRDeviceDaemon/VRDeviceManager.cpp

   • Change: "if(trackerReportMask==fullTrackerReportMask)" to "if(trackerReportMask != 0)"

5. Fix another bug (proper window placement)

   % $EDITOR GL/GLWindow.cpp

   • Add after XMapWindow(display,window);

     /* since XCreateWindow() doesn't properly place the window, we need to move it to the correct location */
     XMoveWindow(display, window, windowPos.origin[0],windowPos.origin[1]);

6. Add a feature (remove decorations on full-screen displays)

   % $EDITOR GL/GLWindow.cpp

   • Add after window=XCreateWindow(...)

     /* Add a block to turn off decorations when window is as big as one screen */
     if ((windowPos.size[0] == 1920) && (windowPos.size[1] == 1080)) {
           unsigned long   wm_hints[5] = { 2, 0, 0, 0, 0 };        /* the 4th element isn't really unsigned, but it's zero, so who cares */
         XChangeProperty(display, window, XInternAtom(display, "_MOTIF_WM_HINTS", False), XInternAtom(display, "_MOTIF_WM_HINTS", False), 32, PropModeReplace, (const unsigned char *)wm_hints, 5);
     }

7. Compile

   % make -j 8

   (this will take less than a minute)

8. Install

   % sudo mkdir -p /opt/VR/Vrui-1.0-068 (or whatever version you are compiling)

   % sudo make install

   (NOTE: after subsequent installs, you'll have to go to $INSTALLDIR and copy back from the saved backup config files)

That's it!

Configuring Vrui

Configuring Vrui can be a very difficult task. A general hint is to find a working configuration setup that's close to what you want to do and then modify! As we gain more experience, we will put more specific advice/instructions here.

In the meantime, here are links to other sources of information:

• KECKCAVES Wiki page on Vrui Configuration
• Oliver Kreylos' Vrui online documentation has three pages on configuration:
  • Setting up and Calibrating a Vrui VR Environment
  • The Vrui Configuration File
  • Vrui Configuration File Settings Reference

Here are some unorganized bits of information as I encounter them during my trials (and tribulations):

• Comments are denoted with the hash (#) symbol through the end-of-line
• When discussing Vrui configuration options, a directory-like syntax is used by the Vrui library (but not the configuration file). In the configuration files, sections have sections within them.
• In Vrui.cfg, the "root" section is the one selected for use, when not specified on the command line with the -rootSection option it defaults to Desktop
• In theory Vrui can use any coordinate frame. In practice, use Z-up since applications seem to assume this.
  • thus, always set root/upDirection (0.0, 0.0, 1.0)
• Windows and Screens go hand-in-hand (I'd prefer them to be a single entity)
• root/displayCenter — the place where the world will go when centering the display (including initial location)
• root/displaySize controls the relative size that the vis-world is rendered. A good rule-of-thumb is to set this to be half the front screen's diagonal

Compiling Vrui Applications

Vrui comes with some example programs that can be quickly compiled and used for experimentation.

1. Adjust the makefile

   % cd ExamplePrograms

   % $EDITOR makefile

   • for Vrui 1.x: set VRUIDIR to "/opt/VR/Vrui-1.0-068"
   • for Vrui 2.x: set VRUI_MAKEDIR to "/opt/VR/Vrui-2.3-001/share/make"

2. Compile

   % make

3. Run

   % ls bin

   % bin/VruiDemo

   This should open a window with a spinning cube.

See Also

• Oliver Kreylos' Vrui page
• Changes between Vrui 1.x and 2.x
• IU AVL Wiki's Vrui page (which will often be in sync with this page) (Login required)
• VisualIdeation Wiki's Vrui page (Login required)
• An unofficial continuation of the Vrui 1.x series