Vrui is a C++ software development toolkit for highly interactive virtual reality applications, with a focus on portability between vastly different virtual reality environments, from laptop or desktop computers to CAVEs and other fully immersive systems such as head-mounted displays. More information about Vrui can be found at http://idav.ucdavis.edu/~okreylos/ResDev/Vrui or http://www.keckcaves.org.
Vrui's development was supported by the University of California, Davis, by the UC Davis W.M. Keck Center for Active Visualization in the Earth Sciences (KeckCAVES, http://www.keckcaves.org), the W.M. Keck Foundation, and the National Science Foundation.
On all operating systems, Vrui is based on the X Window System (X11) and OpenGL. On Mac OS X, X11 is an optional component and can be installed from the installation media. To build Vrui from source on Mac OS X, it is necessary to install the optional X11/Xquartz and xcode components from the installation media. On Linux, we strongly recommend installing appropriate vendor-supplied OpenGL drivers (such as those released by Nvidia or ATI/AMD) for optimal 3D graphics performance.
Vrui uses additional libraries if it detects them on the local system, such as libpng, libjpeg, and libtiff to read/write images in PNG, JPEG, and TIFF formats, respectively, and OpenAL to render three-dimensional sound. On Mac OS X, libpng, libjpeg, and libtiff need to be downloaded from their respective repositories and built from source. On Linux, OpenAL might not be installed by default and needs to be installed via the distribution's package manager.
Required:
Recommended:
Optional:
(Replace
(Install required packages, if necessary or desired.)
Create src directory in home directory and change into it:
mkdir ~/src cd ~/src
Download and unpack the Vrui tarball:
wget -O -
/Vrui- - .tar.gz | tar xfz -
Change into Vrui base directory:
cd Vrui-
-
Build Vrui inside the Vrui base directory:
make or, for multi-processor machines make -j
Install Vrui into /usr/local
sudo make install
If there are error messages during the build, read below.
Change into example application directory:
cd ~/src/Vrui-
- /ExamplePrograms
Build example applications:
make
(On MacOS X: Start X11.)
Run Earth renderer:
./bin/ShowEarthModel
Read about Vrui's default user interface in HTML documentation in
/usr/local/share/doc/Vrui-
Installation is performed via the central makefile in the
Vrui-
The one makefile setting that might need to be adjusted is the Vrui installation path at the very beginning of the makefile. By default, Vrui installs itself into /usr/local hierarchy. This can be changed either by editing the makefile, or, better, by passing the desired nstallation directory on make's command line:
make INSTALLDIR=
NOTE: It is important not to install Vrui into the same directory in
which it is built. A typical installation would download the source
tarball into a special "source" directory, say ~/src, and extract it
from there, resulting in the sources being in
~/src/Vrui-
Here is a diagram of the directory structure described above:
| ~ (home directory) | +- src (unpack Vrui tarball from in here) |
|---|
+- Vrui-<version>-<build> (package root directory, run "make" in
| here)
|
+- COPYING, VERSION, HISTORY, README
|
+- makefile
|
+- BuildRoot (Vrui's build system)
|
+- <Vrui component directories>
|
+- ExamplePrograms (Vrui example program source
| codes)
|
+- d (dependency files, created by "make")
|
+- o (object files, created by "make")
|
+- lib / lib64 (library files and plug-ins,
| created by "make")
|
+- bin (executable files, created by "make")| /usr/local | +- include (system include directory) |
|---|---|
| +- Vrui- |
|
| "make install") | |
| +- Misc, Realtime, Threads, ..., Vrui | |
| +- header files | |
| +- lib / lib64 (system library directory) | +- pkgconfig (system package configuration directory) | ||
|---|---|---|---|
| +- Vrui.pc | |||
| +- Vrui- |
|||
| "make install") | |||
| +- VRTools, VRVislets, VRDevices, VRCalibrators | |||
| +- plug-in *.so files | |||
| +- libMisc..so, libRealtime..so, ... | |||
| +- bin (system executable directory) | +- AlignTrackingMarkers, DeviceTest, ... |
|---|
| +- etc (system configuration directory) | +- Vrui- |
"make install") | |||
|---|---|---|---|---|---|
| +- Vrui.cfg, VRDevices.cfg, ... | |||||
| +- share (system resource directory) | +- Vrui- |
|---|---|
| +- Vrui.makeinclude (makefile fragment, deprecated) | |
| +- make (Whytools build system) | |
| +- SystemDefinitions, BasicMakefile, ... | |
| +- template makefile for Vrui application development | |
| +- GLFonts, Shaders, Textures | |
| +- fonts, shader source files, and textures | |
+- doc (system documentation directory, possibly created by
| "make install")
+- Vrui-<version> (Vrui documentation, created by "make install")
|
+- index.html, ...The root installation directory is set by changing the value of INSTALLDIR at the top of the makefile, or by passing INSTALLDIR=<desired installation directory> on make's command line. Vrui installs itself in the usual subdirectories under the root installation directory:
If the root installation directory is set to /usr, Vrui will almost (but not quite) follow the UNIX installation conventions. Concretely, configuration files will end up in /usr/etc and not in /etc. If the latter is desired, the additional SYSTEMINSTALL parameter needs to be added to make's command line, and INSTALLDIR must be set to the empty string:
make SYSTEMINSTALL=1 INSTALLDIR=
Normally, Vrui installation is controlled by the INSTALLDIR variable defining the root installation directory, and the optional SYSTEMINSTALL flag to create a standard-conformant root level installation. If more fine-tuning is required to install Vrui in a pre-existing directory hierarchy, Vrui's component directories can be specified individually:
HEADERINSTALLDIR: root directory for include files. Installation will create subdirectories Misc, Threads, Plugins, Vrui, ...
LIBINSTALLDIR: directory for shared library files.
EXECUTABLEINSTALLDIR: directory for executable files.
PLUGININSTALLDIR: root directory for tool and vislet plug-ins. Installation will create subdirectories VRTools, VRVislets, VRDevices and VRCalibrators.
ETCINSTALLDIR: directory for configuration files.
SHAREINSTALLDIR: root directory for non-executable files. Installation will create subdirectories GLFonts, Shaders, and Textures.
PKGCONFIGINSTALLDIR: directory for Vrui's pkg-config file (Vrui.pc).
DOCINSTALLDIR: directory for Vrui's HTML documentation.
MAKEINSTALLDIR: directory for Vrui's build system.
Many operating systems contain package managers to distribute software as binaries for simplified installation and management. It is straightforward to build Vrui into such packages, but the details depend on the particular operating system version.
The one thing all packagers have in common is that the software must be built in a "fake root" environment. Meaning, while the software is intended to end up in, say, /etc, /usr/bin, /usr/lib, ..., during package preparation the software has to be copied into a hierarchy under some base directory, such as ~/packages/etc, ~/packages/usr/bin, ...
This can be achieved by using the final installation directory during compilation and linking, and using the "fake root" directory during installation. For example:
make INSTALLDIR= SYSTEMINSTALL=1 make INSTALLDIR=$HOME/packages SYSTEMINSTALL=1 install
will configure the software to be run from /etc, /usr/bin, etc., but will install the files in the same hierarchy underneath ~/packages.
The compiler is selected in the file BuildRoot/SystemDefinitions. The
compiler suite's base directory is set by changing the GNUC_BASEDIR
variable, or by passing GNUC_BASEDIR=
Starting with version 4.1.0, g++ no longer injects friend functions defined inside a class declaration into the surrounding namespace. The build system (BuildRoot/SystemDefinitions and BuildRoot/BasicMakefile) contains code to detect the compiler version and add the -ffriend-injection flag to the compiler's command line if the version number is greater or equal 4.1.0. However, if compiling the example programs in ExamplePrograms generates error messages about undeclared functions, the flag -ffriend-injection needs to be manually added to the compiler command line when building Vrui and Vrui-based applications. The best place to add the flag is to the end of CSYSFLAGS at the beginning of BuildRoot/SystemDefinitions before building. Alternatively, the flag can be added to CFLAGS inside the example programs' build directories after Vrui has been built/installed.
Vrui contains support for reading/writing binary files with automatic endianness conversion, and sending/receiving data over TCP pipes with automatic network endianness detection and endianness conversion. For this to work, the OS must offer an include file that sets the #define macros LITTLE_ENDIAN, __BIG_ENDIAN, and BYTE_ORDER. BYTE_ORDER must be equal to __LITTLE_ENDIAN on little-endian machines, and equal to BIG_ENDIAN on big-endian machines. The Misc/Endianness.h header file includes the appropriate system header files for Linux and Mac OS X, but might need to be adapted for other operating systems.
The image handling library that is part of the Vrui toolkit supports reading and writing image files in PNG, JPEG, and TIFF formats. These features are based on the libpng, libjpeg, and libtiff libraries, respectively. If the host computer does not contain either of these libraries, support for PNG, JPEG, or TIFF images can be disabled separately in the makefile by setting IMAGES_USE_PNG, IMAGES_USE_JPEG, or IMAGES_USE_TIFF to 0, respectively. The Vrui makefile now contains code to automatically detect whether libpng, libjpeg, and/or libtiff are installed, and sets these three variables accordingly. More precisely, the makefile looks for png.h, jpeglib.h, and tiffio.h in /usr/include and /usr/local/include. If either library is installed in a different directory on the host system, the makefile variables need to be set manually, and the paths to the libraries need to be adjusted in BuildRoot/Packages.
Vrui uses the PNG (Portable Network Graphics) image file format to save screenshots taken from a Vrui application window using the image handling library. If that library is not configured to support PNG images (see above), Vrui will automatically fall back to saving screenshots in binary PPM format.
TBW.
TBW.
Vrui contains full support for spatial audio using the OpenAL 3D sound API. Since OpenAL is not yet widely used, this support can be disabled in the makefile, removing dependency on the OpenAL header files and libraries. To disable OpenAL support, the value of the SYSTEM_HAVE_OPENAL variable can be set to 0. The Vrui makefile now contains code to automatically detect whether OpenAL is installed on the host system by looking for AL/al.h in /usr/include and /usr/local/include. If OpenAL is installed elsewhere, the SYSTEM_HAVE_OPENAL makefile variable needs to be set manually, and the paths to OpenAL need to be adjusted in BuildRoot/Packages.
As of version 4.0-001, Vrui contains native support for HTC Vive VR headsets. This support relies on the presence of SteamVR on the local computer. SteamVR can be downloaded through the Steam content distribution system at no cost, but it requires a Steam account, and an installation of the Steam client on the local system. Pre-packaged Steam client binaries are available for most Linux distributions, including Ubuntu (and Linux Mint) and Fedora.
Once the Steam client is installed, start it, create an account (also at no cost), select "Library" from the Steam client window, select "Tools" from the drop-down menu, and then look for SteamVR and install it. Once installation is done, the Steam client can be closed. It is not necessary to run the Steam client later to run Vrui applications on the Vive. In fact, we recommend never running the Steam client again to prevent automatic updates from breaking Vrui compatibility.
Vrui's makefile attempts to detect the presence of SteamVR on the local system, and build support for the HTC Vive if SteamVR is present. If Vrui was built before SteamVR was installed, Vrui's VRDeviceDaemon module needs to be removed before Vrui is built again. From Vrui's root source directory, run
rm -r o/g++-3.g0.O3/VRDeviceDaemon
and then run make again.
If Vrui does not find the SteamVR installation automatically, the path to SteamVR's root directory, which ends in the suffix /common/SteamVR, can be passed on make's command line. For example,
make STEAMVRDIR=/opt/Steam/SteamApps/common/SteamVR
If a custom SteamVR path was passed to Vrui's makefile during "make," the same path also needs to be passed to Vrui's makefile during "make install" or Vrui's Vive-related files will not be installed. For example,
sudo make STEAMVRDIR=/opt/Steam/SteamApps/common/SteamVR install
For more information, see "Setting up HTC Vive" and "Running Vrui Applications on HTC Vive."
As of version 1.0-035, Vrui contains a mechanism to optimally run on shared-memory multi-pipe rendering systems such as SGI Onyx or Prism, or newer multi-CPU computers with multiple graphics cards. Support for multithreaded rendering is enabled by setting GLSUPPORT_USE_TLS to 1 in the makefile. Since this somewhat impacts rendering performance, it is recommended to only enable multithreaded support if (one of) the target VR environments requires it.
If the host compiler and run-time environment do not support a __thread storage class for thread-local storage, SYSTEM_HAVE_TLS in BuildRoot/SystemDefinitions must be set to 0 to fall back to POSIX thread-local storage (for an additional performance penalty).
The easiest way to install Vrui is to cd to the Vrui-
Vrui contains a few settings that might need to be adapted due to different operating system or OpenGL versions. The settings that typically cause trouble can be changed from within the main makefile (they are listed in a section towards the beginning). If Vrui fails to build with compiler errors, that is the first place to look. The makefile lists which sources cause trouble, and how to address them.
The Vrui libraries and executables are by default built without debugging information and with full optimization (-O3). It is possible to build Vrui with full debugging information and without optimization by defining the DEBUG variable in the makefile. The easiest way to achieve this is to pass DEBUG=1 on the make command line, i.e., to type "make DEBUG=1" followed by "make DEBUG=1 install". Vrui is set up such that debug and non-debug versions can coexist in the same installation directory.
To make full use of the debugger, the Vrui application itself needs to be compiled/linked with debugging information as usual. The easiest way to achieve this is to use Vrui's included build system, in which case passing "DEBUG=1" to an application makefile will set everything up correctly.
If Vrui was built with support for HTC Vive VR headsets, the user's physical environment needs to be configured before Vrui applications should be run on the HTC Vive. In general, any Vrui utility or application using the HTC Vive requires that Vrui's device driver, VRDeviceDaemon, is running. To start VRDeviceDaemon in Vive mode, open a new terminal window and run:
RunViveTracker.sh
Leave the daemon running until it is no longer needed, then shut it down by pressing Ctrl+C in its terminal.
The device driver can be tested by connecting to it using Vrui's DeviceTest utility. From a second terminal, run:
DeviceTest -t 0 -p
This will continuously print the 3D position of the Vive headset until shut down by pressing any key. If the 3D position is initially invalid (no numbers, dashes only), hold up the Vive headset such that both tracking base stations can see it.
If tracking is working, run Vrui's RoomSetup utility:
RoomSetup Vive
and work through the setup dialog to configure the room's center point, forward direction, and establish protection boundaries. When done, save the setup through the button in the setup dialog and close RoomSetup.
The ExamplePrograms directory in the Vrui-
ExamplePrograms contains several very simple Vrui applications to show the basic development approach, and ShowEarthModel, one "realistic" application to visualize global earthquake distributions. MeshEditor contains a prototypical and fairly complex VR surface editing application, and VRMLViewer contains a stand-alone viewer for simple VRML files (it does not support VRML's full specification) that mostly serves as an example of how higher-level scene graph functionality can be layered on top of the Vrui API.
All applications can be built by running make in their respective directories. If Vrui was not installed in its default location (/usr/local), the VRUI_MAKEDIR variable at the top of each makefile needs to be changed to the directory named "make" under Vrui's root installation directory.
The example application makefiles show how to create debug/release versions without changing the makefile by respecting the DEBUG make command line argument ("make DEBUG=1") in the same way as the toolkit build itself.
During installation, Vrui installs its own build system in $(SHAREINSTALLDIR)/make. Vrui-based projects can benefit from this build system by using a makefile following the template makefile included in the build system directory. The makefiles provided with the Vrui example applications show how this should be done, and how it results in simple makefiles that build on any environment with a properly installed version of Vrui.
For compatibility with previous versions of Vrui, Vrui also creates a makefile fragment (Vrui.makeinclude or Vrui.makeinclude.debug) in $(SHAREINSTALLDIR)/make. The appropriate fragment should be included by the makefiles of all legacy Vrui-based projects to simplify compiling and linking.
Alternatively, Vrui creates a pkg-config metafile during build,
Share/Vrui.pc. This metafile can be copied to a location recognized by
pkg-config, such as /usr/lib(64)/pkgconfig, and can then be used to
retrieve compiler and linker flags required to build Vrui applications,
as in
g++ -o Foo pkg-config Vrui --cflags Foo.cpp pkg-config Vrui --libs
Vrui applications are started in the usual fashion, by typing the executable name from the directory containing the executable, and providing any required command line parameters. Vrui applications will configure themselves to the machine on which they are running by reading an appropriate root section in the Vrui.cfg configuration file in the installation's etc directory. The root section is determined by the following cascade:
By default, Vrui reads the section that has the same name as the local machine (as reported by hostname).
If an environment variable VRUI_ROOTSECTION exists, Vrui will use its value as the root section
If an application's command line contains the arguments
-rootSection
If the root section selected by the above cascade does not exist in the configuration file, Vrui will fall back to the root section compiled into the library (defaults to "Desktop").
The HTML pages in $(INSTALLDIR)/share/doc contain additional information about configuring, running, and using Vrui applications.
To run a Vrui application on the HTC Vive, first start Vrui's device driver in Vive mode as detailed above. Then, run any Vrui application and append -rootSection Vive to the end of its command line.
On Nvidia graphics cards, running a Vrui application on a Vive HMD requires telling the graphics driver to which video output port to synchronize OpenGL operations. If OpenGL synchronizes to the wrong display, the Vive will be unusable due to judder and lag.
Unfortunately, Nvidia's driver offers no functionality to select a synchronization output from inside a running application; the selection has to be made through the __GL_SYNC_DISPLAY_DEVICE environment variable. To simplify this setup, Vrui installs a helper script, OnVive.sh, alongside its executables (by default in /usr/local/bin). This script will attempt to detect to which video output port a Vive is connected, tell OpenGL to synchronize to that port, and then start a Vrui application. To run a Vrui application using the script, simply pass the application's full command line, minus the -rootSection Vive option, to the OnVive.sh script:
OnVive.sh
...
If OnVive.sh detects a connected and enabled Vive HMD, it will run the Vrui application on it. If it does not, it will print an error message and exit.