|FreeVR: Virtual Reality Integration Library|
FreeVR: User's GuideMarch 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:
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:
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.
The default inputs for the button inputs (normally found on a CAVE wand) are the three mouse buttons.
Joystick inputsThe 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 188.8.131.521 (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.
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:
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:
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:
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.