The VR Juggler Configuration Guide

A configuration element is the fundamental unit of configuration within VR Juggler. Each config element is composed of one or more properties and is identified by a user-specified name. Each property has a type such as string, integer, pointer, etc., and properties can have either a fixed number of values or a variable number (zero or more) of values. The conceptual structure of a simple config element is shown in Figure 1.1, “Simple Configuration Element”.

Figure 1.1. Simple Configuration Element

In the figure, we see that the property named Size has two values: width and height. The valid type for both values of this property is integer. In general, all the values of a given property will have the same type. While there are exceptions to this, we will not go into such details at this time. In nearly all current cases, remember that the values of a property all share the same type.

The list of valid types for properties is shown in Table 1.1, “Valid Property Types”. A basic understanding of the valid types and their run-time interpretation in C++ can be useful when entering values. For example, note that the property type “integer” can be interpreted as a wide variety of C++ integer types. In some cases, the component being configured may limit the range of valid integer values that can be accepted from a config element. Hence, it can be important to know what the range of valid values is for a given property.

Note that the last entry in Table 1.1, “Valid Property Types” is “config element.” This means that config elements can be nested within other config elements. A nested config element is often called an embedded config element. There is no limit to the depth of config element nesting, but in general, config elements are rarely nested more than one level deep. Doing so can complicate user understanding of the configuration process. It is hoped, however, that continued improvements to the VR Juggler configuration editor will alleviate confusion related to nested config elements. For now, it is sufficient to understand that a nested config element is just another property type.

The specification of property types, the number of allowed values, and other structural aspects of config elements are defined by configuration definition , or simply “config definitions.” The relationship between config elements and config definitions is quite similar to that of objects and classes in object-oriented languages. A class defines structural and behavioral information, and an object is an instance of a class. At any time, there can be many instances of a single class, each referenced by a different variable. Similarly, a config definition defines structural information, and a config element is an “instance” of the definition. There can be many config elements for a given definition, and each config element is identified by its unique name. Config definitions even support a limited form of multiple inheritance.

Config definitions are found in files that are named based on the config element type defined therein and have the extension .jdef. To allow versioning of config elements, a given config definition may have many versions, each of which is identified by an integer value that is incremented each time a structural change is made to the definition. Config definitions are loaded by scanning directories listed in an environment variable. VR Juggler performs this scan before any attempt to load a config file is made to ensure that the run-time environment knows about all existing config definitions.

VRJConfig is the Java®-based graphical user interface (GUI) for creating and editing VR Juggler configurations. A screen shot of the VRJConfig Configuration Editor is shown in Figure 1.2, “VRJConfig”. It is based on Tweek, an implementation of a distributed model/view/controller system. Without going into great detail about the Tweek Java® API, it is sufficient to state VRJConfig exists as a collection of JavaBeans™ loaded by and executed within the Tweek JavaBean™ Loader.

Figure 1.2. VRJConfig

The VRJConfig Configuration Editor represents the low-level, all-purpose editor. It is capable of editing any config element. The representation of a config element provided by this editor shows both the property values and the structure of the element.

It is important to understand, however, that VRJConfig strives to provide an interface for configuration editing as opposed to the lower level concept of property editing. As was noted earlier, .jconf files can be edited manually using an ordinary text editor. This approach would be considered property editing because the user concentrates on the values of individual properties without necessarily considering the whole config element let alone the whole configuration. With the VRJConfig Configuration Editor, the intention is to provide more of a big-picture view of a collection of config elements as a complete configuration rather than as an assortment of disparate property values.

Configuration Contexts

The VRJConfig Configuration Editor utilizes a multi-document interface (MDI) paradigm. Each internal window is called a configuration context, or simply a “context.” Each context should be treated as a complete configuration to achieve proper use of VRJConfig. Throughout the discussion of configuration contexts, the main toolbar at the top of the VRJConfig Configuration Editor panel will be important. It is shown again in Figure 1.3, “VRJConfig Configuration Editor Main Toolbar” to distinguish it from the full editor GUI.

Figure 1.3. VRJConfig Configuration Editor Main Toolbar

Creating a Configuration Context

A new config context can be created either by opening an existing .jconf file or by creating a new .jconf file. In either case, a new internal window will open within the VRJConfig Configuration Editor. The main toolbar has buttons for creating a new .jconf file and for opening an existing .jconf file. They are highlighted in Figure 1.4, “VRJConfig Configuration Editor New and Open Buttons”.

Figure 1.4. VRJConfig Configuration Editor New and Open Buttons

Once the context is created, the view of VRJConfig will be similar to what was shown earlier in Figure 1.2, “VRJConfig”.

Managing Multiple Files in a Configuration Context

The purpose of a configuration context within VRJConfig is to facilitate the notion of editing a configuration as a whole. As such, adding more .jconf files to an open context is a common operation. Each context has its own toolbar that is independent of the main VRJConfig Configuration Editor toolbar, and this toolbar is what must be used to extend or modify the state of a given configuration context. The context-specific toolbar is shown in Figure 1.5, “VRJConfig Configuration Context Toolbar”.

Figure 1.5. VRJConfig Configuration Context Toolbar

On the left side of the toolbar, we see the usual icons for file creation, opening, and saving. To add a new .jconf file to the existing config context, either the New or the Open button must be used. Using the New or the Open button from the main VRJConfig toolbar will result in the creation of a new configuration context.

On the right side of the context-specific toolbar, we see a button with an icon that is a downward pointing arrow. This button is only active when there are at least two .jconf files open in the VRJConfig Configuration Editor as a whole. Clicking the button reveals a special menu shown in Figure 1.6, “VRJConfig Context Modification Menu”. In the menu, the selected .jconf files are those that are open in the current context. Selecting a file from the menu will add it to the current context. De-selecting a file removes it from the context. In this way, it is possible to build up config contexts using different config files.

Figure 1.6. VRJConfig Context Modification Menu

Managing Multiple Configuration Contexts

With multiple configuration contexts open, it is often desirable to move or copy config elements around. The MDI paradigm helps make this possible by allowing multiple windows to be visible at once, and cut/copy/paste support within the VRJConfig Configuration Editor completes the picture. Note, however, that the granularity of cut/copy/paste operations—including drag and drop—is at the level of config elements. Individual properties cannot be copied between contexts or between config elements.

Navigating the Config Element Hierarchy

On the left side of each config context window is a tree view of the config element hierarchy (as seen in Figure 1.7, “VRJConfig Config Element Navigator Panel”). This hierarchy is a dynamically updating organizational model of all the config elements in the current configuration context. Within the tree, names shown in bold text are categories. Names shown in non-bold text are config element names. As config elements are added to and removed from the current context, the tree structure will change. Empty categories are not shown.

Figure 1.7. VRJConfig Config Element Navigator Panel

The config element hierarchy also depicts the hierarchy inherent in config elements. That is, the nesting of config elements within config elements is shown, too. This allows quick, direct access to nested config elements for property editing purposes.

Adding and Removing Config Elements

Adding new config elements to a configuration context is easy. Simply click the Add button shown above the config element hierarchy; it is always active. When clicked, a dialog box is opened that is used for choosing the type of config element to add to the context. The list, shown in Figure 1.8, “Config Element Chooser”, displays the human-friendly names of all known config element types. Entering text into the field labeled Config Element Type causes the selection to jump to the first element matching the entered text. This search is a rudimentary, exact-match type of search.

Figure 1.8. Config Element Chooser

For a more advanced search capability, click the tab labeled Search. The dialog box will change to what is shown in Figure 1.9, “Config Element Search Dialog”. Initially, the config element list is empty, but as soon as text is entered into the search field, all elements whose human-friendly identifier match the entered text will be displayed. This search supports sub-string matches of search terms. The Search tab is useful to users who know exactly what they want or who have an idea of what to look for. In Figure 1.9, “Config Element Search Dialog”, the user started entering the word window as a search term, and all three possibilities for window-related config elements were immediately displayed.

Figure 1.9. Config Element Search Dialog

Once the element type is chosen, click the OK button. A new element will be created in the current context with all of its property values initialized to their default setting. If multiple files are open within the context, another dialog box will be opened asking the user for a destination file for the new element. The first thing to do after creating a new config element is to set its name. In the config element hierarchy, new elements are created with a simple, unique name based on the human-readable description of the element type. To rename the element, either double-click on its name or right-click on the name and choose the Rename item from the pop-up menu.

Caution

In some cases, it is necessary to triple-click on the name of a config element in the hierarchy tree. This is because Java® sometimes interprets a double-click within a tree as an expand/collapse command for that branch of the tree. To get the correct behavior every time, right-click on the name of the config element to get the pop-up menu and choose Rename.

To remove a config element, click on its name within the hierarchy and click the Remove button. Otherwise, right-click on the element and choose the Remove item from the pop-up menu.

Editing Configuration Elements

The largest panel in the configuration context window is devoted to editing configuration elements. The full config element selected in the element tree is shown in this panel. From this panel, the individual property values can be edited. The view shown in this panel is designed to illustrate the hierarchical structure of a config element. Panels are nested within panels to show the nesting of config elements within config elements. Multi-value properties are rendered using a layout that shows data grouping as opposed to nesting.

Properties with a Fixed Number of Values

Editing properties with a fixed number of values is straightforward. Those that have a multiple values may need to be expanded to show the full list, but no extra steps are required to insert entries that can be edited. VRJConfig will always show the full number of values for this variety of property. For new config elements, it will fill in the default setting for each of the property's values.

Properties with a Variable Number of Values

Properties with a variable number of values are a little more tricky. This variety of property can have zero or more values set, and the default case is to have zero values set. As such, new values must be added before editing can take place. In Figure 1.10, “Editing a Property with a Variable Number of Values”, we see two highlighted buttons: one for adding a new value and one for removing an existing value. The New Value button is always at the top center of the inset panel while the Remove Value button appears on the right side of the inset panel. There will be one Remove Value button per value present in the config element.

Figure 1.10. Editing a Property with a Variable Number of Values

The values of a property with a variable number of values may be reordered using VRJConfig. Depending on the interpretation config element, this may be useful for changing the processing order of the values. An example of this is shown in Figure 1.11, “Changing the Order of Property Values”. The highlighted up and down buttons move the associated value up or down one position in the ordering of the property's values.

Figure 1.11. Changing the Order of Property Values

Editing a static configuration represents the usual configuration editing process. This means that configuration files are loaded from permanent into VRJConfig. When the editing is complete, the files are saved back to permanent storage to be loaded at a later time by VR Juggler. Following this procedure stays with the traditional configuration process, depicted as follows:

This process does not harness the full potential of VR Juggler. Through its run-time reconfiguration capabilities, VR Juggler can be reconfigured on the fly using VRJConfig as a remote configuration editing tool. That is, VRJConfig can connect to a running application and edit its configuration without requiring the application to be shut down and restarted. A full discussion of this topic is postponed until Chapter 5, Remote Run-Time Reconfiguration Using VRJConfig.

Besides the low-level Configuration Editor, VRJConfig includes a component known as the “Control Panel.” It is named this way because it is styled after the Microsoft Windows® Control Panel. Through the Control Panel, users are presented with high-level, or “custom,” editors that are designed for specific configuration tasks. Furthermore, the Control Panel provides configuration creation tools in the form of wizards that combine multiple high-level editors into a step-by-step configuration process. Whereas the Configuration Editor is capable of editing any type of config element, customized code must be written for use by the Control Panel to edit specific element types. As of this writing, editors exist for the Ascension Flock of Birds®, the Ascension MotionStar Wireless®, the Fakespace Pinch™ Gloves, and the InterSense IS-900™ devices. There is also an editor that presents a directed graph representation of the all the proxies in the config context.

The VRJConfig Control Panel is loaded by clicking on the Control Panel JavaBean™, which is nested under the VRJConfig category. When it is first loaded, the Control Panel appears as shown in Figure 1.12, “VRJConfig Control Panel Start Screen”. The individual panels within the Control Panel are a mixture of category icons and editor or wizard icons. Clicking an icon either navigates to a sub-category or opens a high-level editor or a wizard, depending on what the icon represents. The Back and Forward buttons (in the upper right-hand corner) allow navigation through the panels.

The Control Panel is organized in a hierarchical manner. This is similar to the way that the low-level Configuration Editor organizes config elements in its navigator panel (refer back to Figure 1.7, “VRJConfig Config Element Navigator Panel”). The two hierarchies are similar, but the Control Panel hierarchy is not as dynamic as the Configuration Editor's navigator panel. Indeed, the Control Panel hierarchy is defined statically by the Control Panel configuration file (interested readers can see it in $VJ_BASE_DIR/share/vrjuggler/data/ControlPanel.xml) in order to avoid requiring many mouse button clicks just to get to the desired editor or wizard.

Figure 1.12. VRJConfig Control Panel Start Screen

The driver search path provides the Input Manager with a list of directories where driver DLLs may be found. This property has a default setting determined at the time when the Input Manager was compiled. Based on the current list of supported operating systems, the default search path will be one of three values:

Since the base collection of device drivers that come with Gadgeteer are guaranteed to appear in the default search path, there is usually no need to set a value for the Input Manager driver search path property. The search path is configurable to allow users to tell the Input Manager where to find drivers they have written themselves that appear outside the VR Juggler installation hierarchy. When one or more values are provided through the driver search path property, the default search path is always appended to the end of the list. This ensures that user-specified directories will always be searched first when loading drivers.

When setting the driver search path, environment variables are allowed. As with all uses of environment variables in VR Juggler configuration files, they must be specified using either the form ${ENV_VAR} or $(ENV_VAR). Using $ENV_VAR or %ENV_VAR% will not work in this case or any other case. Any environment variable may be used.

The driver DLL name property is used to name specific device drivers to load. The name of the DLL to load must be specified in a special platform-agnostic manner. Essentially, this form boils down to removing the file extension from the DLL name. For example, the Ascension MotionStar Wireless® DLL may be named MotionStar_drv.so, MotionStar_drv.dylib, or MotionStar_drv.dll depending on the host operating system. Note that all three have a common base name: MotionStar_drv. In the configuration of the Input Manager, this common base name is the string to set for the property value. This aids with portability of configuration files and (we hope) reduces the mental overhead required to configure the Input Manager on different operating systems where conventions will almost certainly vary.

The driver scan path provides a mechanism for loading all the device drivers found in the named directory or directories. This behavior is very similar to the old Input Manager that knew about all the device drivers, but in this case, the drivers are not statically compiled into the Input Manager. Use of this property is helpful when there is no need or no desire to load drivers individually. Doing so increases the memory overhead of the Input Manager, but it dramatically reduces the possibility for configuration errors related to driver loading.

As with the driver search path, environment variables can be used in the string value(s) provided for this property. Furthermore, there is no need to specify a platform-specific file extension for use when scanning a directory for device drivers. The file extension is determined at compile time based on the target operating system. The search criterion used by the Input Manager is that the files match the pattern *_drv.<ext> where <ext> is the platform-specific file extension set at compile time.

Physical devices are those that provide what is traditionally considered immersive input. Typically, such devices have multiple degrees of freedom and/or provide specific information about what the user is doing. For example, a glove device could provide data identifying a specific hand gesture that the user is making. By attaching a 6DOF tracker sensor to the glove, both the position of the hand and the gesture it is making would be available to an immersive application. Placing tracker sensors all over the user's body provides full-body position and orientation information.

In terms of the Gadgeteer Input Manager, physically devices have thus far been characterized as requiring a device driver plug-in. The driver implements in software the communication protocol with the hardware so that data can be read from the device and interpreted before being passed on to the VR Juggler application. As of this writing, it is certainly true that each supported physical device has its own device driver plug-in. Though this could change in the future, it will be useful to remember this fact for the purposes of the topics presented here.

The process of configuring a physical device means configuring its device driver. As noted above, there is very little commonality in the process of configuring specific hardware devices, but it is vital to understand the importance of properly configuring a device driver as part of the overall input configuration. If the driver itself is not configured correctly, there is no way that the rest of the input chain can function properly. In other words, if the driver cannot read data from the input device, there will be nothing to pass on to the VR Juggler application. For instructions and tips on specific device configurations, refer to the appendices at the end of this book.

Since all physical devices do have a device driver plug-in, proper configuration of the Input Manager is absolutely critical. Configuration elements for device drivers are handled by the drivers themselves, and if the Input Manager does not load a required device driver, the config element cannot be processed^[2]. As such, it is very important to remember to configure the Input Manager as part of configuring a physical device.

The configuration of simulator devices is much more involved than that required for physical devices. All simulator devices read data from a traditional desktop keyboard and mouse and translate the data into information that mimics the behavior of the various device types supported by the Input Manager^[3]. To configure a simulator device, there are three pieces that must be configured: a keyboard/mouse input handler, an input window, and the actual simulator device. We explain this in more detail below.