VR Juggler

A convention used throughout this book is to name the variables using all capital letters. In almost all cases, regardless of the shell, this is the naming convention used for environment variables.

Setting a path with an environment variable can require special syntax. Because of this, the method for doing so may vary from shell to shell. Paths are important with VR Juggler when looking up the path to a shared library (dynamically linked library). For each shell, the syntax for setting a path is given.

Referring to environment variables can also vary from shell to shell. An example of how to print the value of an environment variable will be given for each shell. An example of how to refer to an environment variable is also provided as these two operations may vary even within one kind of shell!

In all shells, an environment variable is only available within that single shell instance. That is, setting an environment variable at a command prompt only affects that specific shell and will not be available from other concurrent or future shells. To make a setting “permanent”, it should be done in file read by all shell instances when they are started. This is addressed briefly as appropriate for each shell type.

In a C-style shell (i.e., one whose interface is based on the C programming language), setting environment variables is done using the built-in command setenv. It is used as follows:

% setenv <VARIABLE_NAME> <value>

where the string <VARIABLE_NAME> represents the name of the variable you are going to set and <value> represents the value assigned to that variable. Both are required. If the named variable did not exist before, it will pop into existence. Otherwise, you overwrite the old setting with the new one.

To print the value of an environment variable, use the following command:

% printenv <VARIABLE_NAME>

Referring to a variable, however, is done using the following syntax:

% cd $VARIABLE_NAME/bin

Paths are specified as a colon-separated list. An example of this is:

% printenv PATH
/bin:/sbin:/usr/bin:/usr/sbin

For these types of shells, a “permanent” setting for a given variable should usually be done in your .cshrc file or in your .login file, both of which should be in your home directory. In most cases, it is better to use .cshrc because it is evaluated for every shell instance.

In a shell based on sh, setting environment variables is done using the built-in command export. It is used as follows:

% export <VARIABLE_NAME>=<value>

or

% <VARIABLE_NAME>=<value>
% export <VARIABLE_NAME>

Here, the string <VARIABLE_NAME> represents the name of the variable you are going to set and <value> represents the value assigned to that variable. Both are required. Note that there is no space between the variable name and its value. If the named variable did not exist before, it will pop into existence. Otherwise, you overwrite the old setting with the new one. If the variable was already among your current shell's environment variables, the export command is not necessary.

To print the value of an environment variable, use the following command:

% echo $VARIABLE_NAME

Getting the value of a variable works the same way.

Paths are specified as a colon-separated list. An example of this is:

% echo $PATH
/bin:/sbin:/usr/bin:/usr/sbin

For these types of shells, a “permanent” setting for a given variable should usually be done in the .profile file in your home directory or in your shell's “rc” file. Different shells have different names for this file. Examples are .bashrc for BASH and .zshrc for Zsh. Please refer to your shell's documentation for more information. In any case, the file will be in your home directory.

The typical syntax for setting an environment variable from the command line (in a DOS shell window) under Windows® is:

C:\> set <VARIABLE_NAME>=<value>

Here, <VARIABLE_NAME> is the name of the environment variable to be set, and <value> is the value being assigned to that variable. If the named variable did not exist before, it will pop into existence. Otherwise, you overwrite the old setting with the new one.

To print the value of an environment variable, use the following command:

C:\> set <VARIABLE_NAME>

Referring to a variable, however, is done using the following syntax:

C:\> cd %VARIABLE_NAME%\bin

Paths are specified as a semicolon-separated list. An example of this is:

C:\> set PATH
C:\WINDOWS;C:\bin;C:\

For some versions of Windows®, a “permanent” setting for a given variable should usually be done in C:\AUTOEXEC.BAT. In newer versions (Windows® ME in particular) and in the Windows® NT line of operating systems, the setting is done using the Control Panel. Please refer to the next section for more information on that method.

Before reading this section, please be sure to have read the section called “DOS Shell”. This is necessary because the Windows® GUI for setting environment variables is simply a front-end to that older method and thus uses the same conventions and syntax. The versions of Windows® to which this subsection applies are indicated individually since each is a little different. For more detailed information, please refer to the Windows® online help system and search for “environment variables”.

Windows® 2000 and Windows® XP

In the Control Panel, open the System icon. Under the Advanced tab, there is a button labeled Environment Variables, shown in Figure 2.1, “Windows® 2000 System Properties Dialog” (the Windows® XP version is shown in Figure 2.2, “Windows® XP System Properties Dialog”). Clicking this button opens the dialog box shown in Figure 2.3, “Windows® Environment Variable Editor Dialog”. Here, you can set variables for yourself and, if you have the access privileges, for all users.

Figure 2.1. Windows® 2000 System Properties Dialog

Figure 2.2. Windows® XP System Properties Dialog

Figure 2.3. Windows® Environment Variable Editor Dialog

On Mac OS X, environment variables can be set in two different ways, just as on Windows®. They can be set as “global” environment variables available to all applications launched from the Finder, or they can be set within a Terminal window for use within that shell and by all applications launched from that shell. Refer to Apple's Technical Q&A QA1067 document for details on how to set global environment variables for use by the Mac OS X desktop interface. To set an environment variable within a Terminal window, refer to either the section called “C-Style Shells (csh, tcsh)” or the section called “sh-Derived Shells (sh, ksh, bash, zsh, etc.)” depending on the user's chosen shell (the default is tcsh).

To avoid tying this documentation to a single style of environment variable creation, assignment and reference, the following syntax will be used exclusively from this point onward. Please read this carefully before proceeding.

% <VARIABLE_NAME> = <value>

% echo $VARIABLE_NAME
value

% cd $VARIABLE_NAME/bin

All the sample programs in $VJ_DATA_DIR/samples use the same basic steps to compile unless otherwise noted. Always refer to the top of the sample application's Makefile for information that may be specific to building that application. In general, though, all applications' makefiles require the GNU version of the make(1) utility, sometimes installed as gmake.

The example used here will be the MPApp tutorial application found in $VJ_DATA_DIR/samples/OGL/simple/MPApp. It is an OpenGL-based application that will compile and run on all platforms supported by VR Juggler. Begin by changing into the directory $VJ_DATA_DIR/samples/OGL/simple/MPApp in a command shell.

To compile MPApp, simply enter the following:

% gmake

On Mac OS X, enter the following:

% make bundle

The compile process will then begin. As noted above, the use of GNU make is required to use the distributed makefiles. Now that you have a program compiled, it is time to learn how to run it. (Readers who are not using Visual Studio can skip ahead to Chapter 5, Running a VR Juggler Sample Program.)

All OpenGL sample applications are shipped with pre-configured Microsoft Visual C++ projects. This is done to help new users get started with compiling VR Juggler applications and to give experienced Visual Studio users a starting place for their application development. To use the workspace for the MPApp application, begin by opening the folder containing the source code and double-clicking on MPApp.vcproj.

Figure 4.1. Selecting the Visual C++ Project File

Visual Studio will open, and the MPApp project will be loaded. The unexpanded class view will appear as shown in Figure 4.2, “MPApp Project” when Visual Studio first loads.

Figure 4.2. MPApp Project

In some cases, it may be necessary to change the default project properties. The project properties dialog can be opened in several ways. For example, right-clicking on the project name in the Solution Explorer brings up the menu shown in Figure 4.3, “Project Menu”. We are interested in changing the project's properties, so we select the Properties item from the popup menu.

Figure 4.3. Project Menu

Under the MPApp project settings, the path(s) to the VR Juggler C++ dependencies must be filled in. This means setting paths to find headers and libraries. All the Visual C++ project files shipped with VR Juggler refer to the VR Juggler C++ dependency installation via the VJ_DEPS_DIR environment variable. If this is not set or cannot be used, the paths must be filled in manually.

Once the program properties are set, compile the application. Under the Build menu, choose the Build MPApp item as shown in Figure 4.4, “Build MPApp.exe”. Visual C++ will compile the application, and if you have everything configured properly on your computer, the compiling will complete successfully.

Figure 4.4. Build MPApp.exe

For the remainder of this book, much of the discussion will concentrate on running applications from the command line rather than from the Visual Studio GUI. Readers can follow whichever method they prefer.

Now it is time to run the application—finally! Make sure that all your environment variables are set properly before trying to start the application. Once you are ready, specify the name of the application and all the configuration files it needs. An example of this is:

% MPApp sim.base.jconf sim.wand.mixin.jconf

On Mac OS X, the command would be the following:

% MPApp.app/Contents/MacOS/MPApp sim.base.jconf sim.wand.mixin.jconf

Notice that no paths are specified for finding the configuration files. The full paths to the configuration files is not necessary because the default search path will correctly find these files in $VJ_BASE_DIR\share\vrjuggler\data\configFiles on Windows or $VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles on all other platforms. Beginning users will typically want to reference the example configuration files in that directory. As you get more comfortable with VR Juggler and its configuration system, you may want to make your own modified files and put them in the directory $HOME/.vrjconfig. The environment variable VJ_CFG_PATH is useful in providing a search path for finding your configuration files. (Refer to the section called “Relevant Environment Variables” for more information on using VJ_CFG_PATH). To simplify running applications, you may want to make a shell script (or batch file as appropriate) that does all the work of passing configuration files and common command-line arguments.

As the application starts, you will see a status output printed to the console (more or less depending on how you have VPR_DEBUG_NFY_LEVEL, VPR_DEBUG_ALLOW_CATEGORIES, and VPR_DEBUG_DISALLOW_CATEGORIES set), and then one moderately sized simulator display window will open on the left side of your screen while three blank keyboard input windows open on the right side of your screen. The display window will be titled “SimWindow1”, and the keyboard input windows will be titled “Head Keyboard”, “Sim View Cameras Control” and “Wand Keyboard” (in order from the top of the display to the bottom). Do not worry that the keyboard windows are black—that is normal. The display window will have an animated blue mesh, a cyan ellipsoid, and a green pointer. The mesh is what you have come to see; the ellipsoid is the user's head; and the pointer is the user's hand. In Figure 5.1, “MPApp Running on a Linux Desktop with Multiple Input Windows”, we show what this looks on a Red Hat Linux 7.2 desktop for comparison with what you are seeing. Note that the head and wand are only rendered in the simulator windows. They are present because head and wand input are being simulated, and it is typically quite helpful to see the results of that simulated input. To exit the application, press ESC in the window titled “Head Window”.

Figure 5.1. MPApp Running on a Linux Desktop with Multiple Input Windows

With VR Juggler 2.0 and beyond, it is possible to use a single window for graphics and for input. To use such a configuration, execute MPApp as follows:

% MPApp standalone.jconf

On Mac OS X, execute it this way:

% MPApp.app/Contents/MacOS/MPApp standalone.jconf

This time, only a single window opens, as shown in Figure 5.2, “MPApp Running on a Linux Desktop with One Window”. It shows the same graphics as before, but now it is configured to take keyboard and mouse input. To exit, press ESC in the graphics window.

Figure 5.2. MPApp Running on a Linux Desktop with One Window

Running an Application on Windows from Within Visual Studio

To run MPApp from within the Visual Studio IDE, the program arguments must be set first. This is done by opening the properties dialog for the project. In this dialog box, choose the Debugging item. There will be an empty text entry field under the heading Command Arguments. Here, enter the full paths to the VR Juggler configuration files that will be used to run the torus application. To use the VJ_BASE_DIR environment variable (or any other environment variable), makefile syntax must be used. In other words, to load somefile.jconf, use $(VJ_BASE_DIR)\share\vrjuggler\data\configFiles\somefile.jconf. As was stated above, the full path need not be specified, so referencing VJ_BASE_DIR in the path to the example configuration files will not be necessary in most cases.. In Figure 5.3, “Setting Command Arguments”, we see the use of standalone.jconf as the single command argument to MPApp.

Figure 5.3. Setting Command Arguments

With the application already compiled, execute the MPApp program by choosing the Start item from the Debug menu, shown below in Figure 5.4, “Execute MPApp.exe”.

Figure 5.4. Execute MPApp.exe

Running an Application on Mac OS X with Cocoa Windows

In VR juggler 2.2, Cocoa support has been added for Mac OS X usage. This gives much better results than the previous reliance upon the X Window System. The interface for VR Juggler applications on Mac OS X is noticeably different than other platforms, however. We will explore those differences in this section.

There are two key differences with VR Juggler on Mac OS X from other platforms:

1. Applications are constructed as bundles

2. Every application has the usual Mac OS application menu

The use of application bundles is required for software based on Cocoa. The topic of application bundles is beyond the scope of this document, but Apple has extensive documentation available for perusal. For typical VR Juggler applications, the bundle data files that come with VR Juggler 2.2 will suffice. The application bundle is constructed automatically using these files when the bundle target is built for any VR Juggler application whose build is based on Doozer 2.1.4 and newer. For builds that are not using Doozer, see the files in $VJ_DATA_DIR/data/bundle for a starting point.

The use of application bundles offers several different ways of launching applications. They are as follows:

• Double-clicking on the application bundle icon in the Finder

• Opening the bundle (e.g., MPApp.app) from the command line using open

• Executing the contained application directly from the command line

We have seen an example of the third option above, and in this document, we will always show that approach whenever describing how to launch a VR juggler application from the command line.

Using the open command offers two different options of its own. It can be used to open the bundle in the same way as double-clicking on its icon in the Finder would work. This usage is shown below:

% open MPApp.app

The other usage is to open a .jconf file and tell the open command to use a VR Juggler application bundle to handle the file open operation. This is done as follows:

% open -a MPApp.app $VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles/standalone.jconf

Note that the paths given to the application bundle and to the .jconf file must resolve correctly. No path searching will be performed for either in this case.

The application menu is defined by the .nib contained in the application bundle. This is hooked up to classes in VR Juggler at run time. The application menu is defined with the usual operations for window management as well as the File → Open... (Cmd+O) operation for loading .jconf files. This feature leverages the existing support for run-time reconfiguration of VR Juggler. Every time a .jconf file is opened using the File → Open... (Cmd+O) operation, VR Juggler reconfigures itself. This is basically the same as what can be done with VRJConfig when adding new configuration information dynamically. It is not possible to remove configuration information through this interface; VRJConfig must be used for that purpose.

When a VR Juggler application bundle is opened by double-clicking on its icon in the Finder or by using the first usage of the open command described above, no configuration files are loaded. The File → Open... (Cmd+O) operation must be used to load configuration files and configure VR Juggler. (Even remote run-time reconfiguration through VRJConfig may not be available at this point unless omniORB was configured to find a CORBA Naming Service instance through the OMNIORB_CONFIG environment variable.)

VR juggler applications on Mac OS X can be exited using the App Menu → Quit (Cmd+Q) operation or by using the application shutdown sequence in the same manner as any other platform. The shutdown sequence and the window(s) that accept it depend on the configuration. Usually, this is done by pressing the ESC key in a graphics window or in the input window for the simulated positional device for the user's head.

The Cocoa version of MPApp is shown executing on a Mac OS X desktop in Figure 5.5, “MPApp Running on Mac OS X Using Cocoa with One Window”. Note that in the Dock, the VR Juggler icon is activated. Though it cannot be seen, the application menu is for MPApp.

Figure 5.5. MPApp Running on Mac OS X Using Cocoa with One Window

Running an Application on Mac OS X with the X Window System

Prior to VR Juggler 2.2, using VR Juggler on Mac OS X required the use of the X Window System. VR Juggler 2.2 and beyond support native Cocoa windows, but the X Window System support still exists for those who want to use it (though it is not recommended). This section describes how to run VR Juggler applications on Mac OS X with the X Window System for people who may need to know about this usage. The average Mac OS X user can skip this section since Cocoa will be used instead.

Important

The only way to get full-screen VR juggler windows on Mac OS X is to use the Cocoa windows. If nothing else, this is the biggest single reason not to use the X11 window support on Mac OS X.

Running a VR Juggler application on Mac OS X is slightly different if VR Juggler was compiled against X11 for OS X. Before starting the VR Juggler application, X11 must be running. This can be accomplished by double-clicking on the X11 icon in the Applications folder. By default, X11 will open a standard xterm when it starts. In this xterm, the DISPLAY environment variable will be set correctly, and it is recommended that VR Juggler applications be launched from this xterm. From this xterm, set the necessary environment variables as described earlier in the section called “Relevant Environment Variables”. Once this is done, the application can be executed from the command line just as described in the previous section.

The X11 version of MPApp is shown executing on a Mac OS X desktop in Figure 5.6, “MPApp Running on Mac OS X Using X11 with One Window”. Note that in the Dock, the X11 icon is activated and that the application menu is for an X11 application. This truly is an X11 application running on OS X.

Figure 5.6. MPApp Running on Mac OS X Using X11 with One Window

So now you are probably wondering what you can do with this fancy application. Both of the preceding configurations use the same keyboard/mouse mappings; they vary only in which windows accept the keyboard and mouse input. Using the multi-window configuration, head movement is done with the keyboard in “Head Keyboard”; camera movement is done with the keyboard in “Sim View Cameras Control”; and wand movement is done with the keyboard and mouse in “Wand Keyboard”. Using the single-window configuration, all input is done with the keyboard and mouse in “Sim Window”. Note, however, that for the single-window configuration, the camera is attached to the user's head for an over-the-shoulder view, and hence, it does not move separately from the head. For information on how to verify these settings and to view the current configuration, refer to the VRJConfig Guide. The following list of tables provides all the keyboard and mouse controls for the simulator when using these particular configuration files. Note that it is possible to reconfigure the simulator to suit your preferences. This is provided mainly for those who just want something that works now.

Before continuing on to running an application in a full-scale VR system, we provide two asides: using a simulated glove and using a simulated analog device. The examples provided thus far have not discussed this because the information was not relevant to the particular sample application being used. Knowing how to use these simulated devices is important, however, and it is treated separately as a reference for your future endeavors in running VR Juggler applications.

If you include the sim.glove.mixin.jconf file, your application will also have access to a simulated glove, with position and gesture inputs. The glove is controlled by a window titled “Glove Keyboard”. This window lets you control the glove position and selected gesture. Movement control of the glove uses the mouse and is the same as that of the wand. The mouse buttons are used to select gestures. The mapping of the gesture numbers to actual hand positions is controlled by the “training file” for the simulated glove device. The default training file is $VJ_DATA_DIR/data/gesture/simpleSimGestures.dat.

If you include the sim.analog.wandmixin.jconf file, your application will also have access to a set of four analog devices (devices with a value in a range from 0.0 to 1.0). The analog devices are also controlled using the “Wand Keyboard” window which means that their configuration file requires the wand configuration file.

The key presses used for controlling the analog devices are listed in Table 5.4, “Analog Device Simulator Keys”.

The example configuration files in the directory $VJ_DATA_DIR/data/configFiles modeled after those used for VRAC's Onyx-powered C4 system are as follows:

Running the application is the same as with a simulator configuration except that the configuration files given on the command line are different. For example, to run MPApp in the C4 with stereoscopic graphics, the following command would be used:

% MPApp C4.closed.jconf

On Mac OS X, the following command would be used:

% MPApp.app/Contents/MacOS/MPApp C4.closed.jconf

Clusters involve multiple machines, and running VR Juggler on a cluster means running the application on every node of that cluster. Every node must load the same configuration whether it is defined in multiple files or in a single file. VR Juggler (more specifically, Gadgeteer) sorts out which parts of the configuration apply to each node^[3].

The way that any given cluster-ready VR Juggler application works is up to the people who created the application. The sample applications that come with VR Juggler all work the same way. Namely, the same application is run on every node with the same set of command line options. Other applications may use varying command line options depending on the role of the node in the cluster, or different applications may be run on each node, again depending on the role of the node.

For MPApp, the usage on a cluster is the same as what we have shown previously. The only things that change are the configuration files that are loaded and the execution of the MPApp binary on all nodes of the cluster. If we were to use the example configuration ptah.cluster.jconf, the usage on all nodes would be as follows:

% MPApp ptah.cluster.jconf

On Mac OS X, the following command would be used:

% MPApp.app/Contents/MacOS/MPApp ptah.cluster.jconf