h2 VRUI Release Manual
(copied from the Keck CAVES home page)
The Vrui VR toolkit is currently installed on the following VR environments:
h4 Responsive Workbench (mcphee) * The toolkit is installed in /1/Vrui-1.0; the default configuration uses the workbench for head-tracked stereoscopic display, the stylus and the index fingers on both pinch gloves for dragging operations, the middle fingers on both pinch gloves for two-handed navigation, and the ring fingers on both pinch gloves to bring up the application's root context menu.
h4 Tiled Display Wall (elcapitan) * The toolkit is installed in /home/clusterdata/Vrui-1.0; the default configuration distributes the application to the six render nodes (elcap0 - elcap6), and uses the tiled display wall for head-tracked stereoscopic display, the trigger button on the wand for dragging operations, the red and yellow buttons on the wand for navigation (panning, rotating and scaling), the Y direction of the wand's joystick to fly in the direction the wand is pointing, and the green button on the wand to bring up the application's root context menu.
h4 KeckCAVES (caveman.geology.ucdavis.edu) * The toolkit is installed in /usr/local/Vrui-1.0; the default configuration distributes the application to the four render nodes (r1 - r4), and uses the CAVE for head-tracked stereoscopic display, the red and yellow buttons on the wand for navigation (panning, rotating and scaling), the Y direction of the wand's joystick to fly in the direction the wand is pointing the X direction of the wand's joystick to rotate around the wand's Z axis, and the green button on the wand to bring up the application's root context menu.
h2 Application Development with Vrui
To build a VR application using Vrui, one only has to add the Vrui include file directory (<installdir>/include) to the compiler's include directory path, and the Vrui library directory (<installdir>/lib on 32-bit Linux, <installdir>/lib64 on 64-bit Linux) and the Vrui library (-lVrui.g++-3) to the linker command line. To find the Vrui library at run-time, one can either set the LD_LIBRARY_PATH environment variable to the Vrui library directory, or add the Vrui library directory to the run-time path of built executables by adding -Wl,-rpath=<installdir>/lib (on 32-bit Linux) or -Wl,-rpath=<installdir>/lib64 (on 64-bit Linux) to the linker command line.
Note: Due to the mixed 32-bit/64-bit environment, Vrui applications are currently not binary portable between the different environments; applications need to be rebuilt (but not otherwise changed) when moving between systems. This issue will be resolved in the near future by additionally installing 32-bit versions of the Vrui library and run-time plug-ins on elcapitan.
Here is an example makefile to build a single-source Vrui application:
# Set the Vrui installation directory:\\ ifeq ($(HOSTNAME),mcphee)\\ VRUIDIR = /1/Vrui-1.0\\ elif ($(HOSTNAME),elcap\itan)\\ VRUIDIR = /home/clusterdata/Vrui-1.0\\ elif ($(HOSTNAME),caveman.geology.ucdavis.edu)\\ VRUIDIR = /usr/local/Vrui-1.0\\ endif\\
# Determine library directory:\\ ifeq ($(shell uname -m),x86_64)\\ LIBEXT = lib64\\ else\\ LIBEXT = lib\\ endif\\
# Define Vrui include and link settings:\\ VRUIINC = -I$(VRUIDIR)/include\\ VRUILINK = -L$(VRUIDIR)/$(LIBEXT) -lVrui.g++-3\\
# Add run-time search path to built executables:\\ VRUILINK += -Wl,-rpath=$(VRUIDIR)/$(LIBEXT)\\
# Build the Vrui demo program:\\ VruiDemo: VruiDemo.cpp\\ g++ -o VruiDemo $(VRUIINC) VruiDemo.cpp $(VRUILINK)\\
The VruiDemo application is an “empty” demonstration application for the Vrui::Application class (comparable programming model to GLUT) and some basic features of the Vrui toolkit and the GLMotif user interface component library. It is available for download (C++ source code, 10KB).
h2 The Vrui Run-Time Environment
If a Vrui application has been built with run-time library search path information (as suggested in the above makefile), the Vrui run-time environment does not require any other settings, configuration files, or environment variables to run. The only additional requirement stems from the fact that the cluster-enabled version of Vrui running on the tiled display wall and KeckCAVES uses ssh to distribute an application from the cluster head node to all render nodes. To not have to type in one's password four or six times to start a Vrui application, ssh should be set up with automatic authentication as described in the man page for ssh-keygen. Future versions of the Vrui VR toolkit will support additional distribution mechanisms such as kerberos.
On any environment (single-node or cluster), a Vrui application is started by simply calling the application's executable. The Vrui VR toolkit recognizes (and removes) one argument from a program's command line: If the command line contains the flag “-rootSection” followed by another argument, the Vrui VR toolkit will use that second argument as the root section inside the Vrui configuration file (and then remove the flag and the argument from the command line). For example, to start a Vrui application in desktop mode (on any environment), one types “<appname> -rootSection Simulator”. Without this argument, the Vrui application will start with the settings appropriate for the environment it is running on.
