Vrui Configuration File Settings Reference

Root Section

Setting TagSetting Value TypeSetting Description
enableMultipipeboolean Master toggle for cluster-based multipipe rendering. If true, Vrui will read the following multipipe... settings and configure itself to run in a distributed environment where applications are replicated across cluster nodes and synchronized by sharing input device data and application-specific data streams. This is not the appropriate rendering mode for single-system-image multipipe architectures (such as SGI Onyx/Prism).
multipipeMasterstring Internet host name or dotted-form IP address of the master node in a distributed rendering environment. The master node is the one where users log in and start Vrui applications. Some Vrui settings rely on node indices; the index of the master node is always zero.
multipipeMasterPortinteger Number of the UDP port used for cluster communication on the master node. This port needs to be accessible from the slave nodes, i.e., it must be accepted by any installed firewalls.
multipipeSlaveslist of strings List of the internet host names or dotted-form IP addresses of the slave nodes in a distributed rendering environment. A Vrui application started on the master node will replicate itself onto these slave nodes using the multipipeRemoteCommand. Some Vrui settings rely on node indices; slave nodes are numbered in the order in which they appear in the list, starting at one.
multipipeMulticastGroupstring Internet name or dotted-form IP address of the multicast or broadcast address used for communication from the master node to the slave nodes. Vrui uses a multicast protocol if the given address is a valid IETF multicast address, and uses a broadcast protocol otherwise. All nodes in the cluster must be able to receive UDP packets sent to the multicast/broadcast address.
multipipeMulticastPortinteger Number of the UDP port used for cluster communication on the slave nodes. This port needs to be accessible from the master node, i.e., it must be accepted by any installed firewalls.
multipipeRemoteCommandstring Command used to log in to slave nodes during Vrui application startup. If not specified, this defaults to ssh.
multipipeConnectionWaitTimeoutnumber
multipipePingTimeoutnumber Timeout value for cluster crash detection. If a slave node does not receive data from the master for the specified time (in seconds), it sends a ping request to the master. If too many ping requests time out (see next setting), the slave node exits from Vrui.
multipipePingRetriesinteger Maximum number of ping requests sent by a slave node before it exits from Vrui (see previous setting).
multipipeReceiveWaitTimeoutnumber
multipipeBarrierWaitTimeoutnumber
inchScalenumber Defines the physical coordinate unit used to describe the Vrui environment by specifying the length of an inch in physical units. For example, if the used physical units are meters, inchScale is set to 0.0254.
meterScalenumber Defines the physical coordinate unit used to describe the Vrui environment by specifying the length of a meter in physical units. Alternative to inchScale setting, see above. For example, if the used physical units are centimeters, meterScale is set to 100.0.
displayCenterpoint Defines the center point of the Vrui display environment in physical coordinates. The center point is mostly used by applications to initialize their model coordinates. In general, the display center should be a point that is in the middle of the display space accessible by users, such as the screen center for a single-screen environment or the center point of a CAVE.
displaySizenumber Defines an approximate size for the Vrui display environment in physical coordinate units. The display size is mostly used by applications to initialize their model coordinates.
forwardDirectionvector Defines a direction vector in physical coordinates that corresponds to the typical direction a user would face when looking at a Vrui display environment. For single-screen environments it is typically a vector pointing into the screen; in CAVEs, it is typically a vector pointing into the back wall.
upDirectionvector Defines a direction vector in physical coordinates that corresponds to "up," i.e., the opposite direction of local gravity. It is mostly used by Vrui application to initialize their model coordinates such that models appear right side up.
floorPlaneplane Defines a plane in physical coordinates that corresponds to a Vrui display environment's floor. For walk-in environments such as CAVEs or upright display walls it is typically the true floor plane; for desktop-like environments it is typically a plane orthogonal to the "up" direction that is placed a few feet below the screen center.
glyphSizenumber Specifies the display size of glyphs such as input device pointers in physical coordinates.
newInputDevicePositionpoint Specifies a point in physical coordinates that is used as the initial position for newly created virtual input devices. It is typically identical to the display center, but for single-screen environments, it is typically offset a few inches to be placed in front of the screen to simplify interaction with new virtual input devices.
inputDeviceAdapterNameslist of strings List of names of the input device adapter sections that specify all sources of user input recognized by Vrui applications.
inputDeviceDataSaverstring Name of input device data saver section. If this is a valid section name, Vrui will save the state of all physical input devices to a file on every frame. These files can later be played back by creating a playback input device adapter. Saving input device data can be useful during debugging, to capture a session and play it back later from inside a debugger, or to generate 3D movies of someone using a Vrui application.
updateContinuouslyboolean Flag whether to run Vrui's inner loop continuously. If this is set to false, Vrui will only update its (and the application's state) whenever new data arrives from any input devices. This is the most appropriate mode for non-immersive display environments. If set to true, Vrui will update its internal state as fast as possible, regardless of whether new input device data arrived or not. Applications that use animation will typically override this setting to run smooth animations even if no input device events arrive.
maximumFrameRatenumber The maximum allowed frame rate for Vrui's main loop. If this parameter is set to a value larger than zero, the Vrui main loop will pad each frame to at least the duration of 1.0/maximFrameRate seconds by blocking before advancing to the next frame. Normally Vrui applications should run as fast as they can to minimize latency; however, some special uses like generating 3D movies by saving input device data (see above) might benefit from a throttled frame rate.
viewerNameslist of strings List of names of viewer sections. Viewers define how 3D models are projected onto a Vrui display environment's screens. The first viewer in the list is considered the main viewer and is treated specially, for example, is used to determine the orientation of pop-up menus.
screenNameslist of strings List of names of screen sections. Together with viewers, screens define how 3D models are projected in a Vrui display environment.
screenProtectorslist of screen protectors
node<index>WindowNames
windowNames
list of strings List of names of window sections. Windows are the "glue" that bind viewers to screens and implement the OpenGL-based 3D rendering used by Vrui. In cluster-based distributed display environments, there must be a node<index>WindowNames tag for each cluster node (the master node is always zero; slave nodes are numbered according to their order in the multipipeSlaves list, starting at one). Any nodes with empty window lists will not open any windows, but otherwise fully participate in the Vrui application. This is useful for cluster head nodes with low-powered graphics cards, or for dedicated audio rendering nodes.
node<index>WindowsMultithreaded
windowsMultithreaded
boolean Toggles between serial and parallel rendering for multiple windows on the same computer. If any Vrui node has multiple windows and this setting is true, Vrui will use multiple threads, one per window, to render to the windows in parallel. The default mode, if this setting is false, is to render to the windows serially from a single thread. The appropriate mode for single-system-image multipipe systems such as SGI Onyx or Prism is to configure them as a non-distributed environment (enableMultipipe is false), assign one window to each graphics pipe, and render to these windows in parallel. However, if a node has multiple windows but only a single actual graphics card, it is usually better to render in serial since graphics cards are typically not optimized for rapid context switches.
listenerNameslist of strings List of names of listener sections. Listeners define how spatial 3D sound is rendered in a Vrui environment. The first listener in the list is considered the main listener.
node<index>SoundContextName
soundContextName
string Name of a sound context section. Sound contexts correspond to audio devices and define how spatial 3D sound is rendered in a Vrui environment. In cluster-based distributed display environments, there must be a node<index>SoundContextName tag for each cluster node that is supposed to render spatial 3D sound using the OpenAL library (the master node is always zero; slave nodes are numbered according to their order in the multipipeSlaves list, starting at one).
frontplaneDistnumber Defines the distance in physical units of the OpenGL front clipping plane from the eye points of Vrui viewers. This defines how closely a viewer can approach 3D objects before the objects are clipped away.
backplaneDistnumber Defines the distance in physical units of the OpenGL back clipping plane from the eye points of Vrui viewers. This defines how far a 3D object can move into the distance before it is clipped away.
backgroundColorcolor Defines the background color used for all windows in a Vrui display environment, unless overridden by Vrui applications.
ambientLightColorcolor Defines the ambient color component used in the OpenGL lighting equation. This is the light color used when no other lights are present. It should be kept at fairly low values not to wash out display contrast.
widgetMaterialmaterial Defines the material properties of 3D GUI widgets such as pop-up menus, dialog windows, etc.
drawOverlayWidgetsboolean Switches whether 3D user interface widgets are drawn in an overlay layer above all other 3D graphics. If disabled (the default), 3D widgets are integrated with other 3D graphics and drawn at the proper depth. If enabled, widgets are still drawn at proper depth, but appear to float above other graphics. This makes the user interface more desktop-like and works well in non-stereo mode, but can cause severe eye strain in stereo modes on the desktop and especially in immersive environments.
popWidgetsOnScreenboolean If set to true, widgets popped up by Vrui applications will always be aligned with the main screen's plane, unless the application specifies a full widget transformation. This helps with keeping the illusion of a 2D user interface in desktop environemnts. This flag should not be enabled for immersive environments.
uiSizenumber Defines a size in physical units used for general layout of 3D GUI widgets, such as border widths, text field margins, etc.
uiBgColorcolor
uiFgColorcolor
uiTextFieldBgColorcolor
uiTextFieldFgColorcolor
uiTitleBarBgColorcolor
uiTitleBarFgColorcolor
uiFontNamestring Name of the font used for 3D GUI widgets such as labels, buttons, or text fields. Vrui uses its own texture-based fonts which are installed in the share/GLFonts directory.
uiFontTextHeightnumber Defines the height of text for 3D GUI widgets in physical units.
uiFontAntialiasingboolean Toggles font smoothing for 3D GUI widgets. Should be enabled if text looks "pixellated."
uiSliderWidthnumber
uiSliderHandleColorcolor
uiSliderShaftColorcolor
toolsstring Name of tool manager section. The tool manager is responsible for translating low-level input device events such as button presses into higher-level application functions such as navigation.
visletsstring Name of vislet manager section. Vislets are additional rendering modules that can be loaded into arbitrary Vrui applications as plug-ins.

Input Device Adapter Sections

Setting TagSetting Value TypeSetting Description
inputDeviceAdapterTypeenumerant
Mouse
Adapter for the window system's mouse and keyboard devices. Rest of the section contains mouse input device adapter settings.
DeviceDaemon
Adapter to receive input from Vrui's own stand-alone device driver daemon. Rest of the section contains DeviceDaemon input device adapter settings.
VisBox
Adapter to receive input from the proprietary head tracker used in VisBox systems. Rest of the section contains VisBox input device adapter settings.
HID
Adapter to receive input from human interface devices (HIDs) provided by the operating system's input layer. Rest of the section contains HID input device adapter settings.
Playback
Adaper to read back input device data saved in a previous session, using the saveInputDeviceData and inputDeviceDataFileName root section settings (for debugging or to record screenshot movies of VR interactions after the fact). Rest of the section contains playback input device adapter settings.

Mouse Input Device Adapter Settings

Setting TagSetting Value TypeSetting Description
buttonKeyslist of key names Lists a subset of keyboard keys that are treated just like mouse buttons by the mouse input device adapter. The total number of buttons in each button plane (see modifierKeys setting) is the number of button keys plus the number of actual mouse buttons (see the numButtons setting).
modifierKeyslist of key names Lists the set of modifier keys recognized by the Vrui mouse input device adapter. Modifier keys (and combinations thereof) allow access to several button planes to increase the total number of available buttons. For example, if LeftCtrl and LeftAlt are listed as modifier keys, Vrui will create four button planes (no modifier, LeftCtrl only, LeftAlt only, LeftCtrl+LeftAlt). Buttons are numbered sequentially inside each plane by mouse buttons first and then button keys, and then in order of planes. Planes are ordered according to modifier button combinations in LSB-first binary code. The plane with no modifiers pressed is always zero, and in the preceding example, the (LeftCtrl only) plane is 1, and the (LeftCtrl+LeftAlt) plane is 3.
Note: Any buttons (mouse buttons and/or button keys) that are pressed while the button plane is changed stay pressed until their button plane is selected again. This can be very useful especially in desktop-like environments.
numButtonsinteger Defines the number of buttons on the actual mouse device as reported by the windowing system. Is typically 3 in X11-based systems. The total number of buttons in each button plane (see modifierKeys setting) is the number of button keys (see the buttonKeys setting) plus the number of actual mouse buttons.
fakeMouseCursorboolean Enables a texture-based mouse cursor to be rendered at the position of the mouse input device controlled by the input device adapter. This is useful in situations where the hardware mouse cursor is not available, or is inappropriate, such as in mouse-controlled cluster environments. This setting defaults to false.
mouseCursorImageFileNamestring The name of the cursor image file from which to load the fake mouse cursor, if enabled.
mouseCursorNominalSizeinteger The nominal size of the mouse cursor which is to be loaded from the cursor image file. Nominal sizes are defined in the cursor file itself, and Vrui selects the most closely matching size from the file.
mouseCursorSizesize Size of the rendered mouse cursor glyph in physical coordinates. The third component of the given value is ignored.
mouseCursorHotspotvector Offset from the bottom-left corner of the mouse cursor image to the cursor "hotspot," i.e., the position that corresponds to the mouse position. Normalized to lie within [0, 1] in both directions; the third component of the given value is ignored.

DeviceDaemon Input Device Adapter Settings

Setting TagSetting Value TypeSetting Description
serverNamestring Internet host name or dotted-form IP address of the server computer running the VR device daemon (often the local host). The server computer must be reachable from the Vrui master node via TCP.
serverPortinteger Number of the TCP port used to communicate with the VR device daemon. This port must be accessible from the Vrui master node, i.e., it must be enabled in any firewalls.
inputDeviceNameslist of strings List of names of DeviceDaemon input device sections. Each section defines a single input device, i.e., a collection of an (optional) tracker and a set of buttons and valuators (analog axes).

DeviceDaemon Input Device Sections

namestring The name of the input device used by Vrui itself and visible to Vrui applications.
trackTypeenumerant
None
The input device does not have a tracker; it only contains buttons and/or valuators.
3D
The input device has a tracker that reports 3D position only, but no orientation.
Ray
The input device has a tracker that reports 3D position and a single direction vector, but no full orientation.
6D
The input device has a tracker that reports both 3D position and full 3D orientation.
numButtonsinteger Number of buttons on the input device.
numValuatorsinteger Number of valuators (analog axes) on the input device.
deviceRayDirectionvector The direction of a ray in local device coordinates that is used for ray-based interactions such as menu selection.
deviceGlyphTypeglyph type Type of glyph used to draw a 3D representation of the input device in the Vrui display environment.
deviceGlyphMaterialmaterial Material properties to render the device glyph.
trackerIndexinteger Index of the device's tracker in the flat tracker name space of the VR device daemon.
buttonIndexBaseinteger Base index of the device's buttons in the flat button name space of the VR device daemon. Provides a default index for each device button by adding the button index on the device to the base index.
buttonIndex<index>integer Index of one of the device's buttons in the flat button name space of the VR device daemon. Can be used to override default indices for individual buttons.
valuatorIndexBaseinteger Base index of the device's valuators in the flat valuator name space of the VR device daemon. Provides a default index for each device valuator by adding the valuator index on the device to the base index.
valuatorIndex<index>integer Index of one of the device's valuators in the flat valuator name space of the VR device daemon. Can be used to override default indices for individual valuators.

VisBox Input Device Adapter Settings

Setting TagSetting Value TypeSetting Description
sharedMemoryKeyinteger Shared memory key of the shared memory segment the VisBox tracker driver (VisTracker) dumps its data into. Default value is the default VisTracker memory key, 57005 (0xDEAD in hex).
namestring The name of the input device used by Vrui itself and visible to Vrui applications.
deviceRayDirectionvector The direction of a ray in local device coordinates that is used for ray-based interactions such as menu selection.
deviceGlyphTypeglyph type Type of glyph used to draw a 3D representation of the input device in the Vrui display environment.
deviceGlyphMaterialmaterial Material properties to render the device glyph.

HID Input Device Adapter Settings

Setting TagSetting Value TypeSetting Description
inputDeviceNameslist of strings List of names of HID input device sections. Each section defines a single input device, i.e., a collection of a set of buttons and valuators (analog axes).

HID Input Device Sections

namestring The name of the input device used by Vrui itself and visible to Vrui applications.
deviceVendorProductIdstring A colon-separated pair of hexadecimal numbers defining the vendor and product ID, respectively, of the input device to be used, as defined by the USB specification.
deviceIndexinteger Index of the device to be used among devices with the same vendor/product ID. If this value is 0 (the default), the first matching device is used.
axis<index>Settingaxis value mapper Defines the value mapping for one of the device's absolute or relative analog axes, numbered starting from 0 in the order they are enumerated by the device. Allows to fine-tune the behavior of each device axis individually.

Playback Input Device Adapter Settings

Setting TagSetting Value TypeSetting Description
inputDeviceDataFileNamestring Name of the input file from which to read input device data. The file must have been created by saving input device data from a previous run of the same Vrui application, in the exact same environment; otherwise, results are undefined.
fakeMouseCursorDeviceinteger If set to a valid input device index from the loaded input device file, enables a texture-based mouse cursor to be rendered at the position of the selected input device. This is useful when playing back sessions recorded in mouse-controlled environments, since otherwise the mouse cursor would not show up.
mouseCursorImageFileNamestring The name of the cursor image file from which to load the fake mouse cursor, if enabled.
mouseCursorNominalSizeinteger The nominal size of the mouse cursor which is to be loaded from the cursor image file. Nominal sizes are defined in the cursor file itself, and Vrui selects the most closely matching size from the file.
mouseCursorSizesize Size of the rendered mouse cursor glyph in physical coordinates. The third component of the given value is ignored.
mouseCursorHotspotvector Offset from the bottom-left corner of the mouse cursor image to the cursor "hotspot," i.e., the position that corresponds to the mouse position. Normalized to lie within [0, 1] in both directions; the third component of the given value is ignored.
synchronizePlaybackbool When this flag is set to true, the playback input device adapter will synchronize the timing of Vrui application frames with the time stamps stored in its input file. As a result, the playback should run exactly at the same speed as the original recording.
quitWhenDonebool When this flag is set to true, the playback input device adapter will shut down the Vrui application after reading its entire input file.
soundFileNamestring Name of a sound file to be played in synchronization with the input device data. The sound file must have been recorded by the input device data saver in the same session as the input device data file.
saveMoviebool When this flag is set to true, the playback input device adapter will create a movie by saving a sequence of screen shots from a specified window on the master node, exactly at specified intervals.
movieFileNameTemplatestring Printf-style format string to generate image file names for the screenshots written while generating a movie. The template must contain exactly one integer conversion specifier, of the form %[0-9]*d.
movieWindowIndexinteger The index of the master node window from which to save screenshots for a movie. This integer must be a valid index in the master node's list of windows; saving movie screenshots from a window on a slave node is not yet supported.
movieFrameRatenumber Target frame rate for the exported movie. The playback input device adapter will export slices at exactly the specified times to guarantee real-time playback even if Vrui's main loop frame rate varies. Movie frames will point sample the sequence of Vrui frames: short Vrui frames might be skipped and not generate movie frames, and long Vrui frames might generate multiple identical movie frames.

Input Device Data Saver Section

Setting TagSetting Value TypeSetting Description
inputDeviceDataFileNamestring Name of the file to which the data of all physical input devices is to be saved. The name of the file will be modified by inserting a unique four-digit sequence number before the file name extension.
soundFileNamestring Name of a sound file to be recorded in synchronization with the saved input device data. The sound file can later be played back synchronized to the input device data by the playback input device adapter.
sampleResolutioninteger Sampling resolution for sound recording in bits.
numChannelsinteger Number of channels for sound recording. 1 = mono, 2 = stereo, etc.
sampleRateinteger Sample rate for sound recording in Hertz.

Viewer Sections

Setting TagSetting Value TypeSetting Description
namestring Name of the viewer used by Vrui itself, and visible to Vrui applications.
headTrackedboolean Flag whether the viewer is attached to an input device or at a fixed position in physical space.
headDevicestring If the headTracked flag is true, the name of the input device the viewer is attached to.
headDeviceTransformationtracker state The transformation from local viewer space into physical space (if headTracked is false) or local input device space (if headTracked is true).
viewDirectionvector Defines a general viewing direction in local viewer coordinates.
monoEyePositionpoint Defines a point in local viewer coordinates used for monoscopic rendering.
leftEyePositionpoint Defines the position of the viewer's left eye in local viewer coordinates.
rightEyePositionpoint Defines the position of the viewer's right eye in local viewer coordinates.
headLightEnabledboolean If true, attaches a head light source to the viewer.
headLightPositionpoint Position of the head light source in lcoal viewer coordinates.
headLightDirectionvector Direction of the head light source in local viewer coordinates.
headLightColorcolor Light color of the head light source.
headLightSpotCutoffnumber Cutoff angle (in degrees) for the head light source. The light source will only affect 3D objects inside a cone around the head light direction with the given opening angle. The opening angle must be either between 0 and 90, or equal to 180 to create a point light source.
headLightSpotExponentnumber Coefficient defining the drop-off of light intensity of the head light source around the head light direction. Defines a non-directional point light source if set to zero and increasingly more focused spot lights if set to larger values.

Screen Sections

Setting TagSetting Value TypeSetting Description
namestring Name of the screen used by Vrui itself, and visible to Vrui applications.
deviceMountedboolean Toggles whether the screen is attached to an input device (such as head-mounted displays) or at a fixed position/orientation in physical coordinates.
deviceNamestring If deviceMounted is true, gives the name of the input device the screen is attached to.
originpoint Defines the origin (lower-left corner in pixel coordinates) of the screen in physical coordinates (if deviceMounted is false) or in local device coordinates (if deviceMounted is true).
horizontalAxisvector Direction of the screen's horizontal axis (left to right in pixel coordinates) in physical coordinates (if deviceMounted is false) or in local device coordinates (if deviceMounted is true).
widthnumber Width of the screen in physical units.
verticalAxisvector Direction of the screen's vertical axis (bottom to top in pixel coordinates) in physical coordinates (if deviceMounted is false) or in local device coordinates (if deviceMounted is true).
heightnumber Height of the screen in physical units.
rotateCenterpoint Defines the center point of an additional rotation that can be used to easily rotate a screen around any desired axis (such as in adjustable workbenches or flexible CAVEs).
rotateAxisvector Axis of an additional rotation around the center point defined by the rotateCenter tag.
rotateAnglenumber Angle of additional screen rotation in degrees.
offAxisboolean Flag whether the screen is projected off-axis, i.e., requires a correction homography.
homography3x3 matrix A 3x3 matrix defining a homography in screen space, which transforms the screen's theoretical rectangle into the screen's projected quadrilateral.

Window Sections

Setting TagSetting Value TypeSetting Description
viewerNamestring Name of the viewer associated with this window.
screenNamestring Name of the screen associated with this window.
leftScreenNamestring Name if the left screen if the window's left and right eye views are displayed on different screens (such as in some head-mounted displays).
rightScreenNamestring Name if the right screen if the window's left and right eye views are displayed on different screens (such as in some head-mounted displays).
protectScreensboolean Flag whether to protect the screens associated with this window from monitored input devices (to prevent users from walking into screens).
displaystring Name of the X11 display to use for this window; defaults to the local display defined by the DISPLAY environment variable.
windowPoswindow position Initial position of the window on the display in pixel coordinates.
windowFullscreenboolean Flag whether to initially maximize the window (removing all window decoration and screen borders).
windowTypeenumerant
Mono
Monoscopic window; uses the associated viewer's monoscopic eye position.
LeftEye
Left-eye view only; uses the associated viewer's left eye position.
RightEye
Right-eye view only; uses the associated viewer's right eye position.
AnaglyphicStereo
Stereoscopic rendering using anaglyphic (red/blue color separation) stereo.
SplitViewportStereo
Stereoscopic rendering using two separate viewports in the same window, such as side-by-side stereo. The two used viewports can be exactly specified using the leftViewportPos and rightViewportPos settings.
InterleavedViewportStereo
Stereoscopic rendering using two interleaved viewports in the same window, for example by using even pixel columns for the left eye, and odd pixel columns for the right eye. This is the stereo mode often supported by commodity stereoscopic displays like 3D DLP televisions, or polarizing flat panel monitors. The interleaving pattern can not yet be specified; it currently defaults to the pattern used by 3D DLP televisions.
QuadbufferStereo
Stereoscopic rendering using a quad-buffered visual (also known as "active" stereo). Is only supported by some graphics cards.
leftViewportPoswindow position Position of the viewport used for left-eye views in SplitViewportStereo stereo mode in window coordinates.
rightViewportPoswindow position Position of the viewport used for right-eye views in SplitViewportStereo stereo mode in window coordinates.
autoScreenSizeboolean If set to true, instructs the window to query the physical size of its associated X11 screen, and override the configured size of its associated VR screen with the found values. If the X11 server is configured correctly, this will result in accurate physical units in the display window for any connected monitor.
panningViewportboolean Flag determining the relationship between the display screen containing a window and the Vrui screen describing the window's position in physical space. If this flag is set to false (the default), the associated Vrui screen is always fully mapped to the window's current position and size. If the flag is true, the Vrui screen is considered to map to the display screen containing the window instead. In effect, this means that the window serves as a sliding viewport into the 3D environment as seen through the screen. Moving or resizing a window with a panning viewport will not affect the position or size of the shown model.
navigateboolean Flag defining the effect of moving or resizing a panning-viewport window on the displayed 3D scene. If this flag is true, moving the window will move the 3D scene, and resizing the window will scale the 3D scene using a "fake" navigation tool. In effect, navigation will make a Vrui window behave almost exactly like a 3D window in desktop-centric applications, but the 3D scene will still be projected from the correct viewpoint to provide, for example, correct stereoscopic rendering.
toolKillZonePoswindow point Setting to override the position of the tool kill zone when moving/resizing panning-viewport windows. By default, the position of the tool kill zone is given in physical coordinates and does not move with the window. If this tag is set, the tool kill zone will always stay at the given relative window coordinates. Relative window coordinates map (0, 0) to the lower-left window corner and (1, 1) to the top-right window corner.
showFpsboolean Flag to display the current (filtered) Vrui frame rate in the window.
showFpsFontNamestring Name of the font used to display the current frame rate in the window. Vrui uses its own texture-based fonts which are installed in the share/GLFonts directory.
multisamplingLevelinteger Level of OpenGL multisampling to use for the window. Support for this feature, and the available level numbers, are dependent on the model of installed graphics card.
joinSwapGroupboolean
swapGroupNameinteger
swapBarrierNameinteger

Listener Sections

Setting TagSetting Value TypeSetting Description
namestring Name of the listener used by Vrui itself, and visible to Vrui applications.
headTrackedboolean Flag whether the listener is attached to an input device or at a fixed position in physical space.
headDevicestring If the headTracked flag is true, the name of the input device to which the listener is attached.
headDeviceTransformationtracker state The transformation from local listener space into physical space (if headTracked is false) or local input device space (if headTracked is true).
headPositionvector Defines the listener's head position in the listener's local space.
listenDirectionvector Defines a forward-pointing vector in the listener's local space.
upDirectionvector Defines an up-pointing vector in the listener's local space.
gainnumber Overall gain factor for this listener in all sound contexts.

Sound Context Section

Setting TagSetting Value TypeSetting Description
listenerNamestring Name of the listener associated with this sound context.
deviceNamestring Name of the OpenAL sound device used by this sound context.
speefOfSoundnumber Speed of sound in physical coordinate units/s. Used to compute Dopper shift.
dopplerFactornumber Exaggeration factor for Dopper shift.
distanceAttenuationModelenumerant Distance model for source gain attenuation.
Constant
Source gain is unaffected by distance (default setting).
Inverse
Source gain is inversely proportional to distance from listener.
InverseClamped
Ditto, with minimum and maximum gain clamping.
Linear
Source gain drops linearly with distance from listener.
LinearClamped
Ditto, with minimum and maximum gain clamping.
Exponential
Source gain drops exponentially with distance from listener.
ExponentialClamped
Ditto, with minimum and maximum gain clamping.

Tool Manager Section

Setting TagSetting Value TypeSetting Description
toolDsoNameTemplatestring Defines a template to generate tool DSO file names from tool class names. The template is a printf-style format string with a single %s placeholder that is replaced with the tool class name by the tool manager. The setting defaults to the appropriate template to use the installed Vrui tools. The tool manager splits the given template name into base directory and pattern parts, and initializes its DSO file locator using the base directory.
toolSearchPathslist of strings List of additional directories to search for tool plug-in DSOs. The directory extracted from the tool DSO name template is searched first, then all directories from the list in order until a matching DSO file is found.
toolClassNameslist of strings List of names of tool classes recognized by the tool manager (and offered to users via the Tools menu). Tool classes are instantiated in order of appearance in the list; tool classes that depend on other tool classes must be listed after their dependencies.
killZoneBaseDevicestring Name of the input device the tool kill zone is attached to. By default, the tool kill zone is not attached to any input device and positioned in physical coordinates.
killZoneTypeenumerant
Box
3D rectangular kill zone. Rest of section contains box tool kill zone settings.
Frustum
3D frustum kill zone, defined by a viewer, a screen, and a box in screen coordinates. Covers all input devices that are projected into the screen space box from the viewer's head position. Rest of section contains frustum tool kill zone settings.
killZoneRenderboolean Flag whether to render the tool kill zone in the Vrui display environment.
killZoneMaterialmaterial Defines the material properties to render the tool kill zone.
toolNameslist of strings List of names of tool assignment sections. Tool assignments in this list will be processed by the tool manager during Vrui initialization; in other words, these are the default associations for the Vrui environment.

Box Tool Kill Zone Settings

Setting TagSetting Value TypeSetting Description
killZoneCenterpoint Center point of the kill zone in physical coordinates (if no killZoneBaseDevice is specified) or in local device coordinates.
killZoneSizevector Size of the kill zone box along the three primary coordinate axes in physical units.

Frustum Tool Kill Zone Settings

Setting TagSetting Value TypeSetting Description
killZoneViewerNamestring Name of the viewer the kill zone is associated with. The kill zone is defined as a pyramid extending from the viewer's eye position through the rectangle defined by the kill zone center and size in screen coordinates.
killZoneScreenNamestring Name of the screen the kill zone is associated with.
killZoneCenterpoint Center point of the kill zone in local screen coordinates of the screen the kill zone is associated with.
killZoneSizevector Size of the kill zone along the three primary axes of screen coordinates of the screen the kill zone is associated with. The third size component corresponds to a direction normal to the screen plane and is ignored.

Tool Assignment Sections

Setting TagSetting Value TypeSetting Description
toolClassstring The name of the tool's class.
deviceName<index>string The name of the input device the tool is associated with.
device<index>ButtonIndexBaseinteger Base index of the tool's buttons in the input device's button name space.
device<index>ButtonIndex<index>integer Index of the given tool button in the input device's button name space. If not provided, defaults to the base index plus the index of the tool button.
device<index>ValuatorIndexBaseinteger Base index of the tool's valuators in the input device's valuator name space.
device<index>ValuatorIndex<index>integer Index of the given tool valuator in the input device's valuator name space. If not provided, defaults to the base index plus the index of the tool valuator.

Vislet Manager Section

Setting TagSetting Value TypeSetting Description
visletDsoNameTemplatestring Defines a template to generate vislet DSO file names from vislet class names. The template is a printf-style format string with a single %s placeholder that is replaced with the vislet class name by the vislet manager. The setting defaults to the appropriate template to use the installed Vrui vislets.
visletSearchPathslist of strings List of additional directories to search for vislet plug-in DSOs. The directory extracted from the vislet DSO name template is searched first, then all directories from the list in order until a matching DSO file is found.

Tool Class Settings

MouseNavigationTool

Setting TagSetting Value TypeSetting Description
rotatePlaneOffsetnumber The mouse navigation tool uses an offset plane formula to calculate the rotation axis based on the mouse position and mouse motion in screen coordinates. If the plane offset is zero, any mouse movement will rotate around the screen's z axis (roll); a large plane offset will favor rotation around the screen's x and y axes (yaw and pitch, respectively).
rotateFactornumber Distance in physical units the mouse pointer has to move on screen to rotate the view by one radians.
invertDollyboolean Flag whether to invert the dolly/zoom switch. If this flag is false (the default), pressing the tool buttons 0 and 1 together will zoom, while additionally pressing tool button 2 will dolly in/out of the screen. If this flag is true, the button combinations for zoom and dolly are reversed.
screenDollyingDirectionvector Direction in screen coordinates in which the mouse pointer has to move to dolly in/out of the screen.
screenScalingDirectionvector Direction in screen coordinates in which the mouse pointer has to move to zoom in/out.
dollyFactornumber Distance in physical units the mouse pointer has to move on screen along the dollying direction to dolly in/out by one physical unit.
scaleFactornumber Distance in physical units the mouse pointer has to move on screen along the scaling direction to zoom in/out by a factor of e (2.71...).
wheelDollyFactornumber Amount of dolly movement in physical units triggered by one tick of the mouse wheel.
wheelScaleFactornumber Factor of zooming triggered by one tick of the mouse wheel.
spinThresholdnumber Distance in physical units the mouse pointer has to move while tool button 0 is released to trigger spinning animation.
showScreenCenterboolean Flag whether to draw crosshairs highlighting the center of rotation and zooming during navigation.
interactWithWidgetsboolean Flag whether the mouse navigation tool's first button can also be used to interact with on-screen 3D GUI widgets. If set to true, the first tool button only starts rotating if it is not pressed over a GUI widget; otherwise, it interacts with the widget. This is an evil hack until a better tool chaining method comes along.

MouseDialogNavigationTool

Setting TagSetting Value TypeSetting Description
rotatePlaneOffsetnumber The mouse navigation tool uses an offset plane formula to calculate the rotation axis based on the mouse position and mouse motion in screen coordinates. If the plane offset is zero, any mouse movement will rotate around the screen's z axis (roll); a large plane offset will favor rotation around the screen's x and y axes (yaw and pitch, respectively).
rotateFactornumber Distance in physical units the mouse pointer has to move on screen to rotate the view by one radians.
screenDollyingDirectionvector Direction in screen coordinates in which the mouse pointer has to move to dolly in/out of the screen.
screenScalingDirectionvector Direction in screen coordinates in which the mouse pointer has to move to zoom in/out.
dollyFactornumber Distance in physical units the mouse pointer has to move on screen along the dollying direction to dolly in/out by one physical unit.
scaleFactornumber Distance in physical units the mouse pointer has to move on screen along the scaling direction to zoom in/out by a factor of e (2.71...).
spinThresholdnumber Distance in physical units the mouse pointer has to move while tool button 0 is released to trigger spinning animation.

FlashlightTool

Setting TagSetting Value TypeSetting Description
lightColorcolor Color of the light emitted by the tool.
lightSpotCutoffnumber Maximum angle in degrees that the tool's light source emits away from the input device's ray direction.
lightSpotExponentnumber Exponent controlling the dropoff in emitted light intensity away from the input device's ray direction.

FlyNavigationTool

Setting TagSetting Value TypeSetting Description
flyDirectionvector Movement direction in input device's coordinate system.
flyFactornumber Movement speed in physical coordinate units per second.

FPSNavigationTool

Setting TagSetting Value TypeSetting Description
rotateFactornumber Rotation sensitivity expressed as distance in physical coordinate units the input device has to be moved on the main screen to rotate by an angle of 1 radians.
moveSpeednumber Movement speed in physical coordinate units per second.

InputDeviceTool

Setting TagSetting Value TypeSetting Description
createInputDeviceboolean Flag whether an input device tool creates a new virtual input device when created.
newDeviceNumButtonsinteger Number of buttons to create on a newly created input device.

JoystickNavigationTool

Setting TagSetting Value TypeSetting Description
numButtonsinteger Number of buttons to use for all tools of this class.
toggleButtonIndiceslist of integers List of indices of buttons to treat as toggle buttons.
rotateFactornumber Base angular velocity of all rotational axes expressed as radians per second when an axis valuator is at the limit.
rotationalAxeslist of axis descriptors List of descriptors for rotational axes. The rotation axis' length is used as a multiplicator for the base angular velocity.
translateFactornumber Base linear velocity of all translational axes expressed as physical coordinate units per second when an axis valuator is at the limit.
translationalAxeslist of axis descriptors List of descriptors for translational axes. The translation vector's length is used as a multiplicator for the base linear velocity.
navigationToggleButtonIndexinteger Index of button to toggle between controlling the virtual input device and navigating the environment.
deviceGlyphTypeglyph type Type of glyph to render the virtual input device.
deviceGlyphMaterialmaterial Material to render the virtual input device glyph.

LaserpointerTool

Setting TagSetting Value TypeSetting Description
rayLengthnumber Length of the ray emitted by the tool in physical coordinate units.
rayLineWidthnumber Cosmetic line width to render the emitted ray in pixels.
rayColorcolor Color of the emitted ray.

Setting TagSetting Value TypeSetting Description

Setting TagSetting Value TypeSetting Description

Setting TagSetting Value TypeSetting Description

Setting TagSetting Value TypeSetting Description

Setting Value Types

Mapping from a tool valuator to a translational or rotational axis on a navigation tool. Encoded as a pair of parentheses containing an integer (the index of the mapped valuator), followed by a comma and a vector (the rotation axis or translation vector).
Type NameDescription
boolean Logical value; can be set to the literals true or false.
enumerant One out of a fixed set of possible choices, expressed as literals. Allowed literal values are listed in the setting's description.
key name Name of a key on the keyboard, expressed as a literal. Labeled keys have their own names, and the following "special" key names are recognized: Space, Tab, Return, Backspace, Left, Up, Right, Down, PageUp, PageDown, Home, End, Insert, Delete, Num0, Num1, Num2, Num3, Num4, Num5, Num6, Num7, Num8, Num9, Num/, Num*, Num-, Num+, NumEnter, NumSep, LeftShift, RightShift, LeftCtrl, RightCtrl, LeftAlt, RightAlt, LeftMeta, RightMeta, LeftSuper, RightSuper, LeftHyper, RightHyper.
integer Positive or negative integer number. Consists of an optional plus or minus sign, followed by a sequence of at least one decimal digits.
number Positive or negative floating-point number. Consists of an optional plus or minus sign, followed by a sequence of at least one decimal digit defining the number's integer part, and an optional dot followed by a sequence of at least one decimal digits defining the number's fractional part.
string A sequence of characters enclosed in double quotes. Strings support C-style escape sequences using the backslash escape charater; e.g., \t gets translated to a TAB character, \" is a double quote, and \\ is a backslash. If a string only contains letters, digits, underscores, or escape sequences, the quotes are optional.
list A list of values of another arbitrary setting value type. A list is encoded as a pair of parentheses containing a comma-separated list of an arbitrary number of values.
point A point in 3D affine space, encoded as a list of exactly three numbers (x, y, and z components).
vector A vector in 3D affine space, encoded as a list of exactly three numbers (x, y, and z components).
plane An oriented plane (half-space) in 3D affine space, encoded as a vector (non-normalized normal vector) followed by a comma and a number (origin distance in terms of normal vector length).
tracker state A position and orientation in 3D affine space, encoded as a sequence of basic transformations separated by multiplication signs. The basic transformations are:
translate <translation>
Translates the coordinate system by the given translation vector.
rotate <axis>, <angle>
Rotates the coordinate system around the given non-normalized axis vector, by the given angle number in degrees.
orthogonal transformation A transformation consisting of any combination of translations, rotations, and uniform scalings, encoded as a sequence of basic transformations separated by multiplication signs. The basic transformations are:
translate <translation>
Translates the coordinate system by the given translation vector.
rotate <axis>, <angle>
Rotates the coordinate system around its own origin and the given non-normalized axis vector, by the given angle number in degrees.
scale <factor>
Scales the coordinate system around its own origin by the scaling factor number.
color An RGB color with opacity component, encoded as a list of three or four numbers (red, green, blue, and (optional) opacity components, scaled from 0.0 to 1.0). If the opacity component is missing, it is initialized to 1.0.
material An OpenGL material property, encoded as a pair of curly braces containing a sequence of semicolon-terminated component settings. Omitted components are set to the OpenGL default values. The available component settings are:
Ambient = <ambient color>
Ambient color of the material.
Diffuse = <diffuse color>
Diffuse color of the material.
AmbientDiffuse = <ambient and diffuse color>
Ambient and diffuse color of the material.
Specular = <specular color>
Specular color of the material.
Shininess = <shininess>
Shininess exponent number of the material.
Emission = <emissive color>
Emissive color of the material.
glyph type Type of a 3D icon, encoded as a literal. Available values:
None
No icon.
Cone
A cone with the apex at the origin, oriented along the y axis.
Cube
A cube centered around the origin.
Sphere
A sphere centered around the origin.
Crossball
A cube centered around the origin, with three cylinders oriented along the x, y, and z axes, respectively.
Box
A "wireframe" box composed of oblong rectangles as edges and cubes as vertices.
screen protector Description of a sphere around an input device that triggers a visual alarm when touching a protected display screen. Encoded as a set of parentheses containing a string (the name of an input device), followed by a comma and a point (the center of the sphere in the device's coordinate system), followed by a comma and a number (the radius of the sphere).
window point A point in 2D window space, encoded as a list of exactly two numbers (x and y components, scaled from 0.0 to 1.0).
window position The position and size of a display window, encoded as a list of exactly two integers (window position in pixels), followed by a comma and a list of exactly two integers (window size in pixels).
axis value mapper Defines a mapping from a device's raw absolute or relative axis values to the range [-1, 1] used by Vrui, using a "broken line" model. Encoded as a list of exactly four numbers: the raw value mapped to -1, a pair of raw values defining a "flat zone" such that all raw values between the first and second are mapped to zero, and the raw value mapped to 1.
axis descriptor Mapping from a tool valuator to a translational or rotational axis on a navigation tool. Encoded as a pair of parentheses containing an integer (the index of the mapped valuator), followed by a comma and a vector (the rotation axis or translation vector).