FreeVR HomePage

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. Traditionally FreeVR has been used in large-scale CAVE-style virtual reality facilities, many of which use virtual reality for data analysis. Thus many of the applications that integrate FreeVR were developed for data visualization, though there are several developed to demonstrate various features of virtual reality, plus it was used for several years for college courses on VR, so several student projects have made use of it as well.

It continues to be used in CAVE VR facilities here and there, and potentially can work with HMDs as well, though it presently lacks the lens counter-warping needed to work effectively. That is on the todo list for the near future.

FreeVR also comes with several utility programs that can be very useful for VR development even when the full library itself is not used.

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 an instructional 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 (now defunct) 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 divided 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.

• User Guide
• Application Development Guide
  • Functions Reference
  • FreeVR Application Tutorials
• Administrator's Guide
  • Socket/Telnet Command Reference
• Library Development Guide
• Manual Pages

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 and later, 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 (i.e. in over a decade!):

• 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

• OpenGL,
• ANARI,
• OpenSceneGraph,
• SGI's Inventor (aks Coin3D).

  The following graphics libraries are deprecated:

• Delta3D,
• OpenSG, and
• SGI's Performer.

Note however that only examples for OpenGL-1 are included with the distribution.

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 plugin 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 input devices and input device styles (not to mention we needed something for testing our applications):

Inputs:

• X-windows (provides keyboard & mouse input — useful for simulating VR inputs)
• Linux "joydev" game controller interface
• Linux Event interface (aka "evdev" and "evio")
• Win32 (used for keyboard and simulated inputs under Cygwin)
• Static — a device with constant (or constantly changing) inputs

• AR-Tracking systems (6-DOF position tracker) via DTrack2 protocol
• Ascension Flock of Birds (6-DOF position tracker)
• InterSense IS-900 (6-DOF position tracker)
• Polhemus Fastrak (6-DOF position tracker)

• Magellan (aka SpaceMouse) 6-DOF input device
• SpaceTec SpaceOrb 6-DOF input device
• SpaceTec SpaceBall 6-DOF input device
• Fakespace Pinch Glove
• Virtual Technologies CyberGlove (not thoroughly tested)

• UNC's VRPN
• The VRUI VRDeviceDaemon
• Generic Shared Memory (usable with systems that put values into shared memory)

  ---

• Polhemus Patriot (partially developed) (6-DOF position tracker)
• Ascension MotionStar (partially developed) (6-DOF position tracker)

For some other devices, the VRUI VRDeviceDaemon and the UNC VRPN library can be used to pass input information to FreeVR. Such as the HTC/Valve Lighthouse and Razer Hydra devices. On the output side, FreeVR can act as an input device server, and thus output data via some active VR protocols. Thus FreeVR can act as a translator between input devices and systems that understand VRPN or other protocols, but are missing one or more desired inputs. (Alternatively, FreeVR can manipulate incoming input data and output it in an altered form.)

Outputs:

• UNC's VRPN (though limited to one active connection)
• The VRUI VRDeviceDaemon
• Collabora's Monado OpenXR runtime via the remote input interface
• A configurable shared-memory mechanism — enabling Argonne's TrackD and VisBox interfaces

Recording:

Downloading FreeVR

Download the current version of FreeVR: freevr_0.7e.tar.gz (02/29/24).

Older Versions:

• freevr_0.7d.tar.gz (06/07/22).

• freevr_0.6g.tar.gz — the last of the 0.6 series (05/04/21).
• freevr_0.5g-gamma.tar.gz — the last of the 0.5 series (04/11/07).
• freevr_0.4g.tar.gz — the last of the 0.4 series (06/05/03).

You can also download Bill Sherman's FreeVR programming examples for OpenGL 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 visbox.com 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.

Library Updates

Version 0.7e Enhancements

Version 0.7e has no stand-out new features, but updates several existing features, and includes some significant bug fixes.

There were a collection of updates and fixes to the input/output devices. Bugs were fixed in the VRPN and DTrack input options. A specific bug for VRPN was the initial values of buttons were incorrect, and for DTrack, new message types are now handled, plus the "screen-rendering" for dtracktest now works. On the output side of things, the VruiDD protocol-adjustment code that ensures both sides are speaking the same language was fixed, which improves both the vruidd input device, and also the vruiddtest program, and the stream output device can handle the current "remote" protocol for Monado ("mndrmt3").

A few improvements were made to the telnet interface. A new "status" command was added to give a quick overview of the state of the FreeVR application — whether it's running smoothly, or has some issues. Generally problematic items are now reported in red, which is now true for most of the information provided through the "telnet" interface.

In a similar vein, the inputs program now shows all the inputdevices and will highlight in red any that are non-operational. Another enhancement to the output provided by FreeVR is the inclusion of a time value for most of the information reported during startup, and shutdown. This time is reported as the number of seconds since the application was executed.

Much work was done to enhance FreeVR's robustness. This includes better messages from FreeVR when things are not as they should be, but also more safeguards were added to reduce the times when things go wrong — including when they go wrong because of an error in the configuration file. As part of this, additional calls to vrTrace() have been added to various danger spots, which should provide more useful information for debugging when things do go wrong. As always, the trace information can be obtained through the telnet interface, but for FreeVR 0.7e a new "debug level" was created — "TerminalTrace, which will output all the available process trace information when FreeVR terminates. NOTE: By default the 40 previous trace messages are maintained, but this number can be altered (at compile-time) by changing the value of VRPROC_NUMTRACEMSGS in "vr_debug.h".

Version 0.7d Enhancements

Version 0.7d has a few new features and of course a few bug fixes. The most significant addition is the ability to record and playback inputs (using the VRPN protocol.

The major thing to report, though, is that this version fixes a major bug that occurs when screens are in a particular orientation (such as a floor projection that is oriented toward a screen other than the front screen).

Another important upgrade is that this version fixes a somewhat significant bug in the VRPN protocol parsing (and producing).

The big "new" feature is the ability to record and playback input events. As mentioned in the "Input and Output" section above, this is accomplished using the VRPN protocol, so the stored data is actually just the output from FreeVR acting as a VRPN server, and then the VRPN reader function can later reuse this data to control the inputs. (Or vrpntest can be used to convert the data to CSV format.) As part of this, a new "-govern_time/-gt" option was added to vrpntest, as well as a "govern_time" flag for the VRPN input device type in FreeVR.

A new "output" protocol was added to FreeVR called "stream". The most generic form of this is to simply output CSV (comma-separated-value) data of the tracking. However, another new included protocol streams raw data in a form usable by the Monado (OpenXR) remote interface reader. (This was not the intent of that reader, but it works well for adding new tracking data into the Monado OpenXR runtime).

And finally here's a summary list of some other improvements:

• The socketspy tool was enhanced with a "-swapendian" flag that can be used when outputting 4 and 8-byte integers or floats.
• The default simulator inputs now include a 2nd hand-controller
• The FreeVR configuration language can now accept dots (".") as separators for matrix definitions. (This makes it clearer that operations such as rotate and translate are operating on a particular matrix.) (The underscore ("_") syntax will remain for backward compatibility.)
• New nudge commands (nudgex, nudgey, and nudgez were added to the telnet interface for the window configurations. These changes will be immediately reflected by any windows with the showFrame flag set.
• Matrix debug output now duplicates any whitespace in the "before" argument on each line — making them more readable.
• Now included is a freevrlib.vim VIM syntax file that highlights FreeVR functions, enums, defines, etc. while editing source code in the VIM editor.

Version 0.7c Enhancements

Version 0.7c has several enhancements, and the biggest new feature addition is the ability to generate VRPN output! (Now of course there are some caveats with that; namely that it can only handle one client at a time, it presently operates in simplex mode, and also only operates on the TCP protocol. But it can be very useful when one needs to generate simulated inputs to a VR tool accepting VRPN protocol, or even to translate data from one input stream into VRPN.

On the configuration front, it is now possible to give initial position information for 6-sensors (both simulated and real), that can place the head, hands, whatever at particular locations and orientations at startup. Another configuration improvement is that the tilde ("~") character can now be used at the beginning of file-paths to represent the user's home directory.

A long-standing bug with the use of arrow keys in the Xwindows simulator has been fixed — they now operate as expected. (This is actually a work-around for an X11 bug that was introduced in 2010 or so, about the time of Fedora-13. The X11 bug is that phantom key-presses are generated, often when a key is first pressed.)

Another "finally" addition is the use of actual masks/flags for controlling the rendering of particular aspects of the simulator view. This can be set in the configuration, and altered through the telnet/socket interface.

I also added a new feature to the socketspy tool that allows it to now output 4-byte integers, 4-byte floats and 8-byte doubles. Of course there's a caveat — this output assumes 4-byte-alignment.

There were some other minor additions, such as the ability to generate a GraphViz/dot graph description of the FreeVR system, and another to add a 100-step running average of the frame-rate (FPS100).

And finally, I did some tests with the OpenSceneGraph (OSG) and ANARI rendering libraries. The OSG part of this was merely to test the existing OSG examples with the current FreeVR, and with the version 3.6.5 of the OSG library. (They work!)

Version 0.7b Enhancements

Version 0.7b (the third release in about three weeks!) has no external enhancements — it was going to be two weeks, but it took me one full week to write a single manpage. This version was entirely meant for cleaning out old code, and making some of the remaining code a little safer. (For example using snprintf() instead of sprintf(), and also providing the actual variable to sizeof() instead of a type, which could change).

The one visible sign of change in this version is a new (and very lengthy) "telnet.7fv" manpage — telnet(7fv).

Version 0.7a Enhancements

Version 0.7a was planned to have one basic enhancement, which is to improve the parsing to better handle block-statements and conditionals. Prior to this version these operations generally worked, but not in all circumstances. This should be remedied by this new version. There were also a couple other minor changes, but nothing that affects the API.

Version 0.6g Enhancements

With a five year gap since the previous release, one might expect a mountain of enhancements to the FreeVR library. And there have been some needed improvements, but in truth, for much of those five years, FreeVR development was generally in a state of hiatus. But, as indicated, there were indeed some beneficial improvements to the library.

Perhaps the most visible is the addition of a "-screen" rendering option to both the "vrpntest" and "vruiddtest" input device testing applications. Like all the input-test programs they provide quick assurance of a working input system, and can also help with configuration.

The telnet/socket interface also had some additions that provide some useful improvements to testing and configuring a FreeVR system. In particular, many more "nudge" commands have been added beyond those for "nudging" the location of a window. There are now nudge options for shifting the origin of an input system as well as the individual position tracked receivers of an input device. A history feature was also added to the telnet/socket interface allowing users to both review past commands and also to repeat them using the familiar bang ("!") notation. And finally, the telnet/socket interface was improved by no longer "lingering" on a port, and thus making the interface port immediately available for the next program without waiting 60 seconds.

A new configuration option ("user_travel") was added as a setting for user, system, and the general default settings that places the user at the given location at start-up.

A new test program (glxtest) was developed to test the general OpenGL rendering system, using the SDL2 API for windowing. This tool can also help with ensuring correct operations with mathematical functions.

And one of the big under-the-hood changes to the library is a review of most of the matrix and quaternion mathematical operations, including making the memory layout of a 4x4 matrix more clear, and thus helping clean-up the understanding of the use of the vrMatrix type.

Finally, one other under-the-hood change to the library was the clean-up of the single-thread variant which was included in the 0.6f release of library. This variant runs all the "threads" on a single, sequential, process. Mostly this is for debugging situations where multi-threading makes debugging difficult. Note that since the telnet/socket thread blocks for user input, that feature has been disabled in the single-thread variant.

Version 0.6f Enhancements

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 — debug(7fv).

Version 0.6e Enhancements

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

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

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

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

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

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.

Enjoy!