CalVR Config File

Overview

The CalVR config file holds all the configuration information for the CalVR kernel and its plugins. The $CALVR_CONFIG_FILE environment variable specifies a colon separated list of files to load. The files can either be an absolute path or a path relative to the default config directory. This directory defaults to $CALVR_HOME/config but can be changed with the $CALVR_CONFIG_DIR if needed.

Include, local and Priority

Each xml file has the option of including other xml files, for example:

<INCLUDE>xpol-cinter-mobile.xml</INCLUDE>

Where this tag is in the file is not important, its contents is added to global scope.

If you want to allow for different information to be visible on different rendernodes, for a screen configuration for example, you need to use local tags:

<LOCAL host="calit2-137-110-111-71.ucsd.edu" >
 <NumPipes value="1" />
</LOCAL>

The host attribute is a comma separated list of hosts that will see this tag structure. The LOCAL tag itself is transparent to the application, and thus should not appear in the tag path.

When looking for a config file value, all open xml files are searched until the first instance of the tag/attribute pair is found. If not found, the default value is returned. The file search order starts with the root config file, then looks in its first included file, then those included from that file, etc., then the root's second included file, then its included files... Basically, tag/attribute combinations in a file will override the value defined in any of its included files. If multiple files are listed in $CALVR_CONFIG_FILE, the first file and its includes are search before next file listed, and so on.

Global Tags

CalVR uses the following tag values from the global scope with the following default values:

<MultiThreaded value="SingleThreaded" />

Sets the thread model for rendering. Uses a osgViewer::ViewerBase::ThreadingModel value: "SingleThreaded", "CullThreadPerCameraDrawThreadPerContext", "CullDrawThreadPerContext", "DrawThreadPerContext"

<RenderOnMaster value="true" />

Sets if the master node in a cluster setup should draw. A graphics window is still opened and all other things occure, but the cull/draw is skipped.

<Freeze value="false" />

When set to "true", the camera position stops getting updated by the tracked head position.

<SyncToVBlank value="false" />

When set to "true", sets driver hint to sync buffer swap to vertical blanking.

<Near value="10.0" />

Sets the near plane value for cameras.

<Far value="10000000" />

Sets the far plane value for cameras.

<Stereo separation="64.0" />

Value to use for distance between left and right eye for stereo rendering.

<Stencil value="false" />

Sets if the graphics window should be created with a stencil buffer.

<ShowAxis value="false" />

When set to "true", an coord axis is displayed for world space, object space, each hand and each head. x = red, y = green, z = blue.

<UseDepthPartition value="false" />

When set to "true", a depth partition node is used at the scene root. This is useful when you have scenes too large to set a static near/far value and there is lots of empty space within the depth range. (i.e. ossimPlanet viewing)

<HidePointer value="false" />

When set to "true" the wand pointers for the hands are not visible.

<CullingMode value="CALVR" />

This value sets what CullVisitor to use for the scene. The options are "CALVR" for our custom visitor and "DEFAULT" for the osg default visitor. The CalVR visitor has some modifications for cluster graphics and uses some special node masks. See CalVR Node Masks

<ConfigDebug value="false" />

When set to "true", all config value requests are printed with whatever value was found.

<ViewerPosition x="0" y="0" z="0" />

Defines the default location of the viewer camera.

Tracking

This is a simple example of tracking configuration:

<Input>
 <Threaded FPS="60.0" />
 <TrackingSystem0 value="MOUSE">
  <Offset x="0" y="0" z="0" />
  <Orientation h="0" p="0" r="0" />
  <NumBodies value="1" />
  <NumButtons value="3" />
  <NumValuators value="0" />
  <Body0>
   <Offset x="0" y="0" z="0" />
   <Orientation h="0" p="0" r="0" />
  </Body0>
 </TrackingSystem0>
 <NumHeads value="0" />
 <NumHands value="1" />
 <Hand0>
  <Address system="0" body="0" />
  <ButtonMask system0="0xFF" />
 </Hand0>
</Input>

Tracking is configured by defining the tracking systems being used and how the input from these systems is mapped to head(s) and hand(s). The above example is a simple setup that could be used by a desktop. It defines the basic mouse tracking system with with one tracked body and three buttons. There are 0 tracked heads define, so the ViewerPosition value will be used for the head position/orientation. There is 1 hand that uses the mouse body and buttons.

I will now go into more detail on configuring these tags.

TrackingSystem#

An arbitrary number of tracking systems may be define with TrackingSystem# tags. The only restriction is that the system number must start with 0 and must increment without skipping.
Within the TrackingSystem# tag there are various options.

<Offset x="0" y="0" z="0" />
<Orientation h="0" p="0" r="0" />

These values define a global transform of the tracking data. The orientation rotates the coordinates of the system and the offset provides a global transformation.(transforms applied roll->pitch->heading)

<NumBodies value="1" />
<NumButtons value="3" />
<NumValuators value="0" />

These values define the number of tracked bodies, buttons, and valuators(analog) values in this tracking system.

<Body#>
 <Offset x="0" y="0" z="0" />
 <Orientation h="0" p="0" r="0" />
</Body#>

These tags allows you to provide a translation/rotation correction on each tracked body in the system(replace # with body id)

The value for the tracking system defines the system type.

MOUSE

A mouse tracking system uses the mouse input from the head node. It has at most one tracked body and three buttons. The tracked body is created so that the body origin is at the same point as the camera position. The orientation is calculated based on this point and the intersection of the mouse with the screen. There are no special options for this system.

VRPN

A vrpn tracking system must define a vrpn server to connect to. This is done like so:

<TrackingSystem#>
 ...
 <VRPN>
  <Server value="Device0@127.0.0.1:7701" />
 </VRPN>
 ...
</TrackingSystem#>

SHMEM

This type of tracking system reads data out of a shared memory block that is an output of trackd. You can define which shared memory id to read for the tracker and controller:

<TrackingSystem#>
 ...
 <SHMEM>
  <TrackerID value="4126" />
  <ControllerID value="4127" />
 </SHMEM>
 ...
</TrackingSystem#>

Heads

To define the heads being tracked, you must first state the number of heads.

<NumHeads value="1" />

There must be an entry to define each head.

<Head#Address system="0" body="0" />

The system is the tracking system id and the body is the body id within the tracking system.

Note: When the number of heads is set to 0 the default viewer position/orientation is used and not updated.

Hands

To define the hands being tracked, you must first state the number of hands.

<NumHands value="1" />

You then must define each hand.

<Hand#>
 <Address system="0" body="1" />
 <ButtonMask system0="0xFF" system1="0x00" />
 <NumValuators value="1" />
 <Valuator0 system="1" number="0" type="NON_ZERO" />
</Hand#>

The Address defines the tracking system and body id to use for the hand position/orientation.
The button mask is used to assign buttons to this hand. The mask is in hex. This example tells the hand to use the first 16 buttons from the first system and no buttons from the second. If there are less buttons defined in the system, it will only use that many buttons. Each hand button is given a unique id numbered from the lowest system to the highest. These ids are used in button events.

Each hand may also be assigned a number of valuator(analog) inputs. You first state the number of valuators for the hand then the valuator system and index number. The type value is used when generating valuator events. A value of "NON_ZERO" will create a valuator event when its value is not zero. A value of "CHANGE" will create a valuator event only when the value changes.

This is a more complex input definition:

<Input>
 <Threaded FPS="60.0" />
 <TrackingSystem0 value="MOUSE">
  <Offset x="0" y="0" z="0" />
  <Orientation h="0" p="0" r="0" />
  <NumBodies value="1" />
  <NumButtons value="3" />
  <NumValuators value="0" />
  <Body0>
   <Offset x="0" y="0" z="0" />
   <Orientation h="0" p="0" r="0" />
  </Body0>
 </TrackingSystem0>
 <TrackingSystem1 value="VRPN">
  <NumBodies value="1" />
  <NumButtons value="3" />
  <NumValuators value="1" />
  <VRPN>
   <Server value="Device0@127.0.0.1:7701" />
  </VRPN>
 </TrackingSystem1>
 <NumHeads value="1" />
 <Head0Address system="1" body="0" />
 <NumHands value="2" />
 <Hand0>
  <Address system="0" body="0" />
  <ButtonMask system0="0xFF" system1="0x00" />
 </Hand0>
 <Hand1>
  <Address system="0" body="1" />
  <ButtonMask system0="0x00" system1="0xFF" />
  <NumValuators value="1" />
  <Valuator0 system="1" number="0" type="NON_ZERO" />
 </Hand1>
</Input>

It defines two tracking systems, one the default mouse and one from a vrpn server. It defines one tracked head device and two hands.

Plugins

The config file contains an area reserved for information relating to the loading and running of plugins.
Each tag under the Plugin tag is looked at as naming a plugin. The value of this tag defines if the plugin should be loaded or not. An example would be:

<Plugin>
 <ModelLoader value="on" >
  <ConfigDir value="/home/aprudhom/data/ModelLoader/" />
  <Files>
   <se_building path="/home/aprudhom/data/falko/se_building.obj" mask="1" />
  </Files>
 </ModelLoader>
</Plugin>

The above tells CalVR to try to open a plugin library called "ModelLoader". The rest of the information is used by the plugin itself. Note: the first on/off value for a plugin when reading through the config file will determine if it is loader or not.

Graphics Window Config

In order to specify a screen configuration in CalVR, you must define pipes, windows, channels, and screens.

Pipes

A pipe is an interface to the windowing system. In the case of linux, this defines and x server/screen pair.
A sample pipe config looks like this:

<NumPipes value="2" />
<PipeConfig>
 <Pipe server="0" screen="0" name="0" />
 <Pipe server="0" screen="1" name="1" />
</PipeConfig>
The name attribute defines the pipe number.  This must start with 0 and not skip.

Windows

A window describes a graphics context window using a given pipe.
A sample window config looks like this:

<NumWindows value="2" />
<WindowConfig>
 <Window width="1024" pipeIndex="0" height="768" left="0" bottom="0" name="0" />
 <Window width="1024" pipeIndex="1" height="768" left="0" bottom="0" name="1" />
</WindowConfig>

The width and height define the window size in pixels. The left and bottom define an offset for the window within the pipe. The pipeIndex selects the pipe for the window. The name defines the window number. This must start with 0 and not skip.

The following are attributes that can be added to the window tag with their default values:

decoration="false"

If true, the window has a title bar and border.

useCursor="(see below)"

This defines if the mouse cursor is visible when in the window. This defaults to true on the master node and false on the render nodes.

quadBuffer="false"

If true, the window is created for quad buffered stereo.

overrideRedirect="false"

Some distros of linux will do some funny things to created windows, like resize them so the task bars are visible. If the windows are not being created as specified, this can be used to force your configuration. Note: if you alt tab out of a window with this option, there is no way to get back into it, you must kill the process in a terminal. I do not recommend using this on the head node if possible.

Example

Until I can make some clean examples, a good place to look is in the files in the ${CALVR_HOME}/config directory.