VruiConfig Documentation

Using VruiConfig

• Restarts Vrui within the CAVE
• Allows rapid changes in the configuration of Vrui applications
• Separates configuration files into fragments that can be selected
• Saves configurations, including button-tool assignments

• The VruiConfig package consists of the VruiConfigDriver, ConfigVislet, and VruiConfigurations directory.
• It is started up with: VruiConfigDriver <Vrui command & arguments>
• VruiConfigDriver starts the Vrui command with the same Vrui.cfg (or other cfg files) that the command uses when launched without VruiConfigDriver.
• The ConfigVislet presents a dialog (see below) within the environment that allows the user to restart, restart with a different configuration and/or Vrui command, save configurations, and quit.

The VruiConfigurations directory holds configurations, fragments, and command files that can be accessed from within Vrui using the ConfigVislet.

VruiConfigurations is the top level directory. In this directory, there are three required directories:

• Configs
• Frags
• Commands

Two optional directories include:

• Saves
• Hosts

The Configs directory contains full configuration files except that they should contain only one host environment section named '*', rather than many as in the standard Vrui.cfg file. - link to examples

The Frags directory contains configuration fragments to add various vislets, tools, and devices to a full configuration file.

The Commands directory contains executable files that launch Vrui applications, ensuring that they are launched from the appropriate directory. They are typically executable shell scripts that include a “cd” command.

The Saves directory (if it exists) is where configurations files that are saved from VruiConfig live. The contents of this directory are merged into the the “Next configuration” section of the Vrui Configuration dialog.

The Hosts directory (if it exists) contains subdirectories whose names are host names for different machines as reported by the hostname Unix command. Each of the hostname directories contains Configs, Frags, Commands, and (optionally) Saves directories. This allows customization of the VruiConfig tool to specific environments. If a subdirectory in the Hosts directory has the same name as reported by hostname, that subdirectory is used as the VruiConfigurations directory.

See VruiConfigurations documentation for more details.

Fragments are simply configuration files which may contain an option fragment type specification of the form:

VruiConfigurationFragmentType type

where type can be one of Vislet, Tool or Device.

A fragment's type specifies special rules for merging that fragment into another configuration file. If the fragment has no type, then the standard merging rules are used:

• A configuration file is comprised of a single anonymous section.
• Sections may contain tags (name, value pairs) and named subsections
• A source configuration file is merged into a destination configuration file by merging its anonymous section into the anonymous section of the destination.
• A source section is merged into a destination section by copying all its tags to the destination (overwriting tags of the same name), then merging its subsections into the destination. Subsections of the source not in the destination are added to the destination.

Fragment types modify the rules as follows:

• Vislet: Within the section named by /Vrui/*/vislets, the tag visletSearchPaths is merged.

• Tool: Within the section named by /Vrui/*/tools, the tags toolNames, toolClassNames and toolSearchPaths are merged.

• Device: The tags /Vrui/*/inputDeviceAdapterNames and /Vrui/*/DeviceDaemonAdapter/inputDeviceNames are merged.

See details in Appendix 1

The initial configuration file may include many sections for different environments within the Vrui section. VruiConfig identifies the appropriate section, renames the appropriate section '*', removes the other sections, and merges any fragments into the '*' section. Then when it starts Vrui, it expands '*' to the host name of the environment. Thus, it is essential that fragments and configuration files in the Config directory use '*' as the name of subsections within the Vrui section otherwise they won't merge correctly.

Frag and cfg files need a consistent name for the environment section. The fragment types take care of much of the naming consistency. However, there is one persistent issue with the inputDeviceAdapterNames. There can be multiple sections that include different input devices, e.g. system supported hardware (mouse) might be in the MouseAdapter section and devices requiring VRDeviceDaemon (wii mote) might be in the DeviceDaemonAdapter section. This means that VruiConfig doesn't know which sections to merge unless the section names are consistent across configuration files and fragments. Thus, individual users have to make sure that they are using consistent names within their configuration files and fragments for them to merge properly.

Vislet, Tool, and Device fragments need to include the fragment type declaration at the top of the fragment to merge correctly: VruiConifigurationFragmentType <>

The Saves directory can be separate from the Configs directory. This is so that the Configs directory can be linked to a public/common directory, but any configuration files that are saved go into a local directory. This allows sharing of selected, but not all configuration files.

In your fragments, include as little as possible to get the job done. Otherwise you may unnecessarily overwrite some useful setting in the main configuration file. For example, it would be improper for the VncTool fragment to include a “killZoneType Frustum” because the killZoneType has no bearing on the VncTool and including it might override the intended setting.

A very basic example, Sample Configuration Fragment, from the documentation

Fragments can be created to adjust aspects of the environment, including headtracking or not in the cave, stereo or mono rendering in the cave, etc. These are useful for filming or understanding how to switch functionality between tracked devices.

• Fixed Mono Rendering in the CAVE
• Tracked Mono Rendering in the CAVE

Device fragments provide functionality for new hardware. For example, a wii mote can be included in the main configuration file for a mini cave or it can be merged in using VruiConfig. Similarly, a 3D mouse can be added to a desktop environment using a fragment. (Note in both cases, VruiDeviceDaemon also needs to be started.)

• Wii Mote

These fragments merge custom tools into Vrui, making them accessible to the appropriate applications.

• VncTool

It can be very useful to pre-assign tools to buttons on a device if you use them regularly. This is also how the main menu and navigation functions are assigned to buttons on the cave wand, mouse functionality is pre-assigned on a desktop, etc.

• Wand Button Assignment Fragment
• Wii Mote Button Assignment Fragment

• ShowEarthModel:

#! /bin/bash

cd ~/develop/Vrui-1.0/ExamplePrograms
./ShowEarthModel $*

• 3DVisualizer:

#! /bin/bash

cd ~/3DVisualizer/bin/
./3DVisualizer -palette Microb_DK20_a.pal -class ImageStack /share/Data/VolumeData/RockSerialSections/DK20a.shdr  $*

The scripts must be executable files because only one command is allowed. To make a script executable, the permissions have to be changed:

> chmod u+x file_name