Configuring VR software for a particular hardware system can be a daunting task due to the complexity and diversity of the environments and hardware in use. In addition to this, many users will need to switch between immersive VR hardware and desktop simulators during development, or between one hardware system and another.

VR Juggler's inherent flexibility increases this complexity. VR Juggler components such as displays and device drivers can be combined in many ways. For example, a configuration could mix simulated and real input devices. Or, hardware permitting, VR Juggler could use two separate head-mounted displays (HMDs) simultaneously. Input devices can be chained together, manipulated in a variety of ways, and mapped to different names. The possibilities are endless - but so are the potential pitfalls.

VR Juggler's configuration system was designed to simplify this task as much as possible. While VR Juggler uses plain text configuration files, these files are structured and organized. VR Juggler's config files can be written in a modular fashion, so that different components or hardware features can be easily mixed together. Finally, VR Juggler provides a GUI tool, VjControl, for editing configuration files. The GUI can prevent many kinds of errors and make the user's task easier by presenting the available options, valid arguments, help information, and so on.

When a VR Juggler application is initialized, it creates an internal database of configuration information. This database will contain information about the kind of IO devices available, the display windows VR Juggler should open, and lots of other stuff.

Typically, this database will be filled up by reading one or more configuration files. With many VR Juggler applications, the names of config files to load are given as command-line arguments when the program is run. For example:

% cubes ~/.vjconfig/simstandalone.config

runs the cubesdemo program and tells it to load a configuration file called simstandalone.config, which provides a basic simulator-mode configuration for running applications.

Configuration files can be stored in serveral places:

One of the difficulties of managing a VR system is the rapid proliferation of configuration files. If the entire configuration is read from a single file, then there must exist separate files for every possible permutation of configurations - simulators, projection systems, projection systems with simulated input devices, or configured with monoscopic displays for photo sessions, or monoscopic displays and simulated input devices, etc. Keeping all these files up-to-date can become a full-time job.

VR Juggler sidesteps this problem with the concept of modular configuration files. Instead of listing a single configuration file on the application's command line, we list several. Each file contains configuration information relevant to a particular part of the system. For example, one could define all the displays to be used, while another could define the input devices, and a third could describe how those inputs are mapped to a user's head, glove, wand, etc. There could be several variations of each file to choose from: display configs for an HMD, simulator window, desk, monoscopic desk, etc.; input config files for several varieties of hardware, or the user's preferred simulator setup. So long as a consistent set of names are used for input devices and so on, these files could be freely mixed and matched, eliminating the need to have a separate file for every possible combination.

The VR Juggler distribution includes several examples of modular configuration files in the directory $VJ_BASE_DIR/share/Data/configFiles. The sim.*.config files can be used in various combinations to run an application with various kinds of simulator devices. For example, a basic simulator configuration with one display window and a wand would use these files:

Other files could be used to change the basic configuration. For example, to use a simulated glove instead of a wand, the user would replace sim.wand.mixin.config with sim.glove.mixin.config.

While modular configuration files provide a lot of flexibility, users will not want to list four or five separate config files on the command line every time they run a program. Typically, a small set of combinations will see the majority of use. For example, a fully simulator configuration will be used heavily (but each developer is likely to have a slightly different idea of the preferred simulator configuration).

To provide ease of use - referencing a complete configuration with a single name, while avoiding proliferation - VR Juggler config files feature an include directive, similar to the #include preprocessor directive of C or C++. Thus, a user can create a config file which simply references several files in the system repository. He only needs to keep track of the single file's name, but when any of the included files are updated, he automatically sees the changes.

The building blocks of VR Juggler config files are pieces of data called ConfigChunks, or “Chunks” for short. There are many different kinds of Chunks, and each one contains the complete configuration information for a particular component of VR Juggler. These components can be things like display windows, input device drivers, the VR Juggler performance measurement system, and so on. To give you a better feel for the concept, here's a list of some of the kinds of chunks used by VR Juggler 1.0:

When VR Juggler reads a configuration file, it compiles a list of all the ConfigChunks in the file and then tries to find a VR Juggler component that knows how to deal with it. For example, a Flock of Birds Chunk would be passed to the Input Manager, which would create and activate an instance of VR Juggler's Flock of Birds driver.

So what's inside a ConfigChunk? Lots of stuff - and lots of different stuff, depending on what kind of Chunk it is. After all, the information the Input Manager needs to set up an input device doesn't have a lot in common with what the Display Manager needs to open up a display window.

The one thing that all Chunks have in common is that they all have names. Names are used to distinguish between multiple Chunks of the same type. For example, a configuration file for a CAVE-like device might define several Surface Display Chunks, with names like "Front Wall", "Left Wall", "Floor", and so on. It's important that Chunks have unique names. If VR Juggler reads two ConfigChunks that have the same name, it will assume that the second one is a redefinition or reconfiguration of the first one, and it will forget the first one and just use the second definition.

The rest of the Chunk consists of a list of Properties. Properties are individual pieces information. Continuing our example with a Flock of Birds tracking system, the Properties would include things like the name of the serial port to connect to, the baud rate to use, the positional offset, and so on. To illustrate, here's what it looks like when you view a single ConfigChunk in the VjControl program:

Figure 2.1. Example Config Chunk

"Instance Name" is the name of the Chunk - in this case, "flock_o_birds", while its type is "Flock" (the type is usually show in the window's title bar). Below that are the various properties - "Baud Rate", "Port", etc. Different properties take different kinds of values - Port takes a string, while Baud Rate takes an integer. The Translation property is interesting because it takes three separate floating point numbers. There are also Boolean properties and properties whose values are the names of other Chunks (so that you can have Chunks that refer to other Chunks).

For every kind of ConfigChunk there's an object called a ChunkDesc - short for "Chunk Description". ChunkDescs live in ChunkDesc files - and where are they? The primary VR Juggler ChunkDesc file is $VJ_BASE_DIR/share/Data/chunksDesc - it defines all the different kinds of chunks that VR Juggler beta1 knows about and needs. When a VR Juggler program starts up, one of the first things it does - even before it reads its config files - is to read the primary chunksDesc file.

Later in the beta series, VR Juggler will have the ability to load user-specific ChunkDesc files. These might include ChunkDescs for application-specific ConfigChunks.

If you've read this far, you know what VR Juggler's config files are, and you know what they're made of - lists of ConfigChunks. You also know that there are a lot of different kinds of ConfigChunks. Where do these different kinds of Chunks come from? How does VR Juggler know how to make a "Surface Display" Chunk that's different from a "Position Proxy" Chunk?

So, a particular kind of ConfigChunk is defined by a ChunkDesc. So what's in a ChunkDesc? Information about all the properties in the Chunk, with their names, and types, and number of allowed values. There's also help strings and other information used to make the VjControl program a little more user-friendly.

Here's a breakdown of the contents of a ChunkDesc:

VR Juggler defines two ConfigChunks which don't correspond to components of the VR system itself, but rather impact how configuration files are loaded in the first place.

VR Juggler gives you a great deal of latitude in defining displays. For example, you can use a combination of surface displays and simulator displays, or maybe just one or more simulator displays. Each display window is configured by a Simulator or Surface Display ConfigChunk. To add a new display window, simply add a new Display ConfigChunk to your configuration file and edit it to taste.

Any input devices that are defined in your config file will be initialized at application startup. So, to add a new device, all you have to do is add a ConfigChunk which describes its configuration. This section describes the ConfigChunks for the input devices supported by VR Juggler.

The Environment Manager (EM) is the part of VR Juggler that controls communications with the GUI program, VjControl. It also controls VR Juggler's performance monitoring capabilities.

The VR Juggler control program, VjControl, also uses some ConfigChunks for its own configuration. Generally, these will be kept in a separate file ($HOME/.vjconfig/vjcontrol.config).

VjControl is a Java application designed to take full advantage of Sun's Java Foundation Classes (the "Swing" classes). The current version requires at least JDK1.2, though JDK1.3 is recommended.

Before trying to run VjControl, you should perform the steps discussed under "User Setup" in the VR Juggler Getting Started Guide. In particular, make sure all your environment variables are set correctly.

It is important that you create a ~/.vjconfig directory, as this is where VjControl stores its own preferences.

You should also find out where the VR Juggler config files you should use are located. The VR Juggler distribution includes a number of sample config files in the directory $VJ_BASE_DIR/share/Data/configFiles. Your system administrators may also have a location for customized config files. For ease of use, you may wish to copy commonly-used config files to your ~/.vjconfig directory. This is also a good place to keep any config files that you modify to your own tastes.

On Unix/Linux systems, the command is vjcontrol; on Win32, the command is vjcontrol.bat. If $VJ_BASE_DIR/bin is not in your search path, you will need to give the entire path to VjControl on the command line.

VjControl's Preferences control what files are loaded automatically on startup. There are also command-line arguments that can be used to load files at startup. With the default preferences, VjControl will attempt to load $VJ_BASE_DIR/share/Data/chunksDesc, which contains definitions for the basic types of VR Juggler configuration information.

The main VjControl window consists of a set of panels accessed by a row of tabs (see Figure 5.1).

Figure 5.1. VjControl Tabs

Clicking on a tab exposes its panel; each panel gives access to a particular VjControl function. The functions are as follows:

In addition to these tabbed panels, the VjControl main window also has a fairly typical set of File, Help, and Options menus.

VR Juggler uses two types of files: Config Files and ChunkDesc Files.

For more information, see (DEAD LINKS!):

If a hostname and (optionally) a port are specified, VjControl will try to establish a network connection to a running VR Juggler application on that machine.

Double-click on one of the ConfigChunks in the tree to open the ConfigChunk editing window. This window displays the values for all the Chunk's properties, and lets you modify these values.

Figure 7.4. Config Chunk Editing Window

Some properties in a Chunk allow a variable number of values. These include an Add Value button next to the property name, and a Remove button next to each value (see Figure 7.5).

Figure 7.5. Property Editors

Click the OK button to exit the window, or Cancel to close the window without saving the changes you've made.

VR Juggler includes the idea of an "Include File" chunk, which has one property: the pathname of a VR Juggler config file. When a VR Juggler application loads a file with an "Include File" chunk, it will also load the file named in that chunk. This means that it is possible to make a config file that's just a list of other config files to be loaded.

Similarly, there are "Include Description File" chunks which will cause VR Juggler to automatically load a ChunkDesc file. This is particularly useful for config files which contain application-specific kinds of ConfigChunks. If a config file with includes is loaded into VjControl, the included files are automatically loaded, though each file is viewed separately.

To include a file, simply add an "Include File" (or "Include Descriptions File") chunk to the config file. The name of the "Include File" chunk is the path name of the file to load. You can use the strings "$HOME" and "$VJ_BASE_DIR" at the start of the name to refer to your home directory and the VR Juggler install directory, respectively.

Relative path names in includes (e.g. paths that don't start with "/" or C:) are relative to the location of the file containing the "Include File" chunk. For example, if the config file /home/vr/vjconfig/c2.config includes the file C2/displays.config, VR Juggler will try to load a file named /home/vr/vjconfig/C2/displays.config.

Double-clicking on the name of a ChunkDesc brings up a new window, shown in Figure 8.2.

Figure 8.2. Chunk Description Editor

The uppermost part of the window displays basic information about the ChunkDesc. Every ChunkDesc has two identifiers: a descriptive name which is used for GUI displays, and a shorter token, which is used in the file format and internally by VR Juggler. The name can be any short descriptive phrase; the token should be terse and may not contain spaces. There is also a help string, which can be used to provide a general one-line description of what the ChunkDesc is for.

The center of the ChunkDesc editing window displays a scrollable list of all the properties that ConfigChunks using this description should have. Every ChunkDesc includes a Name property, which is actually used to store the instance name for ConfigChunks of that type. The number and type of other properties can vary.

Users can add a new property by pressing the "Insert" button at the bottom of the window. Properties can be removed by selecting them (clicking on the background of the property's box) and then pressing the "Remove" button.

As with the ChunkDesc itself, each property has a descriptive name and short token, as well as a help string. Some properties can have multiple values (e.g. a position with separate x, y, and z values); this can be defined by entering the desired number of values in the "Number" box, or by selecting the "Var Arguments" value, for a property with a variable number of values.

Every property has a specific type of legal values (integers, strings, etc.); this is selected in the "Type" box. The meanings of the different types are explained in the ConfigChunk Primer.

If a property allows multiple values, it may be helpful to provide individual lables for each one. For example, a "Window Size" parameter may have values labeled "Width" and "Height". To define labels, click on the property's "Value Labels" button. A window such as the one shown in Figure 8.3 will be opened.

Figure 8.3. Property Label Editor

The window contains one line for each value the property allows; in this case we're labeling the individual values "width" and "height". If the property allows a variable number of values, the Value Label window will include Insert and Remove buttons.

Sometimes, a property will have a fixed set of possible values (e.g. "Shift" "Control" "Alt" "None" for keypress modifiers). Selecting the "Edit Enumerations" button for a property description will open a window which allows you to define the set of allowed values. When VjControl is displaying a Property with a set of enumerated values, it can present the choices using a menu instead of requiring the user to type a value. The enumerations feature can also be used to provide text names for numeric or boolean values (e.g. assigning the string "NTSC" to the value 60, and "PAL" to 50).

Sometimes, a property of a ConfigChunk will be a reference to another ConfigChunk. For example, the ConfigChunk for a graphics window might refer to a position input device to use for view frustum calculations.

To create a property of this type, select "Chunk" as the value type for the property. In place of the "Edit Enumerations" button, you'll see a "Set Allowed Types" button. This opens a small window which lets you select what kinds of ConfigChunks this property should be allowed to point to.

Other times, it may be convenient to completely include a ConfigChunk inside of a property, instead of referring to an external Chunk. For example, VR Juggler config files frequently do this to handle complex data types such as keypresses with modifiers in the configuration of its simulated input devices. VjControl has special features to display a small "embedded" chunk as a single line inside a ConfigChunkFrame.

To create a property of this type, select "Embedded Chunk" as the value type. You'll see an "Inner Chunk Type" button in place of the "Edit Enumerations" button. This button opens a small window, similar to the set allowed types window mentioned above (the difference is that this one only allows you to select a single type of ConfigChunk).

The help strings for chunks and properties aren't always sufficient to explain the concept behind a given ConfigChunk, so VjControl includes a mechanism to include more verbose documentation as an external HTML file. These files can be automatically displayed by VjControl when a user presses the help button in the ConfigChunk editor window, or through the help menus, context- sensitive help, etc.

Each "DescHelp" file should be named token.html, where token is the token of the ChunkDesc it describes. VjControl searches for DescHelp files in several places:

The major missing feature in the current OrgTree is the ability to drag around elements of the tree to rearrange them. This ability is forthcoming. For the time being, curious and adventurous readers are referred to Chapter 14.

VjControl communicates with VR Juggler applications over a TCP/IP network connection. This allows VjControl to control VR Juggler applications remotely - from another computer, another room, or another city. This feature is particularly valuable because many VR systems take over their host computer's display, limiting the use of traditional GUI programs.

Figure 11.1. Connection Panel

To connect to a VR Juggler application, switch to the "Connections" panel in VjControl. You will need to enter the hostname and port number that the VR Juggler application is listening to. The hostname and port are in turn specified by one of the configuration files given to the application at startup time (in an Environment Manager ConfigChunk) and are printed to the console as part of the application's initialization.

Once the hostname and port number are in place, press the "Connect" button, and VjControl will open a communications channel to the VR Juggler application.

Alternately, you can specify the hostname and port with VjControl's command-line arguments (see Chapter 6) and it will connect automatically.

Once the connection has been established, switch to the "Configure" panel in VjControl. The list of loaded configuration files which can be selected will contain a new entry called "Active Configuration". Selecting this will display the current configuration of the VR Juggler application - all of the active components displayed as if they were just another configuration file.

Unlike a simple configuration file, changes to this database do not just change VjControl's internal representation. If the user removes a ConfigChunk from the Active Configuration, or copies a Chunk into it, or edits a Chunk and presses the "OK" or "Apply" button, VjControl will send a reconfiguration command across the network connection to the VR Juggler application. The application will process the reconfiguration command and send an updated snapshot of its configuration to VjControl.

Adding a new ConfigChunk to the Active Configuration (as opposed to copying a Chunk into it) does not send a reconfiguration command to the application, since assumably the new Chunk still needs to be edited by the user. The new Chunk won't be sent to the VR Juggler application until the user edits it and presses the "OK" or "Apply" button in the ConfigChunk editor window.

The config files used by VR Juggler and the VjControl program are ASCII text files based around the idea of "ConfigChunks" - logical groupings of configuration for particular parts of a system (e.g. displays, input devices, or simulators). The different kinds of ConfigChunks are defined in ChunkDesc files.

It's important to note that you should load the ChunkDesc files describing the available Chunks before loading a config file - otherwise the config file won't parse correctly.

Here is an example config file with two entries:

display
  Name { "simView" }
  projectiontype { "front" }
  origin { 0 0 }
  size { 600 600 }
  pipe { 0 }
  stereo { False }
  border { True }
  simulator { True }
  simCamera { "CameraProxy" }
  end
flock
  Name { "flock 1" }
  Port { "/dev/tty52" }
  Baud { 38400 }
  num { 1 }
  translate { 0 0 0 }
  rotate { 180.0 0 0 }
  end
End

As you can see, this file defines two chunks. The first is of type Display (i.e. is uses a ChunkDesc whose token is "Display"). The name of this chunk is "simView". All Chunks must have a unique name - if none is given, the parser will give it a geeky default name like "Display_42" and all the other Chunks will make fun of it.

The remaining properties are defined by the ChunkDesc for Display. Each line gives the token for one of the properties followed by a list of values (the type and allowed number of values are also defined in the ChunkDesc).

The general format of a config file is:

ConfigChunk1
ConfigChunk2
...
End

That is, zero or more ConfigChunks followed by the token End.

Several forms of comments are allowed inside the files. C-style comments (/* comment */) can be used to comment out blocks of text. Shell and C++ comments (# and //) can be used to comment out text to the next endline character.

Note that the VjControl program does not preserve comments in the files that it loads and saves, so this is mostly useful as a quick hack or as a debugging feature.

The basic format of a ConfigChunk is:

token
  Name { "name" }
  propertytoken { value1 value2 ... }
  ...
  end

The first line contains only the token of the ChunkDesc that this ConfigChunk uses (note that in general, where tokens of ChunkDescs or PropertyDescs are used, they are not put in quotes, though this would be allowed).

The second line should always be the Name property. This is followed by any other Property lines, and finally by end. Note that it is not strictly necessary to include all of the Properties defined in the Chunk's description. Those that are omitted will be filled in with default values (0, 0.0, false, ""). Omitted properties that allow variable numbers of values will start out with no values at all.

The format for any property line is this:

  token { value1 value2 ... }

Where token is the token for one of the properties defined in the ChunkDesc. Values is a list of 0 or more values separated by whitespace. The surrounding curly braces should be considered mandatory.

The format for a value varies depending upon type. Integers and Floats are simply represented as numbers: 0, 42, 44.556, etc. (Warning: VjControl doesn't parse scientific notation for floats). String values are simply represented as quoted text strings. Boolean values are represented as the strings "True" and "False" (case is irrelevant, and quotes unneccessary).

Some Properties are defined to have a set of named values. If this is the case, the values in the property line can be either names defined in the enumeration or actual values (the example below of an int Property with an enumeration includes one value of each type).

     stringproperty { "a string value" "a second string value" }
     intproperty { 42 }
     floatproperty { 42.0 43.0 }
     booleanproperty { True }
     intproperty_with_enumeration { "a name from the enumeration" 42 }

A ChunkDesc file includes descriptions of different kinds of ConfigChunks. It is a way to configure the configuration system itself. Here's a simple example, a ChunkDesc file with two entries.

chunk flockobirds
 port string 1 port "serial port address"
 offset double 3 offset "tracker coord offset"
 baudrate int 1 baud "serial port rate"
 end
 
chunk display
 name string 1 name "descriptive name"
 origin double 3 origin "other help text"
 size int 2 size ""
 SGIpipe int 1 SGIpipe ""
 xdisplay string 1 xdisplay ""
 stereo bool 1 stereo ""
 lowerleft double 3 lowerleft ""
 lowerright double 3 lowerright ""
 upperleft double 3 upperleft ""
 end

End

The first entry defines a chunk type called "flockobirds" that contains three properties ("port", "offset", and "baudrate"). The second defines a chunktype called "display" which contains 9 properties.

Each property has a type - for example, the values that "port" can take will be strings, such as "/dev/ttyd45", while baudrate will always have integer values.

It is also possible for a property to have a set of values. For example, the "display" chunk's "lowerleft", "lowerright", and "upperleft" properties are meant to represent positions in 3d space. These can be represented by a sequence of three doubles for the x, y, and z coordinates. The number of values a property supports is listed directly to the right of the type - the "3" in the line for "lowerleft", or the "1" for "stereo." If a property might have a variable number of entries (perhaps as a list of active displays, or such), use the number -1.

The fourth word on each property line is the actual token to be used to represent this property when reading/writing config files. Most often this will be the same as the name of the property (which is used internally for querying a ConfigChunk), but the options is provided to make the config files more flexible or readable.

The last thing on a property line is a help string. If the help string contains spaces or is empty, it must be in quotes.

The general format of a ChunkDesc file is:

 [ChunkDesc]
 ...
End

That is, zero or more ChunkDescs followed by the token End.

Several forms of comments are allowed inside the files. C-style comments (/* comment */) can be used to comment out blocks of text. Shell and C++ comments (# and //) can be used to comment out text to the next endline character.

Note that the VjControl program does not preserve comments in the files that it loads and saves, so this is mostly useful as a quick hack or as a debugging feature.

The basic format of a ChunkDesc is:

chunk "token" "longer name" "help info"
    Name String 1 "Name" ""
    [other Property Descriptions]
    ...
    end

The first line contains the token chunk, followed by three strings. The token is used in programs to refer to the ChunkDesc. The name is a longer name that is used in graphical interfaces instead of the token. (The name can contain spaces, the token must not). The help info is a string shown in the graphic interface. All three strings must be defined, though the help string can be empty ("").

The first line is followed by one or more Property Descriptions, followed by the token end. Note that the first property description must always be for the "Name" property - this is used to give a unique name to every ConfigChunk using this ChunkDesc. If there is no "Name" PropertyDesc, one will be added by the loader.

The format of a Property Description line is:

    "token" type num "Name" [optional stuff] "help"

The Token, Name, and Help serve the same purposes as in the Chunk line described above.

Type refers to the type of value stored in this property. Valid values are String, Int, Float, Boolean, and Chunk (a property that stores the names of other ConfigChunks).

Num refers to the number of values that this Property can store. Usually this is 1. A coordinate in 3d space might be stored with 3 float values. A value of -1 in this field means that the property can have a variable number of values (useful for lists of available components, directory search paths, etc.).

There are also two optional fields in a PropertyDesc line, either or both of which can be placed between the Name and Help fields of the line.