FreeVR: Virtual Reality Integration Library
User Guide




    Function List
    Library Dev
    Socket Interface


All materials
Copyright © 2015
William R. Sherman

FreeVR HomePage

FreeVR HomePage

March 20, 2015 for FreeVR Version 0.6f
Written by Bill Sherman (

General Introduction

Welcome to the home page for the FreeVR Free VR library; Free and Open. The library continues to progress, but it is sufficiently stable such that some operational virtual reality facilities rely on it.

Documentation on the current status of the library on various platforms, and interfaces to various I/O devices is included directly on this page. Much of the features of programming FreeVR can be seen in the tutorials. There is also a specific webpage with a listing of most of the functions that the application developer will need to use, plus a webpage on the ability to interface with a running VR application.

What is FreeVR

FreeVR is an open-source virtual reality interface/integration library. It has been designed to work with a wide variety of input and output hardware, with many device interfaces already implemented. One of the design goals was for FreeVR applications to be easily run in existing virtual reality facilities, as well as newly established VR systems. The other major design goal is to make it easier for VR applications to be shared among active VR research sites using different hardware from each other.

What FreeVR is not

FreeVR is not a VR content library. It does not provide a scenegraph layer, or other features often associated with such libraries like intersection testing and collision detection. It does not provide a physical simulation for objects in the virtual world. FreeVR is intended to work with many scenegraph and other libraries. While SGI's Performer library was the primary alternative for many years, it is no longer a primary focus (though if you have a machine with Performer, it will still work). More recently, the OpenSceneGraph (OSG) library has been used with several FreeVR applications, including some that make use of the Delta3D system. FreeVR has also been used with the OpenSG library, though no recent testing has been done. Also, some experimentation with the OpenDynamicsEngine has been done, with some preliminary new tutorials under development, and with more work to do.

FreeVR documentation

The documentation for FreeVR has been broken down into different areas depending on the particular task at hand. For the administrator of a VR facility, the administrator's guide focuses primarily on how to configure FreeVR to run with their displays. For the programmer, there is the overall programming paradigm description, plus separate function reference and tutorial pages. If the programmer desires to go beyond application programming and make modifications to the FreeVR library itself, there is a library development guide. And for the end user is a user's guide, plus a separate document on connecting to a running application to view and even modify parameters.

Unix manpages are also now being written to provide in-shell documentation to the application developer or facility administrator. Presently, manpages exist for the input test suite of utilities, along with an overview page for FreeVR itself, and one page documenting how to interface FreeVR with a Nintendo Wii™ remote (aka "wiimote").

Operating System Coverage

Presently, FreeVR is Unix-centric, and recent versions of FreeVR are tested primarily on these Unix-style operating systems:

  • Linux (2.6 kernel, w/ nVidia & ATI OpenGL) [many distributions]
  • Macintosh OS/X (Darwin w/ XFree86)
  • Cygwin under MS-Windows

These operating systems worked with older versions of FreeVR, but have not been tested lately:

  • SGI IRIX 6.x (o32, n32 & 64 bit)
  • BSD Unix (Free/Net/Open)
  • Solaris
  • HP-UX
  • Tru-64
  • AIX

Language API Bindings

Currently, C is the only language for which a fully developed API exists. Of course, C++ will also work, but no extra features have been added to complement it. However, many C++ applications have been written using the FreeVR library, including many student programming assignments, and interfaces to other libraries with only C++ APIs, such as OSG and ODE.


Graphics Libraries

Thus far, FreeVR has been interfaced to four graphics libraries:
  • OpenGL,
  • OpenSceneGraph,
  • Delta3D,
  • OpenSG, and
  • SGI's Performer.
Note however that examples for OpenSceneGraph and OpenSG are not yet included with the distribution.
An interface to the Inventor graphics API has worked in the past, and work continues. At this point, the focus is on the Coin3D implementation of the Inventor API.

Input Devices

Part of the reasoning for making FreeVR an open-source effort is to allow easy access to anyone interested in using the library who might have unusual I/O devices. (Of course, that's not the only reason or we would have simply provided a DSO interface.)

However, we knew that there had to be a minimal set of devices already implemented in order to get the ball rolling. And these devices also serve to provide sample source code for a variety of devices (not to mention we needed something for testing our applications):

  • X-windows (provides keyboard & mouse input -- useful for simulating VR inputs)
  • Win32 (used for keyboard and simulated inputs under Cygwin)
  • Static — a device with constant (or constantly changing) inputs
  • Generic Shared Memory (usable with systems that put values into shared memory)
  • Ascension Flock of Birds
  • InterSense IS-900
  • AR-Tracking systems via dtrack protocol
  • Polhemus Fastrak
  • Magellan (aka SpaceMouse) 6-DOF input device
  • SpaceTec SpaceOrb 6-DOF input device
  • SpaceTec SpaceBall 6-DOF input device
  • Fakespace Pinch Glove
  • Linux "joydev" game controller interface
  • Linux Event interface (aka "evdev")
  • Virtual Technologies CyberGlove (not thoroughly tested)
  • The VRUI VRDeviceDaemon
  • UNC's VRPN
  • Polhemus Patriot (partially developed)
  • Ascension MotionStar (partially developed)

For some other devices, the VRUI VRDeviceDaemon and the UNC VRPN library can be used to pass input information to FreeVR.

Downloading FreeVR

Download the current version of FreeVR: freevr_0.6f.tar.gz.

Older Versions:

You can also download Bill Sherman's FreeVR programming examples for OpenGL, or for Performer. These examples are technically not open source, but shared to help get new FreeVR programmers up and immersing themselves.

FreeVR Applications

In addition to the example applications above, there have been some interesting CAVE applications that have been ported to work with FreeVR.

The most interesting of these (which also happens to be open-source) is the AfterShock QuakeIII world loader application ported to VR by Paul Rajlich. The CQ3A Application can be downloaded from Paul's webpage. For best results with FreeVR, you will need a version later than 0.8.7.

The VMD (Visual Molecular Dynamics) tool for rendering molecules consisting of even millions of dynamically moving atoms has a FreeVR interface that can be enabled when compiling the library. VMD can be downloaded from the VMD Download page, with a free registration required.

Other fun and useful applications will be listed here as they become available.

Version 0.6f Enhancements

(released 03/20/15 for IEEE VR 2015)

Version 0.6f added a new variant to the FreeVR compile-time options: single-threaded. As the name implies, the single-threaded variant produces applications that do NOT spawn processes or threads to perform their separate tasks, but rather everything happens in one thread sequentially. Of course, this is usually not the best way to run a virtual reality application, so the primary use of this variant is in debugging, especially when the standard multi-process operation makes the debugging effort overly difficult.

There is also a new "debug.7fv" manpage.

Version 0.6e Enhancements

(released 10/01/14)

Version 0.6e is primarily a clean-up version with a handful of bug-fixes and other improvements. However there are no major new features.

The most important bug fix was to the ART DTrack2 input system parsing, which would occasionally hang on slower (or more highly taxed) systems.

Version 0.6d Enhancements

(feature frozen 09/14/13 in honor of the Jet Man at the Reno Air Races)

Version 0.6d has some advances in input devices, namely, there is now a VRPN interface, including the vrpntest program which will show all the VRPN outputs and their values as they change. The long-suffering evdev (or EVIO) interface is now complete, which expands the ability to read inputs from many devices through the Linux kernel event I/O system. There have also been enhancements to both the Vrui VRDeviceDaemon inputs and outputs to handle the new protocols for Vrui 2.x and 3.x generations.

Some of the commands for the telnet interface have been enhanced or expanded. It is now possible to toggle on and off window frame renderings to help view a current configuration. Plus some "nudge" commands to make configuration adjustments on the fly.

A new "-flag" option was added to both "serialspy" and "socketspy" to highlight particular values of interest while examining a data stream. Many new command line options were added to the input test programs — mostly to avoid the need for setting environment variables, though those still work as well.

Another new feature related to the input device test programs is manpages. Manpages were written for most of the current input systems, as well as serialspy and socketspy, plus some overview pages, including one on Wiimote interfaces to FreeVR.

Plus the usual suspects of bug fixes and output enhancements, including some which would cause mal-formed systems to hang with little or no explanation — now at least there is some explanation.

Version 0.6c Enhancements

(released 02/08/12 in honor of SuperBowl XLVI)

Version 0.6c has some advances in input devices, plus a handful of bug fixes and cleanups.

For the inputs, the Polhemus Patriot input device was enhanced. It works, but the Patriot device itself has some issues with flipping into different hemispheres.

A new "inputs" sample application is now compiled by default. This application just renders information about what inputs FreeVR is receiving. This serves both to help setup a new virtual reality installation, as well as being useful for using FreeVR as an input daemon (simultaneously providing a monitor of the values).

Finally, some very early prototype code was added for a "text" rendering process, which will also serve as a means of providing a FreeVR device daemon.

Version 0.6b Enhancements

(released 03/20/11 at IEEE VR 2011)

Version 0.6b has some new input device features, plus the usual bug fixes as necessary. New input devices include the AR-Tracking dtrack protocol, and the Polhemus Patriot Wireless. The ARTracking works very well, however the Patriot Wireless has some issues with its protocol (not sure why Polhemus didn't stick with their existing Fastrak protocol), so more work is required there. One new "output" device was also added -- the Vrui VRDeviceDaemon protocol can now be emitted by the FreeVR library, so now FreeVR can act as a Daemon to Vrui applications. There are some new stereo rendering modes that are under development, but the implementations are not yet complete, so they will be part of the forthcoming release.

Version 0.6a Update

(released 12/07/09)

Version 0.6a was created to indicate a break where support for clustering would be added to FreeVR. Unfortunately, that support has not yet been culminated. Some effort was put forth, but the task was not completed by those to whom it was assigned, so it has become incumbent on the primary author to pick up the ball.

In the meantime, there is at least one fancy new feature, and that is the ability to allow portion of the virtual world to be rendered from viewpoints separate from the primary view — typically the head of a second user.

Also, a new new "device" can now be handled — the VRUI VRDeviceDaemon. This then also allows any device handled by the VRUI daemon to now be read by any FreeVR application.

The last major update however was to the FreeVR tutorials. A handful of new tutorials have been added, many toward the beginning of the steps through FreeVR, so most of the tutorial programs have been renumbered.

And there are the usual bug fixes here and there.

Version 0.5g Update

(released 04/11/07 -- the Gonzo the Great version)

Of course, FreeVR version 0.5g fixes a few bugs over previous releases, but there are many other feature additions that make this release noteworthy. Among these features is the ability to work with the OpenSceneGraph graphics rendering library. We have also done some testing with the OpenSG rendering library. There are also some new function calls for "self-documenting" the user interface to the application. And there is now a Tcl/Tk based program "fvri.tcl" to provide users with a GUI interface to the running VR program. The documentation has also been improved in a few areas, particularly on how to view and interpret the running statistics information that is collected.

The webpage was also improved a little to allow for better navigation through the site. Hopefully the post-alpha version of this release will include a small gallery of sample applications.


© Copyright William R. Sherman, 2015.