FreeVR VR integration library

FreeVR is a VR integration library currently maintained by Bill Sherman. The design approach of FreeVR was to provide an API that call-for-call lines up with the CAVE library from the University of Illinois at Chicago. Occasionally new functionality was added, but little was left out. Another philosophical decision was to be as minimalist as possible, depending on as few other resources, and thus being easy to compile on just about any OS version.

There are pre-existing FreeVR Applications written at the University of Illinois and DRI as part of our immersive visualization ensemble. But before using a FreeVR application, one must first install and configure FreeVR.

FreeVR Versions

The FreeVR API has been very stable, so most versions from the past few years will work, though of course bugs are eliminated in each version and a handful of nifty features are generally added. The most recently released version of FreeVR (as of [02/29/24]) is 0.7e.

FreeVR Dependencies

Basic FreeVR depends only on two packages which are generally installed on any self-respecting computer:

OpenGL
X-windows

Optionally, FreeVR can work with:

OpenSceneGraph

On MS-Windows, FreeVR also requires:

Cygwin

Nothing else should need to be installed for the library, though some applications will make use of additional libraries.

Installing FreeVR

FreeVR can be downloaded from: FreeVR.org/Downloads. The Downloads page usually has the current version, the previous version, as well as the tail-end version of all the minor-change versions. (Note that as of now, FreeVR hasn't been declared reaching 1.0 status, although there have been about 43 tagged versions starting with 0.1a.)

These instructions have been tested with FreeVR version 0.7e (the latest version as of this writing), but should generally work for other versions of FreeVR.

Download FreeVR
Download from the FreeVR Download page
Untar in a local directory
% tar -zxf freevr_0.7e.tar.gz

% cd freevr_0.7e
Compile
For major OSes, there are quick targets that will build the library and some test applications:
- % make linux
- % make darwin — This is for MacOS (Darwin is the Mac window manager)
- % make cygwin — This is the MS-Windows version and requires Cygwin
There are also two specialty targets useful on Linux systems:
- % make pt — the pthreads-compatible version for Linux
- % make st — the single-thread variant for Linux
(this should all build in a handful of seconds)
There are additional build options, which can be obtained from:
- % make
Install
Presently, there is no "install" target, because when one builds from a Downloaded tarball, then that directory is sufficient to be the "install" directory, and if the "modules" system is used, the module file can just point to the "bin", "etc"", "man" and "src" directories — the latter being the directory with both the libraries and header files.
(NOTE: in the future, FreeVR will include an "install" build target to create the standard directory layout.)

That's it!

Configuring FreeVR

Configuring FreeVR can be a very difficult task. If no configuration file is available, FreeVR will default to rendering a desktop window with inputs that can be simulated through keyboard and mouse. Because it is often easier to begin with a working configuration and make alterations, a suite of sample configuration files are provided as part of the tarball. These can be found in the etc directory, and include options such as rc_sample_cave, rc_sample_cygwin, and rc_sample_vrpnserver. There is also an example personal configuration file named "freevrrc_home", which would be renamed to "~/.freevrrc".

Detailed information on creating/altering a FreeVR configuration file can be found in the online in the FreeVR VR Administrator's Guild.

Here are some configuration information nuggets:

Comments are denoted with the hash (#) symbol through the end-of-line;
FreeVR sections are contained in C-style curly brackets ({ and });
Statements not contained within curly-brackets are generally to set global effects;
Configuration files can read other configuration files, which is especially useful for the user's personal configuration file;
Conditional statements are available for setting a configuration, which allows a configuration to be depending on machine names or environment variable settings;
BUG: One issue to be aware of is that the "args" value of configuration objects is parsed such that the first occurrence in a string of the keyword is the one that is honored;

Compiling FreeVR Applications

Compiling FreeVR applications is fairly straight forward. In the compiling line, the header file should be included. E.g.:

-I/<freevr-path>/include

And in the linking line, the library should be included. E.g.:

-L/<freevr-path>/lib -lfreevr_64

If the PThreads variant is used, then more libraries are required:

-L/<freevr-path>/lib -lfreevr_64pt -ldl -lpthread

By default FreeVR will build two example applications: "travel" and "inputs". The "travel" application is meant to demonstrate the ability to walk around objects, most of which are fixed to the physical (real) world, and then travel relative to one object in the virtual world (a white pyramid). Object placement is primarily meant to be interesting in a 9'x9' CAVE-style VR system. The "input" application is intended to quickly visualize the state of all the VR inputs, and thus give a sense of whether they are being correctly read/interpreted. The "input" application also works well when FreeVR is being used for for of the side-effects by which VR inputs can be output to other applications (be they other VR systems or not).

FreeVR VR Tutorials

The FreeVR webpage includes a subpage of VR tutorial examples. Presently the only tutorials available for download is the OpenGL suite. However, there are also collections for building with OpenSceneGraph, and the ODE Physics Engine. In the (hopefully) near future, these will be added to the FreeVR webpage.

FreeVR Utility Suite

In addition to the FreeVR library for building new VR applications, the FreeVR package includes many additional tools, most of which are for testing various input devices and protocols. Perhaps the most useful of these are the tools that report VR inputs from the VRPN input server, the Vrui VRDeviceDaemon, and the DTrack server from AR-Tracking.

What these tools provide is a live output of whatever input values are transmitted from these servers. The output can be in one of three forms:

Readable text to the terminal
CSV text to the terminal
ASCII-art style rendering to the terminal

Other input readers include several for specialized input devices, such as the Space Navigator, Polhemus Fastrak (and related) devices.

In addition to the input-testing utilities, there is also a pair of tools useful for reverse-engineering data streams of input devices. One of these ("serialspy") was useful during the era when many devices connected to computers via the RS-232 hardware protocol and sent serial data to readable ports. The other tool ("socketspy") is similarly useful to help interpret data streams that are sent via TCP/IP protocol from client to server. Both act as "man-in-the-middle" interceptors that output the values to the terminal, and also continue to pass the data between client and server to allow them to continue functioning normally.

FreeVR

Contents