Table of Contents
List of Figures
- 1.1. Windows Folder View of ZIP File
- 1.2. Open WinZip Window
- 1.3. WinZip Extract Dialog
- 2.1. Windows 2000 System Properties Dialog
- 2.2. Windows XP System Properties Dialog
- 2.3. Windows Environment Variable Editor Dialog
- 2.4. Setting VJ_BASE_DIR on Windows
- 4.1. Selecting the Visual C++ Project File
- 4.2. MPApp Project
- 4.3. Project Menu
- 4.4. Build MPApp.exe
- 5.1. MPApp running on a Linux desktop with multiple input windows
- 5.2. MPApp running on a Linux desktop with one window
- 5.3. Setting Command Arguments
- 5.4. Execute MPApp.exe
- 5.5. MPApp running on Mac OS X using X11 with one window
List of Tables
This book is for people who are just getting started with VR Juggler. It guides new users through getting and installing VR Juggler, configuring users' environment to use it, and compiling and running a sample application.
The prerequisites for reading this book are minimal. They are:
Some experience with a command-line interface (i.e., a shell such as tcsh or the DOS shell)
Creating and browsing directories
Those users who want to get more involved with VR Juggler to do more than just run applications should be aware right away of the following prerequisites:
Knowledge of C++ and object-oriented design
Knowledge of one of VR Juggler's currently supported graphics APIs (OpenGL, OpenGL Performer, OpenSG, or Open Scene Graph)
As with most Open Source projects, VR Juggler is distributed as compressed archive files using popular formats. Installing a distribution requires very little effort, but you do need to know how to use archiving utilities to extract the installation tree. Automation of the installation is a goal of the VR Juggler team, but we are still finalizing the details of cross-platform installation management. Before reading further, you should know where you want to install VR Juggler, and you should make sure that you have access to write to that directory.
The TAR (Tape ARchive) format has been around for a long, long time in the UNIX world. It is simply a collection of files in a directory tree that are lumped into a single file suitable for writing to a tape or for downloading. The format is a standard, and the tar(1) utility is available on every UNIX-based platform and on Win32. A free version can be downloaded from the GNU Project. A compressed TAR file is made for each VR Juggler distribution, and some distributions come in other formats as well. You can always count on the availability of a TAR file, though. The TAR files are compressed using either GZIP or BZIP2, both of which are standard compression formats. The gzip(1) utility is freely available from the GNU Project, and the bzip2(1) utility can be downloaded for free from RedHat, Inc.. The GNU version of TAR has the GZIP and BZIP2 algorithms built in. The compression algorithm used can be determined by the file extension. Files compressed with GZIP end in .gz; files compressed with BZIP2 end in .bz2.
Once you have downloaded a VR Juggler TAR distribution, you can unpack it one of two ways depending on what your platform's version of TAR supports. Before extracting the installation tree, make sure that your current directory is the one where you want to install VR Juggler. If your version of TAR does not have GZIP built in (it does not support the -z option), the following command will do the decompression and extraction:
% gzip -cd vrjuggler-distribution.tar.gz | tar -xvf -
For versions of TAR without built-in BZIP2 support (there is no -j option) the command is similar:
% bzip2 -cd vrjuggler-distribution.tar.bz2 | tar -xvf -
Here, you should fill in vrjuggler-distribution.tar.gz (or vrjuggler-distribution.tar.bz2) with the name of the VR Juggler distribution file you downloaded. The above commands will work with any shell that supports redirection of standard output to a pipe. If that looks too scary, you can separate the decompression and extraction into two commands (for GZIP):
% gunzip vrjuggler-distribution.tar.gz % tar -xvf vrjuggler-distribution.tar
or for BZIP2:
% bunzip2 vrjuggler-distribution.tar.bz2 % tar -xvf vrjuggler-distribution.tar
Note that the distribution file in the second command does not have the .gz extension after gzip(1) is run. These steps also work if your version of tar(1) supports the -z option (-j for BZIP2), but you can simplify your work if that option is supported. The following illustrates how to decompress and extract a TAR file compressed with GZIP all in one step:
% tar -xzvf vrjuggler-distribution.tar.gz
The following would be used for a TAR file compressed with BZIP2:
% tar -xjvf vrjuggler-distribution.tar.bz2
In either case, while the command runs, you will see the name of each file as it is written to disk. This is because of the -v option to tar(1) that tells it to be verbose in its efforts. tar(1) takes care of creating all the directories in the installation tree, so you only need to have the base directory (for example, /usr/local) when you start. For more information about these utilities, please refer to the tar(1) and gzip(1) manual pages.
On the Win32 family of platforms, the ZIP format rules. In the old days, you would use the PKZIP utility to uncompress and extract a ZIP file. Nowadays, most people use WinZip or some other comparable graphical interface. This documentation covers only the use of WinZip when extracting a ZIP file.
Once you have downloaded the VR Juggler ZIP file, the easiest way to extract it is to double-click on its icon in the open folder window as shown in Figure 1.1, “Windows Folder View of ZIP File”.
Double-clicking opens the main WinZip window, as shown in Figure 1.2, “Open WinZip Window”.
Note that in this screen shot, the button is highlighted. Click this button to open the following window. Note that in this screen shot, the button is highlighted. Click this button to open the dialog box shown in Figure 1.3, “WinZip Extract Dialog”.
In this window, choose the directory where VR Juggler will be installed and click . WinZip will then proceed to extract the ZIP file into the directory you named. That is all there is to it.
Table of Contents
There are several environment variables that affect the way VR Juggler works. Some of these are required to compile and run applications while others are optional. This chapter lists all such variables and explains their meanings and uses.
The syntax for setting or changing an environment variable varies with operating systems and shell interpreters. Instead of choosing one style of syntax that is specific to a particular shell type, we define our own syntax which you must then translate to your shell's specific syntax. Before defining this syntax, we present the method used to set environment variables in the three most common types of shells. We also provide a quick overview of how to set environment variables using Win32-based GUIs.
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 Win32 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 Win32 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”.
In the Control Panel, open the System icon. Under the Advanced tab, there is a button labeled , 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.
To set up VR Juggler, the environment variable VJ_BASE_DIR needs to be set, probably for all users, though it depends very much on local system requirements. For this example, let us say that the Win32 version of VR Juggler is installed in the D:\ directory. As such, we will set VJ_BASE_DIR as shown in Figure 2.4, “Setting VJ_BASE_DIR on Windows”. VJ_DEPS_DIR is set similarly.
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.
When naming an environment variable in the plain text of this document, the variable will be referred to by its name only. For example, to talk about the environment variable containing your path, we will talk about it as PATH.
The syntax to set an environment variable is:
% <VARIABLE_NAME> = <value>
Setting an environment variable also creates it if it is not already present in the current shell's environment.
Printing an environment variable's value to standard output (stdout) is done as follows:
% echo $VARIABLE_NAME value
- VJ_BASE_DIR
The environment variable VJ_BASE_DIR tells a VR Juggler application where to find important data files. It is required to compile and run any Juggler application. It should be set to the base directory of the installed VR Juggler library. For example, if you downloaded a UNIX version of VR Juggler 2.0 and extracted it to the directory /home/software, you would set VJ_BASE_DIR with this command:
% VJ_BASE_DIR = /home/software/vrjuggler-2.0
The last component of the path depends on the particular version of Juggler you have downloaded.
If you downloaded and built VR Juggler from the source code, the compilation creates a directory called instlinks which can be used as a VR Juggler base:
% VJ_BASE_DIR = $HOME/juggler/my_build_dir/instlinks
- VJ_DEPS_DIR
This variable provides the path to the complete set of bundled VR Juggler dependencies (Boost, CppDOM, OpenAL, etc.). It is used by scripts such as vrjuggler-config and by the Visual C++ project files that come with the sample applications. If you downloaded the dependencies as a separate package, set this environment variable to the path where that package was installed. If the dependencies are bundled in the same tree as VR Juggler, then this environment variable does not have to be set.
- PATH
To compile any of the sample applications, the $VJ_BASE_DIR/bin directory must be added to your PATH as follows:
% PATH = $PATH:$VJ_BASE_DIR/bin
Depending on your shell, you may need to run the rehash command after executing the above.
Windows users must also include the directories $VJ_DEPS_DIR/bin, $VJ_DEPS_DIR/lib, and $VJ_BASE_DIR/lib in their PATH setting. This is so that the DLLs for VR Juggler and its dependencies will be found when an application is executed.
- JDK_HOME
The JDK_HOME environment variable is required by the script that starts VRJConfig, the VR Juggler configuration program. If Java is installed on your system, JDK_HOME may already be set. If not, it needs to be set to the base of the Java installation.
- LD_LIBRARY_PATH (UNIX/Linux only), DYLD_LIBRARY_PATH (Darwin/Mac OS X only), LD_LIBRARYN32_PATH (IRIX only), LD_LIBRARY64_PATH (IRIX only)
UNIX/Linux systems use these environment variables to find dynamically loaded libraries, such as libvrj.so. Unless you are building everything with static libraries, you will need to set these to include the VR Juggler library directory (under VJ_BASE_DIR). IRIX supports several Application Binary Interfaces (ABIs). VR Juggler supports only the N32 and 64 formats, and there are different library path variables for each. The N32 ABI uses the LD_LIBRARYN32_PATH variable, and the 64 ABI uses LD_LIBRARY64_PATH. An example of setting the library path is as follows:
% LD_LIBRARY_PATH = $VJ_BASE_DIR/lib
If you have VJ_DEPS_DIR set and it is not the same as VJ_BASE_DIR, then $VJ_DEPS_DIR/lib also needs to be in LD_LIBRARY_PATH.
Note
On some SGI systems running IRIX, users of the MIPSpro Compilers (version 7.3) may need to add another directory as follows:
% LD_LIBRARY_PATH = $LD_LIBRARY_PATH:/usr/lib32/cmplrs:$VJ_BASE_DIR/lib32
- VJ_CFG_PATH
This variable provides a search path for looking up configuration files. It lists one or more directories where VR Juggler configuration files may be found. At run time, this path will be used to find configuration files that are not named using absolute paths. This variable is set using a platform-specific format. On Windows, DOS paths should be used, and they must be separated by the semi-colon (;) character. On UNIX variants and Mac OS X, the paths should be separated by the colon (:) character. This is exactly the way that the $PATH environment variable would be set on all of these platforms. If not set, the default search path for configuration files is $VJ_BASE_DIR/share/vrjuggler/data/configFiles.
Note
The configuration files are loaded by the module JCCL, and it will recognize the environment variable JCCL_CFG_PATH. If JCCL_CFG_PATH is set, it takes precedence over VJ_CFG_PATH.
- JCCL_DEFINITION_PATH
This variable provides the search path for JCCL definition files (those files with the extension .jdef). It is set using a platform-specific format. On Windows, DOS paths should be used, and they must be separated by the semi-colon (;) character. On UNIX variants and Mac OS X, the paths should be separated by the colon (:) character. This is exactly the way that the PATH environment variable would be set on these platforms. If not set, the default search path for configuration files is $VJ_BASE_DIR/share/vrjuggler/data/definitions.
- SNX_BASE_DIR
The environment variable that defines the root directory of a Sonix installation. At run time, Sonix uses this variable to search for plug-ins. If it is not set, Sonix plug-in loading may fail. In genereal, it will be set to the same value as VJ_BASE_DIR.
- VPR_DEBUG_NFY_LEVEL
This variable can be used to control the amount of diagnostic information a VR Juggler application outputs. Its value is a number between 0 (only very important messages are printed) and 7 (vast amounts of data) inclusive. Non-hackers are advised to use levels 0 through 3, as higher debug levels become increasingly cryptic and can severely impact application performance. The default is level 1—only errors and critical information are output. An example of setting a value for this variable is:
% VPR_DEBUG_NFY_LEVEL = 3
- VPR_DEBUG_ALLOW_CATEGORIES
This variable can be used to control which components of VR Juggler are allowed to output diagnostic data. If for some reason you set VPR_DEBUG_NFY_LEVEL to 5 or higher, this variable can be used to filter the output. The value of VPR_DEBUG_CATEGORIES is a space-separated list of Juggler debug component names (defined in $VJ_BASE_DIR/include/vrj/Util/Debug.h, $VJ_BASE_DIR/include/vpr/Util/Debug.h, $VJ_BASE_DIR/include/tweek/Util/Debug.h, $VJ_BASE_DIR/include/jccl/Util/Debug.h, and $VJ_BASE_DIR/include/gadget/Util/Debug.h). The default value is “DBG_ALL”, which performs no filtering whatsoever. Examples of setting it are as follows:
% VPR_DEBUG_ALLOW_CATEGORIES = DBG_ERROR % VPR_DEBUG_ALLOW_CATEGORIES = "DBG_KERNEL DBG_INPUT_MGR DBG_DRAW_MGR" % VPR_DEBUG_ALLOW_CATEGORIES = "DBG_CONFIG DBG_RECONFIGURATION"
- VPR_DEBUG_DISALLOW_CATEGORIES
This variable is basically the opposite of VPR_DEBUG_ALLOW_CATEGORIES. Instead of specifying which debugging categories you want to see, you specify which ones you do not want to see. Its default value is empty which means that no debugging categories are excluded. Examples of setting it are as follows:
% VPR_DEBUG_DISALLOW_CATEGORIES = DBG_ERROR % VPR_DEBUG_DISALLOW_CATEGORIES = "DBG_KERNEL DBG_INPUT_MGR DBG_DRAW_MGR" % VPR_DEBUG_DISALLOW_CATEGORIES = "DBG_CONFIG DBG_RECONFIGURATION"
Table of Contents
VR Juggler comes with several sample applications in its samples directory tree. Many of them are very simple and are designed to demonstrate a specific feature of VR Juggler or a technique to use when writing your own applications. This chapter lists the current sample applications as of this writing and gives a quick description of what you as a potential developer might find interesting in the code. Those users who just want to run applications can safely skip this chapter.
Some sample applications designed for getting started with VR Juggler are found in $VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple. All of these applications were designed to be used as part of courses teaching people how to write VR Juggler applications using OpenGL. They contain clear comments explaining what the code is doing, and they are intended to be as simple as possible. These tutorials are as follows:
simpleInput: An application that demonstrates how to get input from devices. No graphics are rendered with this application. It is intended to be a starting point for getting an understanding of how user input is queried.
SimpleApp: A very simple OpenGL application that draws a small cube in space and draws the coordinate axes for the cube.
contextApp: An application demonstrating how to use OpenGL display lists in VR Juggler applications. This extends SimpleApp by using a display list to draw a cube and by moving the cube with the wand.
ConfigApp: A relatively simple application that demonstrates how user-level code can take advantage of the VR Juggler configuration system, JCCL.
MPApp: A more complex OpenGL application that demonstrates how to do multi-processing in VR Juggler applications. As it exists in its distributed form, no multi-processing is done. A more detailed lesson is available that explains how to extend the application to employ multi-processing techniques.
For a step-by-step lesson how to use these applications to learn VR Juggler application programming, please refer to the Programmer's Guide. It contains sections explaining each of the above applications in great detail. Each lesson ends with an exercise where the reader extends the application to include some new functionality.
Examples of OpenGL Performer applications can be found in $VJ_BASE_DIR/share/vrjuggler/samples/Pf/advanced. These are for more advanced developers who are familiar with Performer and some of the more complicated aspects of VR Juggler. There are two main programs to be found there:
pfNav: A starting point for basic VR Juggler Performer applications that need to load a model and navigate through it. Users implement their application by inheriting from a provided class, simplePfNav. This may be a good place for intermediate-level users of OpenGL Performer to start because simplePfNav hides many of the complicated details (which actually makes that class far from simple).
pfConfigNav: A more advanced example of a VR Juggler Performer application that can be given its model through a VR Juggler configuration element.
Table of Contents
Now that you have VR Juggler installed and you have your environment all configured, it is time for the fun to begin. No, seriously. You are now ready to compile and run VR Juggler applications, and that is the whole point, right? This chapter explains how to compile the applications provided in the directory $VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple.
Before reading any further, make sure you have already read the instructions on how to install VR Juggler (in Chapter 1, Installing VR Juggler) and on how to configure your environment (in Chapter 2, Environment Variables). That information will not be repeated, and it is assumed that you already know what we mean by VJ_BASE_DIR. You should also have a basic understanding of how make(1) works, but in these examples, nothing more will be necessary than typing make on the command line. Refer to the make(1) manual page for more information about it.
There are two ways to compile VR Juggler applications: from the command line or with Microsoft Visual Studio. Compiling an application on the command line requires the use of GNU make (often installed as gmake) so that it will work on all supported platforms including Win32. Using Microsoft Visual Studio will only work on Win32.
All the sample programs in $VJ_BASE_DIR/share/vrjuggler/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_BASE_DIR/share/vrjuggler/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_BASE_DIR/share/vrjuggler/samples/OGL/simple/MPApp in a command shell.
To compile MPApp, simply enter the following:
% gmake
The compile process will then begin. As noted above, the use of GNU make is required to use the distributed makefiles. With Cygwin, GNU make is simply make. If you have your system set up properly, it will complete with an executable MPApp file (or MPApp.exe on Win32) in the directory. 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.)
Note
Remember that the Netscape Portable Runtime (NSPR) is required to use VR Juggler on Windows. Its DLL directory must be in your path (via the PATH environment variable) for proper application execution. The NSPR can be downloaded from the NSPR home page. If the pre-compiled VR Juggler dependencies are installed, then NSPR is already available.
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.
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.
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 item from the popup 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 menu, choose the 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.
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.
Table of Contents
It is important to note that the same VR Juggler application can be run in simulator mode or in a full-scale VR system with no modifications. What does change is the configuration files used when starting the program. In $VJ_BASE_DIR/share/vrjuggler/data/configFiles, you can find many basic configuration files including those for running in simulator using a mouse and keyboard to simulate VR input devices and some example files based on those used for the VRAC C4 system. In the directory, you will see some files with names containing “mixin”. These are special files that provide a specific capability not necessarily needed by all applications. They can be mixed in (hence the name) with other configuration files as needed. The configuration files found in the configFiles directory will be referenced in the examples provided, so be sure you know where they are.
Before reading any further, make sure you have already read the instructions on how to install VR Juggler (see Chapter 1, Installing VR Juggler) and on how to configure your environment (see Chapter 2, Environment Variables). That information will not be repeated, and it is assumed that you already know what we mean by VJ_BASE_DIR and LD_LIBRARY_PATH, to name two environment variables. At this point, it is also assumed that you already have compiled an application (MPApp in the case of the examples provided), so you should be sure to have read about how to compile a sample VR Juggler application (in Chapter 4, Compiling a VR Juggler Sample Program) before proceeding.
Running in “simulator mode” means that your input is simulated and your display windows may have limited functionality. (By “simulated input”, we mean that input is provided through windows that take keyboard and mouse input and translate that into transformations in the virtual world.) Simulator viewports are limited primarily in that they cannot display stereo graphics. It is important to note that a simulator viewport is a special kind of VR Juggler viewport within a display window. Instead of basing its viewpoint on the head position of one of the users, the viewpoint is controlled by a separate camera that is just another positional device. Within a simulator viewport, VR Juggler draws certain objects to help visualize the environment. For example, the heads of users are represented as blue ellipsoids with gray eyes, and a wand (if present) is drawn as a green pointing device. Besides these common simulator objects, display surfaces can be drawn. These represent projection screens or HMD viewing projections and are drawn as translucent rectangles.
As mentioned, several simulator configuration files are provided with a VR Juggler distribution. These files provide a complete simulation of an immersive environment. Please note that this documentation reflects the state of the configuration files at the time the documentation was written. For more information about the configuration files and how to view or modify the configuration, refer to the VRJConfig Guide. (Using VRJConfig is the best way to find out how a specific configuration file is set up.) The configuration files of interest for simulator mode are as follows:
sim.base.jconf - The basic configuration file needed by all applications when run in simulator mode. It defines commonly used VR Juggler concepts that are beyond the scope of this particular book. It also defines simulated head movement using the keyboard. For now, it is sufficient to know that it is required to run the sample applications in simulator mode.
This file also contains the basic simulator display configuration file needed by all applications when run in simulator mode. It defines the display windows where the rendering magic occurs. Two simulator display windows are configured by this file: a small one that is active by default and a larger one that is inactive initially.
sim.analog.wandmixin.jconf - A “mix-in” configuration file that defines simulated analog input using the keyboard. This is only required for applications where analog input is used and needs to be simulated when in simulator mode.
sim.analog.mixin.jconf - This version of the analog simulator opens its own window. See the previous file (sim.analog.wandmixin.jconf) for other details.
sim.c6displays.mixin.jconf - A “mix-in” configuration file that defines the surface displays of VRAC's C6. This is not required for any application but can be used to test opening multiple display windows (each containing either a surface or a simulator viewport) before running in a multi-screen VR system.
sim.digital.glove.mixin.jconf - A “mix-in” configuration file that defines simulated digital glove input using the keyboard. This is only required for applications where digital glove input is used and needs to be simulated when in simulator mode.
sim.glove.mixin.jconf - A “mix-in” configuration file that defines simulated gesture-based glove input using the keyboard. This is only required for applications where gesture-based glove input is used and needs to be simulated when in simulator mode.
sim.wand.mixin.jconf - A “mix-in” configuration file that defines simulated wand input using the mouse. This is only required for applications where wand input is used and needs to be simulated when in simulator mode.
standalone.jconf - A configuration file that stands on its own and combines the functionality of sim.base.jconf and sim.wand.mixin.jconf. Note that it uses a single display window for all input.
Note
At the time of this writing, this configuration file only works with OpenGL, OpenSG, and Open Scene Graph applications on UNIX, Win32, and Mac OS X. It will not work with OpenGL Performer.
For the MPApp application, we need the base configuration file and the wand mix-in configuration file.
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
You will 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. 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/.vjconfig. The environment variable VJ_CFG_PATH is useful in providing a search path for finding your configuration files. (Refer to the section called “Optional Related 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 RedHat 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”.
With VR Juggler 1.1/2.0, 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
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.
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.
With the application already compiled, execute the MPApp program by choosing the item from the menu, shown below in Figure 5.4, “Execute MPApp.exe”.
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 “Required Environment Variables”. Once this is done, the application can be executed from the command line just as described in the previous section.
MPApp is shown executing on a Mac OS X desktop in Figure 5.5, “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.
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.
Table 5.1. Moving the simulated head
| Transformation | Key Press |
|---|---|
| Move head backward | 2 on keypad |
| Move head left | 4 on keypad |
| Move head right | 6 on keypad |
| Move head forward | 8 on keypad |
| Move head down | 7 on keypad |
| Move head up | 9 on keypad |
| Turn head up | CTRL+2 on keypad |
| Turn head left | CTRL+4 on keypad |
| Turn head right | CTRL+6 on keypad |
| Turn head down | CTRL+8 on keypad |
| Rotate head clockwise | 1 on keypad |
| Rotate head counter-clockwise | 3 on keypad |
Table 5.2. Moving the simulated wand
| Transformation | Mouse Input/Key Press |
|---|---|
| Move wand backward | ALT+move mouse backward |
| Move wand forward | ALT+move mouse forward |
| Move wand left | CTRL+move mouse left |
| Move wand right | CTRL+move mouse right |
| Move wand up | CTRL+move mouse forward |
| Move wand down | CTRL+move mouse backward |
| Rotate wand left | SHIFT+move mouse left |
| Rotate wand right | SHIFT+move mouse right |
| Rotate wand up | SHIFT+move mouse backward |
| Rotate wand down | SHIFT+move mouse forward |
| Rotate wand clockwise | Right arrow |
| Rotate wand counter-clockwise | Left arrow |
| Wand button #1 | Left mouse button |
| Wand button #2 | Middle mouse button |
| Wand button #3 | Right mouse button |
| Wand button #4 | 4 |
| Wand button #5 | 5 |
| Wand button #6 | 6 |
Table 5.3. Moving the camera (multi-window configuration only)
| Transformation | Key Press |
|---|---|
| Move camera backward | 2 on keypad |
| Move camera left | 4 on keypad |
| Move camera right | 6 on keypad |
| Move camera forward | 8 on keypad |
| Move camera down | 7 on keypad |
| Move camera up | 9 on keypad |
| Turn camera up | CTRL+2 on keypad |
| Turn camera left | CTRL+4 on keypad |
| Turn camera right | CTRL+6 on keypad |
| Turn camera down | CTRL+8 on keypad |
| Rotate camera clockwise | 1 on keypad |
| Rotate camera counter-clockwise | 3 on keypad |
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 sim glove. The default training file is $VJ_BASE_DIR/share/vrjuggler/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.
Note
A separate file, sim.analog.mixin.jconf, is provided for analog input from a separate simulator window.
The key presses used for controlling the analog devices are listed in Table 5.4, “Analog Device Simulator Keys”.
Running an application full-scale in a VR system is more complicated than running in simulator mode. The reason for this is that VR systems tend to differ in configuration and in available hardware. VR Juggler is flexible enough to handle most any configuration you throw at it, but those configurations need to be put together first. Examples of configuration files used in VRAC's C4 system are provided, and they are used in this documentation. It should be noted, however, that for any particular system, custom configuration files will probably have to be written. The idea behind this section is to provide a basic understanding of what is needed to get started with running in a VR system.
The example configuration files in the directory $VJ_BASE_DIR/share/vrjuggler/data/configFiles modeled after those used for VRAC's C4 system are as follows:
C4.closed.jconf - The single configuration file that includes the other configuration files necessary for loading a VR Juggler application in the C4 in its closed configuration with full tracking and stereoscopic graphics.
C4.closed.mono.jconf - The single configuration file that includes the other configuration files necessary for loading a VR Juggler application in the C4 in its closed configuration with full tracking and monoscopic graphics.
C4.base.jconf - The basic configuration file needed by all applications when run in the C4. It defines commonly used VR Juggler concepts that are beyond the scope of this particular book.
C4.displays.closed.jconf - The basic display configuration file needed to run with all four walls active and rendering stereoscopic graphics. This defines only the four surface displays to be opened. The corners are configured for the closed position of the moveable walls.
C4.displays.closed.mono.jconf - The basic display configuration file needed to run with all four walls active and rendering monoscopic graphics. This defines only the four surface displays to be opened. The corners are configured for the closed position of the moveable walls.
C4.mstar.jconf - The Ascension MotionStar configuration file that defines which bird provides input for the head and for the wand.
C4.rfwand.jconf - The radio frequency wireless mouse that acts as a wand.
Running the application is the same as in simulator mode 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