Vrui 3.xxx-yyy Release Notes

This page lists major changes between Vrui versions 2.xxx-yyy ("Vrui 2") and 3.xxx-yyy ("Vrui 3"), both for users and programmers.

User-Level Changes

Changes to configuration file syntax
Section names in configuration files are now read including special characters and whitespace. As a result, section names including anything but characters no longer have to be enclosed in double quotes, i.e., section "foo.bar.baz" becomes section foo.bar.baz. For backwards compatibility, double quotes around section names are detected and discarded.

There is now a concatenation operator for list-type tags. If foo is a list-type tag, i.e., its value is of the form (A1, A2, ..., An), then a line foo += (B1, B2, ..., Bm) will append the given list to the list currently assigned to foo, i.e., the result in the example will be the same as writing foo (A1, A2, ..., An, B1, B2, ..., Bm). Concatenation works for any list element type, including lists, but it can only be applied to the outermost list level.

New VR device daemon protocol
The protocol between a VR device daemon (Vrui's input device driver) and a Vrui application has been augmented by so-called "virtual input device" descriptors. The upshot is that the necessary configuration to assemble scattered trackers, buttons, and valuators into cohesive input devices, which was previously done in Vrui.cfg, is now done in VRDevices.cfg. The main benefit is that this centralizes device management into a single location, and makes the communication between a device daemon and applications much more robust to changes in device layout.
Support for Oculus Rift head-mounted displays
Vrui now natively supports Oculus Rift head-mounted displays, including their built-in inertial 3-DOF low-latency trackers. There is a new device daemon module "OculusRift," and there is support for post-rendering lens distortion correction in the Vrui run-time. There is also a new calibration utility, "OculusCalibrator," to perform hard- and soft-iron correction on the Rift's built-in magnetometer, fine-tune the built-in linear accelerometers, auto-generate configuration file sections, and calculate yaw orientation correction transformations.

Programmer-Level Changes

Vrui 3 contains around 100 small or large changes compared to Vrui-2.8-001 (documented in the HISTORY file), and several of these are API changes that break existing code. However, most of those are purely syntactic and can be found (and fixed) by recompiling existing application code against Vrui 3. The following list are common problems and their solutions:
Addition of rayStart element to Vrui::InputDevice
This new element allows offsetting a device's selection ray along the ray direction. The primary reason is much improved handling of mouse input devices. As a result, the Vrui::InputDevice::setDeviceRayDirection method has been removed, and replaced by Vrui::InputDevice::setDeviceRay, which takes both a ray direction and a ray offset as parameters.
Changes in Misc/ArrayValueCoders.h
Misc::FixedArrayValueCoder and Misc::DynamicArrayValueCoder keep numElements and elements pointer as object state instead of expecting them as method parameters; encode and decode methods are no longer static. In Misc::DynamicArrayValueCoder::decode, the initial value of numElements is taken as the maximum number of supported elements, and is changed to the actual number of decoded elements upon return.
Misc::ConfigurationFile value access methods
The retrieveValue and storeValue methods in Misc::ConfigurationFile that take non-standard value coder classes now expect an object of the value coder class as last parameter. These methods names have been changed to retrieveValueWC and storeValueWC (WC: with coder) to avoid template ambiguities.

The following few changes require programmer attention, as old code will not generate compiler errors, but cease to function properly:

Signature of Vrui::Tool::configure
The type of the configuration file section parameter in the Vrui::Tool::configure virtual method has been changed to const Misc::ConfigurationFileSection& to be in line with the rest of the Vrui API. In derived tool classes using the old signature, the configure method will no longer be called because the compiler considers it a different function.