Revision as of 10:49, 16 May 2024

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

Vrui LidarViewer

As of the last update of this Wiki page, the latest version of Vrui is 12.0-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 lines of the Vrui library, then you will need to have each branch 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.

This page has most recently been updated for Vrui version 12.0-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

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

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

As of 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.0-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
Untar in a local directory
% tar -zxf Vrui-12.0-001.tar.gz

% mkdir Vrui-12.0-001_<os>

% cd Vrui-12.0-001
Adjust the makefile
% $EDITOR makefile
- set INSTALLDIR to "/opt/VR/Vrui-12.0-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 change to the actual installation directory
Adjust makefile [optional — as required]
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
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:

KECKCAVES Wiki page on Vrui Configuration
Oliver Kreylos' Vrui online documentation has three pages on configuration:

As of Vrui version 2.7, there is 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.

% OnHMD ShowEarchModel

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

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

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
4.3-001	07/18/2017
4.5-004	08/06/2018
4.6-002	12/04/2018
4.6-005	12/17/2018
...

Difference between revisions of "Vrui"