Vrui VR integration library

Vrui is a VR integration library from the University of California at Davis' Datalab library facility (formerly from the UC-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 LidarViewer

Vrui Versions

As of the last update of this Wiki page, the latest version of Vrui is 12.1-002. The API has gone through a handful of minor breaking changes, which (in the future) may be specifically documented, though once all the old applications have been updated, there will be diminishing need for that information. There are also multiple versions of Vrui's VR-DeviceDaemon protocol, which fortunately, Vrui generally negotiates a mutually agreeable protocol between client and server before input data is transmitted.

If you have applications written for multiple branches of the Vrui library, then you will need to have each branch installed. Fortunately, this is rather easy to do (especially using Modules), and following these directions will ensure that your system will work with multiple versions of Vrui installed.

This page has most recently been updated for Vrui version 12.1-002, but much of the configuration details are the same for older versions.

To determine what version of Vrui a dynamic library (SO/DLL) is, or what version of Vrui an application was compiled with, search through the ASCII strings of the binary for "libVrui".

% strings <application> | grep libVrui

libVrui.so.12

Building Vrui

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's capabilities:

libusb1-devel — for communicating with some I/O devices
vulkan-validation-layers — for compositing video to hidden HMD screens
vulkan-loader-devel — for compositing video to hidden HMD screens
(perhaps) vulkan-headers-1.3.250.1-1.el8.noarch — for the "vulkan.h" header
glslang-devel / glslang-tools — for compositing video to hidden HMD screens
OpenAL — for audio collaboration
zlib-devel
libpng-devel
libjpeg-devel
libtiff-devel
libasound2-dev
bluez-libs-devel
libogg & libtheora — for recording VR sessions

Also, there are other changes to the OS that are required:

Install the Vrui UDEV rules
(These set the permissions of USB ports connected to VR hardware to be user-accessable)

Installing Vrui

Starting with Vrui version 8.0 or so, Vrui can be downloaded and installed via the "PullPackage" method, which auto-downloads and builds configurations based on the local system. However, it is also still possible to download a tarball and manually build/install/configure. These instructions have been tested with Vrui version 12.1-002, but should generally work for other versions of Vrui. Note that mostly for the purpose of using Modules, these instructions append an _<OS> to the installation directory.

Download Vrui
Download from the Vrui Download page

% wget http://vroom.library.ucdavis.edu/Software/Vrui/Vrui-12.1-002.tar.gz
Untar in a local directory (and make an installation directory)
% tar -zxf Vrui-12.1-002.tar.gz

% mkdir Vrui-12.1-002_<os>

% cd Vrui-12.1-002
Adjust the makefile
% $EDITOR makefile
- set INSTALLDIR to "/opt/VR/Vrui-12.1-002_<os>"
  NOTE: adding the build-version to INSTALLDIR helps avoid issues when upgrading.
  
  NOTE also: Adding an abbreviation for the OS (e.g. "_el8" or "_u22") helps the Modules system to install the proper version.
  
  NOTE furthermore: the </opt/VR> path is an example. This should be changed to the actual installation directory.
Further adjust makefile [optional — as required]
Here are some things that still may require adjustment:
- SYSTEM_HAVE_OPENVR=1 (added after "disable Vive support" line)
- GLSLC=<path-to-bin>StandAlone/glslangValidator
- Also add -V to the shader compiling line:
  $(GLSLC) -o $@ $(GLSLCFLAGS) -V $<
Fix a bug (update tracking for single tracker)
% cp -p VRDeviceDaemon/VRDeviceManager.cpp{,_orig}
% $EDITOR VRDeviceDaemon/VRDeviceManager.cpp
- Change: "if(trackerReportMask==fullTrackerReportMask)" to "if(trackerReportMask != 0)"
  NOTE: Currently there are two lines where this should be changed.
Set the location of SteamVR (if not in usual place) [optional]
% export STEAMVR=<path-above-drivers>
(this is a pointer to the path where drivers/lighthouse/bin/<OS>/driver_lighthouse.so is found)
- If OpenAL isn't installed, you may have to forcibly exclude the addition of VruiSoundConfig and VruiSoundConfigTest from being added to the list of EXECUTABLES.
  NOTE: Actually, it's possible these will still compile w/o audio in >=12.1=001 versions of Vrui.
Compile
% make -j 8
(this will take less than a minute)
Install
% [sudo] make install
- Depending on where the files will installed will determine whether you need to use sudo to do the installing — you should make sure you have permission to do that, or instead make an installation directory you already have write access to.
Create Module file [optional]
% $EDITOR $MODULEPATH/vrui/<version>
(Add details of where the "bin", "lib", "include" and "share" directories are)

NOTE: If $MODULEPATHcontains more than one directory, then pick the relevant one.

That's it!

(Perhaps)

Fix to Vrui's BasicMakefile for applications that might need a more flexible library link ordering Fix to source/MATH/Point4.ccp to always return a value (See 05/01/24)

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:

Oliver Kreylos' Vrui online documentation has three pages on configuration:
Formerly: KECKCAVES Wiki page on Vrui Configuration (Wiki moved, or no longer exists)

Starting with Vrui version 2.7, the Vrui package has included a handy Vrui application called "DrawEnvironment" that will display a representation of the screens and tracked objects of the current configuration. This can come in quite handy when troubleshooting configuration difficulties — of course, you need to have something partially working to make use of it.

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 (or set in the VRUI_ROOTSECTION environment variable) 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

Testing Vrui

Once the VRDeviceDaemon is running (which may be through a script such as RunOpenVRTracker.sh), there are tools available to confirm the proper operation of the tracking.

From the Vrui tool suite is "DeviceTest", which connects to the daemon server and reports input values.

To report the location values from tracker #0 use:

% DeviceTest -t 0

From the FreeVR tool suite there is a similar tool called "vruiddtest", which will generally report all the input values.

To report all the inputs with a special "screen" rendering, use:

% vruiddtest -screen

Compiling Vrui Applications

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

% cd ExamplePrograms
In the past it was required to adjust the makefile
(This is no longer required)
% $EDITOR makefile
- for Vrui 2.x & 3.x: set VRUI_MAKEDIR to "/opt/VR/Vrui-2.7-001/share/make"
- for Vrui 1.x: set VRUIDIR to "/opt/VR/Vrui-1.0-068"
Compile
% make
Run
% ls bin

% bin/VruiDemo
This should open a window with a spinning cube.

Running Vrui Applications

In normal circumstances, a properly compiled Vrui application, running on a system with a proper Vrui configuration, can be run simply by calling the executable from the command line. For example:

% ShowEarthModel

Running on an HMD

To run a Vrui application such that it appears inside the view of an HMD, there are options that can be included on the command line to activate this. As a shortcut, the "OnHMD" script can also be used — though caution should be taken when the application is run through another Bash script.

But first there are two (or five the first time) other steps that must be taken:

(Once) Ensure that Vulkan is installed on your system — required by RunVRCompositor;
(Once) Ensure that the OpenVRDevices.conf file exists and is correct. Here is the configuration for an HTC Vive:
% cat $INSTALLDIR/etc/OpenVRDevices.conf

HMD_TYPE="HTC Vive"

CONTROLLER_TYPE="HTC Vive Wands"
Run the tracking daemon:
% RunOpenVRTracker.sh
(Once) Run the RoomSetup application:
% RoomSetup.sh (bash script)

or % RoomSetup -ignore HMD -buttonName Trigger -setConfig "Window/windowFullscreen=true"
Run the VR Compositor (which sends images to the HMD):
% VRCompositingServer -hmd "HTC Corporation HTC-VIVE"

Then:

Run the application on the HMD:
% OnHMD ShowEarchModel
- NOTE: the OnHMD <application> program is a bash script, but it is not written such that another bash script containing a Vrui command inside will work as the argument.

Activating Vrui options

The Vrui library has it's own command-line arguments that can be applied to any Vrui application. Features include the ability to select a non-default display mode — such as CAVE vs. HMD vs. Desktop (See "Selecting Alternate Display Modes" below.)

Another example is to increase the verbosity of the application and Vrui library, which is often useful when tweaking and debugging the configuration:

% ShowEarthModel -vruiVerbose

Selecting Alternate Display Modes

A Vrui configuration file ("Vrui.cfg") may contain multiple configuration sections, for different systems, or for different layouts of one system. By default, the first of these contained in the file will be selected, but this can be overridden with the -rootSection option:

% ShowEarthModel -rootSection 3DTV

or with the VRUI_ROOTSECTION environment variable:

% export VRUI_ROOTSECTION="cave"

% ShowEarthModel

Adding Vislets

Vrui is designed such that "generic" tools (plugins) can be written that can be added to any application at runtime. In Vrui parlance, these are called "vislets".

For example, to add a frame render-time display to an application:

% ShowEarthModel -vislet FrameRateViewer

NOTE: depending on how the application parses command-line options, it may be required to add the Vrui options after the application-specific options.

Keyboard Inputs

There are a handful of keyboard inputs that Vrui recognizes, in addition to which, any unassigned keyboard action can be mapped to any of Vrui's built-in tools.

Keyboard Shortcuts

Keyboard shortcuts can affect the rendering of the application scene when typed while a window has focus.

Here is one (some):

Vrui Keyboard Shortcuts
Keyboard Input	Affect
Win-Scrolllock	Toggle "burn mode" (aka OSD) (FPS if it's on)

Mapping Inputs to Tools

...

Vrui Issues

Here is a list of known issues (or at least things that bother the author of this page):

The chaperon outline isn't going away when all tracked objects are in the safe-space.
The chaperon outline renders over objects that are in front of it
The controller avatars render over objects that are in front of them
The "makefile" needs to be hand-edited to ensure proper SteamVR building
The path to the configuration files is hard-coded into the library and the applications.
Doesn't Build/Run on machine w/o OpenGL (e.g. NVIDIA DGX computers)
The "makefile" needs to check for SYSTEM_HAVE_LIBUSB1 when adding "FindHMD" to EXECUTABLES
Controller avatar models don't show up in "Home" (Null) world, then appear in applications

Older Vrui Versions

Specific references to building, installing and configuring older versions of Vrui will generally be removed from the primary document. However, as this is a wiki, past versions are saved in perpetuity:

Vrui Version release dates

Here is a table of dates (sometimes approximate) of when different versions of Vrui have been released):

Vrui version release dates
Vrui Version	Release Date	Vrui Version	Release Date
1.0-034	08/03/2006	6.0-001	08/05/2020
1.0-039	10/03/2006	8.0-002	03/13/2021
1.0-043	04/04/2007	9.0-002	11/18/2021
1.0-050	02/29/2008	9.0-003	04/15/2022
1.0-062	07/01/2009	9.0-004	05/24/2022
1.0-068	02/25/2010	9.0-005	06/14/2022
2.3-001	03/14/2012	10.0-001	07/27/2022
2.4-004	10/30/2012	10.1-001	08/08/2022
2.6.002	02/05/2013	10.1-006	03/14/2023
2.7-001	03/16/2013	10.2-001	03/20/2023
3.0-002	08/13/2013	10.2-002	04/13/2023
3.1-002	02/04/2014	11.0-001	01/26/2024
3.2-pre	11/03/2015	11.0-003	03/22/2024
4.0-001pre	12/02/2015	12.0-001	04/02/2024
4.2-004	10/18/2016	12.1-001	05/17/2024
4.3-001	07/18/2017	12.1-002	07/22/2024
4.5-004	08/06/2018
4.6-002	12/04/2018
4.6-005	12/17/2018
...	...

Vrui

Contents