Vrui 2.xxx-yyy Release Notes

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

User-Level Changes

Greater tool binding flexibility
In Vrui 1, each tool class had a hard-coded input layout, consisting of one or more input devices, and zero or more buttons or valuators per devices. It was not possible to bind two button or valuator slots from the same device slot to two different input devices, severly restricting the user's ability to build complex input graphs. In Vrui 2, tools still expect a certain number of buttons and valuators, but these can be provided from any number of input devices. Additionally, tool classes can request optional buttons or valuators, which are assigned to optional tool functions in the order in which they are bound.
Modal interactive tool binding procedure
The procedure to bind tools requiring multiple buttons and/or valuators in Vrui 1 was to press the first button, and before making a tool class selection from the tool menu, pressing and releasing all additional buttons and/or valuators to be bound. In Vrui 2, the procedure is to press the first button or valuator, select a tool class from the tool menu, and then press buttons or valuators in the order in which they are to be bound as prompted by the tool creation dialog. To cancel tool creation, or finish binding optional buttons or valuators, one presses the first button or valuator again.
Tool graph display
Vrui 2 can display the subgraph of the input graph that is mapped to a particular button or valuator. This can be requested by moving an input device into the tool kill zone, pressing a button or valuator, and then removing the input device from the tool kill zone before releasing that button or valuator again.
Loading and saving input graphs
To assist users in creating complex input graphs, Vrui 2 can save the current input graph, meaning all virtual input devices and all tools, to a configuration file fragment (InputGraph.cfg in the current directory). Such configuration file fragments can later be loaded back, exactly recreating the input configuration of a Vrui application. It is also possible to create complex input graphs by editing configuration file fragments using a plain text editor, and then load them into an application.
Default tool bindings in configuration files
In Vrui 1, tools to be loaded at application start-up were listed using a toolNames tag in the Tools section, followed by a number of subsections of the names defined in the toolNames tag. In Vrui 2, tools are loaded from a configuration file section that has the same format as the configuration file fragments written when "Save Input Graph" is selected from the Vrui System menu. The name of the section containing all tool sections is specified using the defaultTools tag in the Tools section.
Tool binding syntax
In Vrui 1, tool bindings were defined using a sequence of tags specifying single input devices, button indices, or valuator indices. In Vrui 2, tool bindings are defined using a single bindings tag, whose value is a list of binding items. Each binding item is a list containing the name of an input device, followed by any number of button or valuator names. Button or valuators from that list are bound to tool button or valuator slots in the order in which they occur.

Programmer-Level Changes

Vrui 2 contains 393 small or large changes compared to Vrui-1.0-068 (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 2. The following list are common problems and their solutions:
Method name change in GLMotif::Label
In Vrui 1, the GLMotif::getLabel function returned the label string of a label object as a C-style string. In Vrui 2, GLMotif::getLabel returns an object of class GLLabel. To get the actual string, one can either go through the GLLabel object, as in GLMotif::getLabel().getString(), or use the equivalent convenience function GLMotif::getString. This change was necessary to create a sane API using the GLLabel class, which in turn was a major performance improvement when rendering large number of labels. Analogously, to directly change the label string of a GLMotif::Label object, one uses GLMotif::Label::setString.

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

Additional tool factory methods
Tool factories are now expected to provide methods returning descriptive names for each of their tools' button and valuator slots, using the methods Vrui::ToolFactory::getButtonFunction and Vrui::ToolFactory::getValuatorFunction, respectively. While class Vrui::ToolFactory provides default implementations of both, developers are strongly encouraged to provided their own implementations.
Changed tool input layout
Vrui 2 uses a completely different tool input layout model. Tools no longer request a certain number of input devices, and a certain number of buttons and valuators for each input device, but simply a fixed number of buttons and valuators, with the option of allowing additional optional buttons and valuators. As a result, the syntax of input-related methods of class Vrui::Tool has changed: The convenience functions defined in Vrui::Tool have changed accordingly, taking only a single button or valuator slot index.