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:
One a configured VR system, running a FreeVR application is a simple executable that can be run via command line, or via a GUI scripting interface (such as with Python-TK). For example, to run the CAVE Quake III Arena application on a terminal command line:
% cq3a [cq3a-options]Of course different applications may have different options that can be provided. In the case of cq3a, if there is a world database available no options are required.
When a FreeVR application is run at the shell, the user will typically see a simple report of the running system. That report will look something like this:
When the "debug level" is set to greater than 2, then there may be more informational output, and if the debug level is set higher, more and more output for debugging purposes will be produced. Thus, for a standard user on a pre-configured system, a debug level of 2 (aka almost always) is good. (For the very confident, setting the debug level to 1 (aka always) will produce a little less output. The debug level can be set via environment variable (see below), or in the FreeVR configuration file (aka ".freevrrc").************************************************* ** FreeVR library version: FreeVR Version 0.6g-beta ** ************************************************* FreeVR: **** Configuring the System! **** FreeVR config: Reading string "Default Config String". FreeVR config: Using system 'simulator' FreeVR config: Reading file "/home/<user>/.freevrrc". C A V E Q U A K E I I I A R E N A --------------------------------------- by Paul Rajlich [followed by more CQ3A-specific output] FreeVR: **** Initializing the System! **** FreeVR: Process "default-visren" spawned! Pid = 1237655, spawn time = 2.258985 FreeVR: Process "simulator-input" spawned! Pid = 1237656, spawn time = 2.259294 FreeVR: Inputs for device 'simulator-indev' are NOT YET created. FreeVR: Inputs for device 'vruidd-output' are NOT YET created. FreeVR: Still waiting for 'simulator-indev' inputs to be created. FreeVR: Process "default-telnet" spawned! Pid = 1237657, spawn time = 2.259446 FreeVR (telnet): Connect to 'indy.cam.nist.gov:3000' to send commands to FreeVR FreeVR: >>>>>> Inputs for all 2 devices created. <<<<<< ================================================== FreeVR Version = "FreeVR Version 0.6g" Compiled: Apr 22 2021 at 00:05:42 on localhost (Linux 4.18.0-240.22.1.el8_3.x86_64)[linux2.6-glx-64] with GLX Using System = "simulator" (initialized = 0) debug level = debug:aalways (2) debug exact = debug:none (0) visrenmode default = "mono" (0) processor lock default = "default" InputMap = "default" 2 input devs = [ "simulator-indev" "vruidd-output" ] (initialized = 1) 1 users = [ "default-user" ] (initialized = 1) 1 eyes = [ "default-user:cyclops" ] 1 eyelists = [ "default" ] 1 windows = [ "default" ] 4 processes = [ "built-in main" (1237654) "default-visren" (1237655) "simulator-input" (1237656) "default-telnet" (1237657) ] ================================================== FreeVR: **** FreeVR library startup complete. ****
For a complete list of debug levels, see the debug.1fv manpage.
The output shown above indicates what version of FreeVR the application was compiled with, along with some of the settings, such as with the GLX graphical interface, and possible the pthread or single-thread variants of the library. Plus details about the operating system the library was compiled on are listed, along with the date and time the library was built. These details are often helpful when debugging issues that might arise from using a library that is out-of-sync with the application code.
The above output also indicates the type of system being run. In this case a simulated CAVE view is provided, with a "simulated-input" process to control virtual position trackers, valuators and button presses. Also this system has a default-telnet process running which enables a user to have extra access to the internals of the running VR application. (See the accompanying Telnet/Socket documentation" for more details.)
If there are unrecoverable errors, then it may simply be a fault in the configuration file, in which case the FreeVR Administrator's Guide should be consulted. Deeper issues may require information from the FreeVR Application Development Guide.
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:
- FREEVR_HOME
- The root directory of the FreeVR installation, and used to read a system-wide configuration file:
$FREEVR_HOME/.freevrrc
- HOME
- The user's home directory, which is used to look for a user-specific configuration file:
$HOME/.freevrrcNote, 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.
- FREEVR
- 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.
- FREEVR_DEBUGLEVEL_NO
- 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.
- FREEVR_DEBUGEXACT_NO
- 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.
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.
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.
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.
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 1.6.1.901 (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.
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.
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.
Here is a table that summarizes the default input controls:
Joystick Input
Sensor Translation
Sensor Rotation
Sensor Selection
Sensor Misc
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.