FreeVR: Virtual Reality Integration Library
User Guide




    Function List
    Library Dev
    Socket Interface


All materials
Copyright © 2015
William R. Sherman

FreeVR: User's Guide

FreeVR: User's Guide

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


This guide is for the user of applications compiled with the FreeVR library. Therefore, topics such as how to configure a FreeVR application to run in a CAVE™ environment are not included here. It is assumed that a VR system administrator has already configured your system for the available hardware using the FreeVR Administrator's Guide.

What this guide does cover is how to use FreeVR in simulator mode, and (soon) how to make some basic adjustments to the configuration that a user might be interested in.

The other FreeVR guides are:

Environment Variables

When a FreeVR application is executed, there are a handful of environment variables whose values have an effect on how the initial configuration process will take place:

The root directory of the FreeVR installation, and used to read a system-wide configuration file:

The user's home directory, which is used to look for a user-specific configuration file:
Note, the user-specific configuration file is read after the system-wide configuration, and thus can override any of the configuration parameters in a user customizable way.

The FREEVR environment variable can be set to contain a configuration string, which is applied to the configuration settings after the user-specific file is read, and thus can override options the user normally prefers. By using an environment variable, a user can have a settings that are specific to a particular command shell, and all application run from that shell will have these unique parameters. This can also be a way to provide certain command settings when applications are run from a menuing system — for controlling stereo rendering for example.

Set level of debugging output that a FreeVR application will generate. Setting this value happens last, and thus none of the other means of reading configuration commands will override this setting — hence the NO tag.

Set an extra, exact level of debugging output that a FreeVR application will additionally generate, in addition to all messages at or below the general debug-level. Setting this value happens last, and thus none of the other means of reading configuration commands will override this setting — hence the NO tag.

There are also many environment variables that pertain to debugging portions of the library such as inputs or serial communication.

Inline application help

The FreeVR library provides the mechanism for FreeVR applications to supply information about their basic operation directly on-screen. To summon this basic application documentation, press the ./Del key on the numeric keypad in any of the rendering windows. This will bring up a semi-transparent box with a white border. If all you see is a small square in the upper left corner of the screen, then the application developer(s) did not opt to make use of this FreeVR feature.

Running FreeVR in "simulator" mode

When a FreeVR application is executed on a machine with no specific configuration information, it will default to a configuration with inputs taken from the keyboard to simulate typical inputs found in most CAVE™ VR displays. Keystrokes allow the user to virtually press the wand buttons, move the joystick, and move around the head and wand.

The user can reconfigure the default keymappings using the configuration instructions (that will be) described below. However, a default mapping has been assigned that will be familiar to users of the EVL CAVE library.

Manipulating the inputs

The FreeVR library avoids the use of mappings of specific keys to particular functions by the application. Instead, keys are mapped to button inputs which can then be used by the application. So, by default, the 'Escape' key is mapped to button(0), which is the de facto method of terminating CAVE-based VR applications.

Button inputs

The default inputs for the button inputs (normally found on a CAVE wand) are the three mouse buttons.

Joystick inputs

The valuator inputs from the standard wand joystick are based on the location of the mouse pointer inside the simulator view window. The joystick inputs are only active while the spacebar is depressed.

6-DOF Tracker-sensor inputs

Translating a sensor

The basic method of moving a sensor is to translate it using the four arrow keys.

By default the arrow keys move the sensor in the X-Z plane (ie. parallel to the floor). The 'f' and 'v' keys move the sensor up and down (in the Y direction) respectively. There are several ways to modify this behavior. While holding down the 'left-shift' key, the Y and Z movements are reversed. Thus the arrow keys now move the sensor in the X-Y plane. By pressing the one key, translation becomes relative to the orientation of the sensor. Thus the up-arrow key will move the sensor in the direction it is facing. Pressing the one key again returns to absolute translation mode.

NOTE: a change in the behavior of the XOrg implementation of X-Windows made shortly after version (which is the version used by Fedora-11) resulted in abnormal behavior in the keyboard controls of 6-DOF devices. For a yet-to-be-determined reason, only keyboard releases are recognized.

The mouse can also be used to translate the sensor.

  • 'q' — move the sensor in the X-Y plane with the mouse
  • 'a' — move the sensor in the X-Z plane with the mouse
The mouse method of translating a sensor uses the location of the mouse pointer within the simulator window to control the velocity of movement.

Normally, the sensors are restricted to move only within the "CAVE volume" depicted in the simulator display. This restriction can be disabled and reenabled with the 'two' key.

The sensor can be reset to the origin with the 'r' key. This also resets the orientation.

Rotating a sensor

The basic method for rotating a sensor is with the following keys:

  • 'h' — rotate left about the Y axis (azimuth)
  • 'j' — rotate down about the X axis (elevation)
  • 'k' — rotate up about the X axis (elevation)
  • 'l' — rotate right about the Y axis (azimuth)
  • ',' — rotate counterclockwise about the Z axis (roll)
  • '.' — rotate clockwise about the Z axis (roll)

The four arrow keys can also be switched from controlling translation to rotation by holding down the left-alt key.

Selecting a sensor

The default configuration creates two sensors that can be manipulated. One for the user's head, the other for a wand controller. Upon startup, the head sensor is under the control of the user. This can be changed with the 'n' key, which selects the "next" sensor. The user can also specify a specific sensor with the 's' (skull) and 'w' (wand) keys.

Overall input chart

Here is a table that summarizes the default input controls:

    Button Input
  • 'esc' — button 0 (terminate button)
  • 'left mouse' — button 1
  • 'middle mouse' — button 2
  • 'right mouse' — button 3

    Joystick Input

  • 'space' — map mouse location to joystick (valuator 0 and valuator 1)

    Sensor Translation

  • 'up arrow' — move sensor forward in Z
  • 'down arrow' — move sensor backward in Z
  • 'left arrow' — move sensor left in X
  • 'right arrow' — move sensor right in X
  • 'f' — move sensor up in Y
  • 'v' — move sensor down in Y
  • 'left-shift' — swap the Y and Z movement controls
  • 'q' — move the sensor in the X-Y plane with the mouse
  • 'a' — move the sensor in the X-Z plane with the mouse
  • '1' — toggle between absolute and relative movement
  • '2' — toggle the space restriction on movement

    Sensor Rotation

  • 'h' — rotate left about the Y axis (azimuth)
  • 'j' — rotate down about the X axis (elevation)
  • 'k' — rotate up about the X axis (elevation)
  • 'l' — rotate right about the Y axis (azimuth)
  • ',' — rotate counterclockwise about the Z axis (roll)
  • '.' — rotate clockwise about the Z axis (roll)
  • 'left-alt' — map the four arrow keys to azimuth and elevation rotations

    Sensor Selection

  • 'n' — select the next sensor
  • 's' — select the head (skull) sensor
  • 'w' — select the wand sensor

    Sensor Misc

  • 'r' — reset sensor's location and orientation
  • '8' — reset all sensors' location and orientation

Manipulating the view

Unlike the CAVE library, FreeVR currently does not provide a means to change the simulator view from the external perspective view (ie. viewing mode 2 in the CAVE library). While the CAVE library allows the user to switch to head-perspective (mode 1) and wall-perspective (mode 0) views, in FreeVR these must be created as separate windows.

To change the view in the FreeVR simulator display, the following keymappings on the numeric keypad are the default:

  • '+' — move away from the origin
  • '-' — move toward the origin
  • '5' — reset view to center position
  • '4' — rotate about the Y axis
  • '6' — rotate about the Y axis
  • '8' — rotate about the X axis
  • '2' — rotate about the X axis

  • 'Enter' — set the current view as the home position
  • '7' — jump to the home position view

  • './Del' — toggle the online help
  • '*' — toggle the frame rate display
  • '9/PgUp' — toggle the timing statistics output
  • '3/PgDn' — toggle the input operations output
  • '0/Ins' — toggle the simulator graphics
  • '1/End' — toggle the world graphics
  • '/' — toggle whether this window will appear in the simulator views

Note, however there are three caveats in the current implementation of the FreeVR library. First, key repeating is disabled in FreeVR input windows, so holding down a key to continue a view change won't work — you need to repeatedly press the key (hopefully we'll fix that in a near-future release). Second, if the "xmodmap" is strange (as is the case for at least Solaris) many of the keys won't work. In this case, you will need to change your X keyboard mappings to have the keypad operate in a more expected manner.

© Copyright William R. Sherman, 2015.