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-001. 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-001, 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
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

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-001, but should generally work for other versions of Vrui. Note that mostly for the purpose of using Modules.

Download Vrui
Download from the Vrui Download page

% wget http://vroom.library.ucdavis.edu/Software/Vrui/Vrui-12.1-001.tar.gz
Untar in a local directory
% tar -zxf Vrui-12.1-001.tar.gz

% mkdir Vrui-12.1-001_<os>

% cd Vrui-12.1-001
Adjust the makefile
% $EDITOR makefile
- set INSTALLDIR to "/opt/VR/Vrui-12.1-001_<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
- 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)
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!

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 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
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.

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

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

...

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</CODE option: % ShowEarthModel -rootSection 3DTV

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.

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 1.0-068
Vrui 2.7-001

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


...
...

See Also

 Vive Lighthouse — Setting up Vrui as a Valve Lighthouse interface
Oliver Kreylos' Vrui page
Oliver Kreylos' blog
Vrui tarball directory
Old Download page
Changes between Vrui 1.x and 2.x

Vrui

Contents