To get the most from this chapter, there are a few prerequisites:

For some of the advanced sections of this book, it is recommended that readers review the VR Juggler architecture book. This is optional, though it may be helpful in gaining a quicker understanding of some topics and concepts.

Readers who already have experience with other VR software development environments can easily skim through this book and find the relevant new information. The book is designed for easy skimming. Simply look at the headings to get a good determination of what should be read and what may be skipped.

This book is organized into three main parts:

Since VR Juggler applications are objects, developers do not write the traditional main() function. Instead, developers create an application object that implements a set of pre-defined interfaces. The VR Juggler kernel controls the application's processing time by calling the object's interface implementation methods.

In traditional programs, the main() function defines the point where the thread of control enters the application. After the main() function is called, the application starts performing any necessary processing. When the operating system (OS) starts the program, it gives the main() function some unit of processing time. After the time unit (quantum) for the process expires, the OS performs what is called a “context switch” to change control to another process. VR Juggler achieves similar functionality but in a slightly different manner.

The application objects correspond to processes in a normal OS. The kernel is the scheduler, and it allocates time to an application by invoking the methods of the application object. Because the kernel has additional information about the resources needed by the applications, it maintains a very strict schedule to define when the application is granted processing time. This is the basis to maintain coherence across the system.

The first step in defining an application object is to implement the basic interfaces defined by the kernel and the Draw Managers. There is a base class for the interface that the kernel expects (vrj::App) and a base class handled by each Draw Manager interface (vrj::pf::App, vrj::opengl::App, etc.). See Figure 2.1. vrj::App hierarchy for a visual representation of the complete application interface hierarchy. The interface defined in vrj::App specifies methods for initialization, shutdown, and execution of the application. This is the abstract type that is seen by the VR Juggler kernel. The Draw Manager interfaces specified in the vrj::*App classes define the API-specific functions necessary to render the virtual environment. For example, an interface used by a Draw Manager could have functions for drawing the scene and for initializing context-specific information.

Figure 2.1. vrj::App hierarchy

To implement an application in VR Juggler, developers simply need to “fill in the blanks” of the appropriate interfaces. To simplify this process, there are default implementations of most methods in the interfaces. Hence, the user must only provide implementations for the aspects they want to customize. If an implementation is not provided in the user application object, the default is used, but it is important to know that in most cases, the default implementation does nothing.

As a virtual platform, VR Juggler does not use the model described above because VR Juggler needs to maintain control of the system components. This control is necessary to make changes to the virtual platform at run time. As the controller of the execution, the kernel always knows the current state of the applications, and therefore, it can manage the run-time reconfigurations of the virtual environment safely. With run-time reconfiguration, it is possible to switch applications, start new devices, reconfigure running devices, and send reconfiguration information to the application object.

Application objects lead to a robust architecture as a result of low coupling and well-defined inter-object dependencies. The application interface defines the only communication path between the application and the virtual platform, and this allows restriction of inter-object dependencies. This decreased coupling allows changes in the system to be localized, and thus, changes to one object will not affect another unless the interface itself is changed. The result is code that is more robust and more extensible.

Because the application is simply an object, it is possibly to load and unload applications dynamically. When the virtual platform initializes, it waits for an application to be passed to it. When the application is given to the VR Juggler kernel at run time, the kernel performs a few initialization steps and then executes the application.

Since applications use a distinct interface to communicate with the virtual platform, changes to the implementation of the virtual platform do not affect the application. Changes could include bug fixes, performance tuning, or new device support.

By treating applications as objects, we can mix programming languages in the VR Juggler kernel. For example, an application object could be written in Python, C#, or even VB.NET, but the VR Juggler kernel (written in standard C++) will still see it as an instance of the abstract interface vrj::App. The use of application objects has allowed such extensions to VR Juggler to be written without requiring any changes to VR Juggler.

Previously, we explained how VR Juggler applications do not have a main() function, but further explanation is required. While it is true that user applications do not have a main() function because they are objects, there must still be a main() somewhere that starts the system. This is because the operating system uses main() as the starting point for all applications. In typical VR Juggler applications, there is a main(), but it only starts the VR Juggler kernel and gives the kernel the application to run. It then waits for the kernel to shut down before exiting.

The following is a typical example of a main() function that will start the VR Juggler kernel and hand it an instance of a user application object. The specifics of what is happening in this code are described below.

  1 #include <vrj/Kernel/Kernel.h>
    #include <simpleApp.h>
    
    int main(int argc, char* argv[])
  5 {                                                                         
       vrj::Kernel* kernel = vrj::Kernel::instance(); // Get the kernel       
       simpleApp app;                                 // Create the app object
                                                                              
       kernel->init(argc, argv);                // Process command line options
 10    kernel->loadConfigFile(...);             // Configure the kernel       
       kernel->start();                         // Start the kernel thread
       kernel->setApplication(&app);            // Give application to kernel
       kernel->waitForKernelStop();             // Block until kernel stops
    
 15    return 0;
    }

VR Juggler 2.2 introduces support for Cocoa on Mac OS X. Cocoa itself is quite different than the X11 or Win32 APIs as far as restrictions on threading and the implementation of the main() function. The fundamental issue, however, is that both the NSApplication singleton object and the vrj::Kernel singleton object want to be in charge of application execution. A balance has been struck that generally allows VR Juggler applications to look and act the same on Mac OS X as on any other platform while still taking advantage of unique features that Cocoa and Mac OS X have to offer.

  1 @include <iostream>
    #include <cstdlib>
    #include <vrj/Kernel/Kernel.h>
    #include <simpleApp.h>
  5 
    int main(int argc, char* argv[])
    {
       if ( argc <= 1 )
       {
 10       std::cout << "Usage: " << argv[0]
                    << "cfgfile[0] cfgfile[1] ... cfgfile[n]"
                    << std::endl;
          std::exit(EXIT_FAILURE);
       }
 15 
       vrj::Kernel* kernel = vrj::Kernel::instance(); // Get the kernel
       simpleApp app;                                 // Create the app object
    
       kernel->init(argc, argv);                // Process command line options
 20    kernel->loadConfigFile(...);             // Configure the kernel
       kernel->start();                         // Start the kernel thread
       kernel->setApplication(&app);            // Give application to kernel
       kernel->waitForKernelStop();             // Block until kernel stops
    
 25    return 0;
    }

  1 @include <iostream>
    #include <cstdlib>
    #include <vrj/Kernel/Kernel.h>
    #include <simpleApp.h>
  5 
    int main(int argc, char* argv[])
    {
    #if ! defined(VRJ_USE_COCOA)
       if ( argc <= 1 )
 10    {
          std::cout << "Usage: " << argv[0]
                    << "cfgfile[0] cfgfile[1] ... cfgfile[n]"
                    << std::endl;
          std::exit(EXIT_FAILURE);
 15    }
    #endif
    
       vrj::Kernel* kernel = vrj::Kernel::instance(); // Get the kernel
       simpleApp app;                                 // Create the app object
 20 
       kernel->init(argc, argv);                // Process command line options
    #if ! defined(VRJ_USE_COCOA)
       kernel->loadConfigFile(...);             // Configure the kernel
    #endif
 25    kernel->start();                         // Start the kernel thread
       kernel->setApplication(&app);            // Give application to kernel
       kernel->waitForKernelStop();             // Block until kernel stops
    
       return 0;
 30 }

  1 @include <iostream>
    #include <cstdlib>
    #include <vrj/Kernel/Kernel.h>
    #include <simpleApp.h>
  5 
    int main(int argc, char* argv[])
    {
    #if ! defined(VRJ_USE_COCOA)
       if ( argc <= 1 )
 10    {
          std::cout << "Usage: " << argv[0]
                    << "cfgfile[0] cfgfile[1] ... cfgfile[n]"
                    << std::endl;
          std::exit(EXIT_FAILURE);
 15    }
    #endif
    
       vrj::Kernel* kernel = vrj::Kernel::instance(); // Get the kernel
       simpleApp app;                                 // Create the app object
 20 
       kernel->init(argc, argv);                // Process command line options
       kernel->loadConfigFile(...);             // Configure the kernel
       kernel->start();                         // Start the kernel thread
       kernel->setApplication(&app);            // Give application to kernel
 25    kernel->waitForKernelStop();             // Block until kernel stops
    
       return 0;
    }

The VR Juggler kernel calls each of the methods in the application object based on a strictly scheduled frame of execution. The frame of execution is shown in Figure 2.2. Kernel loop sequence; it makes up all the lines within the “while(!quit)” clause.

During the frame of execution, the kernel calls the application methods and performs internal updates (the updateAllData() method call). Because the kernel has complete control over the frame, it can make changes at pre-defined “safe” times when the application is not doing any processing. At these times, the kernel can change the virtual platform configuration as long as the interface remains the same.

The frame of execution also serves as a framework for the application. That is, the application can expect that when preFrame() is called, the devices have just been updated. Applications can rely upon the system being in well-defined stages of the frame when the kernel invokes the application object's methods.

The following is a description of the application objects related to the initialization of a VR Juggler application. The order of presentation is the same as the order of execution when the application is executed by the kernel.

Once the application object has been initialized by the VR Juggler kernel, the kernel frame loop begins. Each frame, there are specific application object methods that are invoked, and understanding the timing and potential uses of these methods can improve the functionality of the immersive application. In some cases, it is possible to use these member functions to optimize the application to improve the frame rate and the level of interactivity.

float vrj::App::getDrawScaleFactor()
{
   return gadget::PositionUnitConversion::ConvertToFeet;
}

The OpenGL application base class adds several methods to the application interface that allow rendering of OpenGL graphics. The extensions to the base vrj::App class are shown in Figure 2.4. vrj::opengl::App interface extensions to vrj::App. In the following, we describe the method vrj::opengl::App::draw(), the most important element of the interface. More details about the vrj::opengl::App class are provided in OpenGL Applications, found in Chapter 4. Application Authoring Basics.

Figure 2.4. vrj::opengl::App interface extensions to vrj::App

The OpenGL Performer application base class adds interface functions that deal with the OpenGL Performer scene graph. Some of the interface extensions are shown in Figure 2.5. vrj::pf::App interface extensions to vrj::App. The following is a description of only two methods in the vrj::pf::App interface. More detailed discussion on this class is provided in OpenGL Performer Applications, found in Chapter 4. Application Authoring Basics.

Figure 2.5. vrj::pf::App interface extensions to vrj::App

The class gmtl::Vec<S, T> is designed to work the same way as a mathematical vector, typically of 3 or 4 dimensions. There are predefined vector types that would normally be used in a VR application that are provided for convenience. That is, a gmtl::Vec3f object can be thought of as a vector of the form <x, y, z>. Similarly, a gmtl::Vec4f can be thought of as a vector of the form <x, y, z, w>. An existing understanding of mathematical vectors is sufficient to know how these classes can be used. The question then becomes, how are they used? We will get to that later, and readers who have experience with vectors can skip ahead. If vectors are an unfamiliar topic, it may be convenient to think of these classes as three- and four-element C++ arrays of floats respectively. Most benefits of the vector concept are lost with that simpler idea, however. Therefore, if the reader needs to think of them as arrays, then arrays should probably be used until vectors feel more comfortable. Once the use of vectors seems familiar and straightforward, readers are encouraged to come back and read further.

Vectors are typically used to contain spatial data or something similar. For convenience, however, they can be visualized as a more general-purpose container for numerical data upon which well-defined operations can be performed. There is no need to constrain thinking of them as only holding the coordinates for some point in space or some other limited-scope use. The GMTL vectors use by VR Juggler retain this generality and can be used wherever vectors come in handy.

gmtl::Vec3f and gmtl::Vec4f, as specific implementations of mathematical vectors, hide vector operations on single-precision floating-point numbers (float) behind a simple-to-use interface. For a single vector, the following standard vector operations are available:

For two vectors, the following operations can be performed:

Using GMTL vectors should be straightforward if readers understand these operations and keep in mind that gmtl::Vec3f and gmtl::Vec4f can be thought of at this high level.

With an understanding of these classes as standard mathematical vectors, it is time to learn how to deal with them at the C++ level. In some cases, the mathematical operators are overloaded to simplify user code; in other cases, a named method must be invoked on an object. Before any of that, however, make sure that the source file includes the gmtl/Vec.h header file. From here on, the available operations are presented in the order they were listed in the previous section. We begin with creating the objects and setting their values.

Before doing anything with vectors, some must be created. The examples here use gmtl::Vec3f, but the example is equally applicable to gmtl::Vec4f. To create a gmtl::Vec3f, use the default constructor which initializes the vector to <0.0, 0.0, 0.0>:

gmtl::Vec3f vec1;

After creating the vector vec1, its elements can be assigned values all at once as follows:

vec1.set(1.0, 1.5, -1.0);

or individually:

vec1[0] = 1.0;
vec1[1] = 1.5;
vec1[2] = -1.0;

Note that in the last example, the individual elements of the vector can be accessed exactly as with a normal array. To do the above steps all at once when the vector is created, give the element values when declaring the vector:

gmtl::Vec3f vec1(1.0, 1.5, -1.0);

All of the above code has exactly the same results but accomplishes them in different ways. This flexibility is just one of the ways that GMTL vectors are more powerful than C++ arrays (of the same size, of course).

Once a vector is created, the simplest operation that can be performed on it is finding its inverse. The following code demonstrates just that:

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2;

vec2 = -vec1;

The vector vec2 now has the value <-1.0, -1.5, 1.0>. That is all there is to it. (Readers interested in details should note that the above does a copy operation to return the negative values.)

Normalizing a vector is another simple operation (at the interface level anyway). The following code normalizes a vector:

gmtl::Vec3f vec1(1.0, 1.5, -1.0);

gmtl::normalize( vec1 );

The vector vec1 is now normalized. Clean and simple.

Besides normalizing a given vector, a vector can be tested to determine if it has already been normalized. This is done as follows (assuming the vector vec has already been declared before this point):

if ( gmtl::isNormalized( vec1 ) )
{
   // Go here if vec is normalized
}

Part of normalizing a vector requires finding its length first. To get a vector's length, do the following:

gmtl::Vec3f vec1(1.0, 1.5, -1.0);
float length;

length = gmtl::length( vec1 );

In this case, length is assigned the value 2.061553 (or more accurately, the square root of 4.25). Finding the length of a vector appears simple from the programmer's perspective, but it has some hidden costs. Namely, it requires a square root calculation. For optimization purposes, GMTL provides a function called gmtl::lengthSquared() that returns the length of the vector without calculating the square root.

The GMTL vector classes provide an easy way to multiply a vector by a scalar. There are several ways to do it depending on what is required. Examples of each method follow.

To multiply a vector by a scalar and store the result in another vector, do the following:

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2;

vec2 = 3 * vec1;

(The order of the factors in the multiplication can be swapped depending on preference or need.) Here, vec2 gets the value <3.0, 4.5, -3.0>.

To multiply a vector by a scalar and store the result in the same vector, do the following:

gmtl::Vec3f vec1(1.0, 1.5, -1.0);

vec1 *= 3;

After this, vec1 has the value <3.0, 4.5, -3.0>.

Very similar to multiplying by a scalar, division by scalars is also possible. While the examples are almost identical, they are provided here for clarity.

To divide a vector by a scalar and store the result in another vector, do the following:

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2;

vec2 = vec1 / 3;

Here, vec2 gets the value <0.333333, 0.5, -0.333333>. Note that the scalar must come after the vector because the operation would not make sense otherwise.

To divide a vector by a scalar and store the result in the same vector, do the following:

gmtl::Vec3f vec1(1.0, 1.5, -1.0);

vec1 /= 3;

After this, vec1 has the value <0.333333, 0.5, -0.333333>.

SGI's OpenGL Performer likes to work with its own pfVec3 class, and to facilitate the use of it with gmtl::Vec3f, two conversion functions are provided for converting a gmtl::Vec3f to a pfVec3 and vice versa. The first works as follows:

gmtl::Vec3f vj_vec;
pfVec3 pf_vec;

// Do stuff to vj_vec...

pf_vec = vrj::GetPfVec(vj_vec);

where vj_vec is passed by reference for efficiency. (pf_vec gets a copy of a pfVec3.) To convert a pfVec3 to a gmtl::Vec3f, do the following:

pfVec3 pf_vec;
gmtl::Vec3f vj_vec;

// Do stuff to pf_vec...

vj_vec = vrj::GetVjVec(pf_vec);

Here again, pf_vec is passed by reference for efficiency, and vj_vec gets a copy of a gmtl::Vec3f. Both of these functions are found in the header vrj/Draw/Pf/PfUtil.h.

We have already demonstrated vector assignment, though it was not pointed out explicitly. It works just as vector assignment in mathematics. The C++ code that does assignment is as follows:

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2;

vec2 = vec1;

After the assignment, vec2 has the value <-1.0, -1.5, 1.0>. Ta da! Note that this is a copy operation which is the case for all the types of assignments of GMTL vectors.

To compare the equality of two vectors, there are three available methods (one is just the complement of the other, though):

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);

if ( gmtl::isEqual(vec1, vec2) )
{
   // Go here if vec1 and vec2 are equal.
}

or

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);

if ( vec1 == vec2 )
{
   // Go here if vec1 and vec2 are equal.
}

or

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);

if ( vec1 != vec2 )
{
   // Go here if vec1 and vec2 are not equal.
}

Choose whichever method is most convenient.

Given two vectors, finding the dot product is often needed. GMTL vectors provide a way to do this quickly so that programmers can save themselves the time of typing in the formula over and over. It works as follows:

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);
float dot_product;

dot_product = gmtl::dot(vec1, vec2);

Now, dot_product has the value 4.0.

Besides the dot product of two vectors, the cross product is another commonly needed result. It is calculated thusly:

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0), vec3;

vec3 = gmtl::cross(vec1, vec2);

The result is that vec3 gets a copy of vec1 cross vec2.

Adding two vectors can be done one of two ways. The first method returns a resulting vector, and the second method performs the addition and stores the result in the first vector.

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0), vec3;

vec3 = vec1 + vec2;

Now, vec3 has the value <2.5, 2.5, -2.0>.

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);

vec1 += vec2;

This time, vec1 has the value <2.5, 2.5, -2.0>.

Subtracting two vectors gives the same options as addition, and while the code is nearly identical, it is provided for the sake of clarity.

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0), vec3;

vec3 = vec1 - vec2;

Now, vec3 has the value <-0.5, 0.5, 0.0>.

gmtl::Vec3f vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);

vec1 -= vec2;

In this case, vec1 has the value <-0.5, 0.5, 0.0>.

It is often helpful to apply a transformation to a vector. Transformations are represented by a matrix, so it is necessary to multiply a matrix and a vector. The function gmtl::xform() does this job. For the following example, assume that there is a gmtl::Matrix44f transformation matrix xform_mat:

gmtl::Vec3f vec(1.0, 1.0, 1.0), result_vec;

gmtl::xform(result_vec, xform_mat, vec1);

Depending on the transformations contained within xform_mat, result_vec will be transformed fully. The operation as a mathematical equation would be:

where V and V' are vectors and M is a 4×4 transformation matrix.

The details behind gmtl::Vec3f and gmtl::Vec4f really are not all that gory. Internally, they are represented as three- and four-element arrays of floats respectively. Access to these arrays is provided through the member function getData(). For example, this access can be used in the following way:

gmtl::Vec3f pos(4.0, 1.0982, 10.1241);

glVertex3fv(pos.getData());

Granted, this particular example is rather silly and much slower than just listing the values as the individual arguments to glVertex3f(), but it should get the point across.

In general, the getData() member function should be treated very carefully. Access to it is provided mainly so that operations similar to this example can be performed quickly. An example of abusing access to getData() follows:

gmtl::Vec4f my_vec;

my_vec.getData()[0] = 4.0;
my_vec.getData()[1] = 1.0982;
my_vec.getData()[2] = 10.1241;
my_vec.getData()[3] = 1.0;

Do not do this. It can be confusing to readers of the code who do not necessarily need to know the details of the internal representation. Instead, use one of the methods described above for creating vectors and assigning the elements values.

Abstractly, gmtl::Matrix44f represents a 4×4 matrix of single-precision floating-point values. The class includes implementations of the standard matrix operations such as transpose, scale, and multiply. More specifically, it is a mechanism to facilitate common matrix operations used in computer graphics, especially those associated with a transform matrix. On the surface, it is nearly identical to a 4×4 C++ array of floats, but there is one crucial difference: a gmtl::Matrix44f keeps its internal matrix in column-major order rather than in row-major order. More detail on this is given below, but this is done because OpenGL maintains its internal matrices using the same memory layout. At the conceptual level, this does not matter—it is related only to the matrix representation in the computer's memory. Access to the elements is still in row-major order. In any case, understanding how C++ multidimensional arrays work means understanding 90% of what there is to know about gmtl::Matrix44f. The class provides a degree convenience not found with a normal C++ array, especially when programming with OpenGL. The complications surrounding the gmtl::Matrix44f class are identical to those with OpenGL matrix handling, and with an understanding of that, then all that is left to learn is the interface of gmtl::Matrix44f.

As a representation of mathematical matrices, gmtl::Matrix44f implements several common operations performed on matrices to relieve the users of some tedious, repetitive effort. The general mathematical operations are:

The operations well-suited for use with computer graphics are:

What is presented here involves some complicated concepts that are far beyond the scope of this documentation. Without an understanding of matrix math (linear algebra) and an understanding of how transformation matrices work in OpenGL, this document will not be very useful. It is highly recommended that readers be familiar with these topics before proceeding. Otherwise, with this high-level description in mind, we now continue on to explain the gmtl::Matrix44f class at the C++ level.

Keeping the idea of a normal mathematical matrix in mind, we are now ready to look at the C++ use of the gmtl::Matrix44f class. Most of the interface is defined using methods, but there are a few cases where mathematical operators have been overloaded to make code easier to read. Before going any further, whenever using a gmtl::Matrix44f, make sure to include gmtl/Matrix.h first. The operations presented above are now described in detail in the order in which they were listed above. We begin with creating the objects and setting their values.

Before doing anything with matrices, some must be created first. To create a gmtl::Matrix44f, the default constructor can be used. It initializes the matrix to be an identity matrix:

gmtl::Matrix44f mat1;

After creating this matrix mat1, its 16 elements can be assigned values all at once as follows:

mat1.set(0.0, 1.0, 2.3, 4.1,
         8.3, 9.0, 2.2, 1.0,
         5.6, 9.9, 9.7, 8.2,
         3.8, 0.9, 2.1, 0.1);

or with a float array:

float mat_vals[16] =
{
   0.0, 8.3, 5.6, 3.8,
   1.0, 9.0, 9.9, 0.9,
   2.3, 2.2, 9.7, 2.1,
   4.1, 1.0, 1.0, 0.1
};

mat1.set(mat_vals);

Note that when explicitly listing the values with set(), they are specified in row-major order. When put into a 16-element array of floats, however, they must be ordered so that they can be copied into the gmtl::Matrix44f in column-major order. This is the one exception in the interface where access is column-major (which probably means that the interface has a bug).

To set all the values of a new matrix in one step, they can be given as arguments when declaring the matrix:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1,
                     8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2,
                     3.8, 0.9, 2.1, 0.1);

All of the above code has exactly the same results but accomplishes those results in different ways.

To read the elements in a gmtl::Matrix44f object, programmers can use either the overloaded [] operator or the overloaded () operator. The overloaded [] operator returns the specified row of the gmtl::Matrix44f, and an element in that row can then be read using [] again. The code looks exactly the same as with a normal C++ two-dimensional array:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1,
                     8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2,
                     3.8, 0.9, 2.1, 0.1);
float val;

val = mat1[3][0];

Here, val is assigned the value 3.8. Using the overloaded () operator results in code that looks similar to the way the matrix element would be referenced in mathematics:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1,
                     8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2,
                     3.8, 0.9, 2.1, 0.1);
float val;

val = mat1(3, 0);

Again, val is assigned the value 3.8. Both of these operations are row-major.

Assigning one gmtl::Matrix44f to another happens using the normal = operator as follows:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2;

mat2 = mat1;

This makes a copy of mat1 in mat2 which can be a slow operation.

To compare the equality of two matrices, there are three available methods (one is just the complement of the other, though):

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

if ( gmtl::isEqual(mat1, mat2) )
{
   // Go here if mat1 and mat2 are equal.
}

or

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

if ( mat1 == mat2 )
{
   // Go here if mat1 and mat2 are equal.
}

or

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

if ( mat1 != mat2 )
{
   // Go here if mat1 and mat2 are not equal.
}

Choose whichever method is most convenient.

The transpose operation works conceptually as . The code is then:

gmtl::Matrix44f mat1;
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

gmtl::transpose(mat1, mat2);

The result is stored in mat1. mat2 is passed by reference for efficiency.

The inverse operation works conceptually as . The code is then:

gmtl::Matrix44f mat1;
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

gmtl::invert(mat1, mat2);

The result is stored in mat1. mat2 is passed by reference for efficiency.

For the addition operation, the interface is defined so that the sum of two matrices is stored in a third. There are two ways to do addition with gmtl::Matrix44f: using the add() method or using the overloaded + operator. Use of the former is recommended, but the latter can be used if one prefers that style of programming. Examples of both methods follow. The first block of code only declares the gmtl::Matrix44f objects.

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat3;

Using the gmtl::add() function:

gmtl::add(mat3, mat1, mat2);

Using the overloaded + operator:

mat3 = mat1 + mat2;

The result is stored (via a copy) in mat3.

For the subtraction operation, the interface is defined so that the difference of two matrices is stored in a third. There are two ways to do subtraction with gmtl::Matrix44f: using the sub() method or using the overloaded - operator. It is recommended that developers use the former, but the latter can be used for stylistic purposes. Examples of both methods follow. The first block of code only declares the gmtl::Matrix44f objects.

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat3;

Using the gmtl::sub() method:

gmtl::sub(mat3, mat1, mat2);

Using the overloaded - operator:

mat3 = mat1 - mat2;

The result is stored (via a copy) in mat3.

As in the case of addition and subtraction, the multiplication interface is defined so that the product of two matrices is stored in a third. This is likely to be the operation used most often since transformation matrices are constructed through multiplication of different transforms. For normal matrix multiplication, there are two ways to do multiplication with gmtl::Matrix44f: using the gmtl::mult() function or using the overloaded * operator. We recommend the use of the gmtl::mult() function but the overloaded * operator can be used by those who prefer that style of programming. Examples of both methods follow. The first block of code only declares the gmtl::Matrix44f objects.

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                    5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat3;

Using the gmtl::mult() function:

gmtl::mult(mat3, mat1, mat2);

Using the overloaded * operator:

mat3 = mat1 * mat2;

The result is stored (via a copy) in mat3.

There are two more multiplication operations provided that help in handling the order of the matrices when they are multiplied. These two extra operations do post-multiplication and pre-multiplication of two matrices. An example of post-multiplication is:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

gmtl::postMult(mat1, mat2);

Conceptually, the operation is so that the second matrix (mat2) comes as the second factor. The same result can be achieved using the overloaded *= operator:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

mat1 *= mat2;

An example of pre-multiplication is:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);
gmtl::Matrix44f mat2(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

gmtl::preMult(mat1, mat2);

Here, the conceptual operation is so that the second matrix (mat2) comes as the first factor. In both cases, the result of the multiplication is stored in mat1.

Scaling the values of a matrix by a scalar value can be done using two different methods: the setScale() method or the overloaded * and / operators that take a single scalar value and returns a gmtl::Matrix44f. As with the preceding operations, we recommend the use of the former, but the latter is available for those who want it. Examples of both methods follow. First, using the gmtl::setScale() function works as:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);


gmtl::setScale(mat1, 3.0);

In computer graphics, an identity matrix is often needed when performing transformations. Because of this, gmtl::Matrix44f provides a method for converting a matrix into an identity matrix in a single step (at the user code level anyway):

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

gmtl::identity(mat1);

Of course, simply declaring mat1 with no arguments would achieve the same result, but that is not such an interesting example.

Before using a matrix, it is often helpful to zero it out to ensure that there is no pollution from previous use. With a gmtl::Matrix44f, this can be done in one step:

gmtl::Matrix44f mat1(0.0, 1.0, 2.3, 4.1, 8.3, 9.0, 2.2, 1.0,
                     5.6, 9.9, 9.7, 8.2, 3.8, 0.9, 2.1, 0.1);

gmtl::zero(mat1);

The result is that all elements of mat1 are now 0.0.

All the rotation information for a transform can be contained in a single matrix using the methods for making an XYZ, a ZYX, or a ZXY Euler matrix. Code for all three follows:

vrj::Matrix mat1;
float x_rot = 0.4, y_rot = 0.541, z_rot = 0.14221;

gmtl::setRot(mat1, gmtl::EulerAngleXYZf(x_rot, y_rot, z_rot));
gmtl::setRot(mat1, gmtl::EulerAngleZYXf(z_rot, y_rot, x_rot));
gmtl::setRot(mat1, gmtl::EulerAngleZXYf(z_rot, x_rot, y_rot));

In every case, the matrix is zeroed before the rotation transformation is stored. The result of the above code is that mat1 is a ZXY Euler rotation matrix. The previous two operations are destroyed.

To make a translation matrix, there are two methods with each having two different types of arguments specifying the translation. The first makes a matrix with only the given translation (all other transformation information is destroyed):

gmtl::Matrix44f mat;
gmtl::Vec3f trans(4.0, -4.231, 1.0);

mat = gmtl::makeTrans<gmtl::Matrix44f>(trans);

To change the translation of a transformation matrix without completely obliterating all other transformations, use the following instead:

gmtl::Vec3f trans(4.0, -4.231, 1.0);

gmtl::setTrans(mat, trans);

To make a transformation matrix that only scales, a simple method is provided. It works as follows:

gmtl::Matrix44f mat;
gmtl::Vec3f scale( 1.5, 1.5, 1.5 );

mat = gmtl::makeScale<Matrix44f>(scale);

The result is that mat is a transformation matrix that will perform a scale operation. In this specific case, the scaling happens uniformly for x, y, and z.

Finally, methods are provided for extracting transformations from a given matrix. The individual rotations and the translation can be read. For the following examples, assume that mat is a gmtl::Matrix44f object representing arbitrary translation, rotation, and scaling transformations. To get the Z-axis rotation information (an Euler angle), use the following:

float z_rot = (gmtl::makeRot<gmtl::EulerAngleXYZf>(mat))[2];

The value return is in radians. We can also get the X-axis rotation.

float x_rot = (gmtl::makeRot<gmtl::EulerAngleXYZf>(mat))[0];

Getting translations is even simpler because translations are collected into a single vector easily.

gmtl::Vec3f trans;
gmtl::setTrans(trans, mat);

After this, the translation in mat is stored in trans. The same can be done with a gmtl::Vec4f instead of the gmtl::Vec3f.

SGI's OpenGL Performer likes to work with its own pfMatrix class, and to facilitate the use of it with gmtl::Matrix44f, two conversion functions are provided for making conversions. The first works as follows:

gmtl::Matrix44f vj_mat;
pfMatrix pf_mat;

// Perform operations on vj_mat...

pf_mat = vrj::GetPfMatrix(vj_mat);

where vj_mat is passed by reference for efficiency. (pf_mat gets a copy of a pfMatrix which is a slow operation.) To convert a pfMatrix to a gmtl::Matrix44f, do the following:

pfMatrix pf_mat;
gmtl::Matrix44f vj_mat;

// Perform operations on pf_mat...

vj_mat = vrj::GetVjMatrix(pf_mat);

Here again, pf_mat is passed by reference for efficiency, and vj_mat gets a copy of a gmtl::Matrix44f. Both of these functions are found in the header vrj/Draw/Pf/PfUtil.h.

Now it is time for the really nasty part. Reading this could cause difficulty in understanding the overwhelming amount of information just presented. Do not read any further unless you absolutely have to or you just like to confuse yourself.

C, C++, and mathematics use matrices in row-major order. Access indices are shown in Table 3.1. Row-major access indices

OpenGL ordering specifies that the matrix has to be column-major in memory. Thus, to provide programmers with a way to pass a transformation matrix to OpenGL in one step (via glMultMatrixf()), the gmtl::Matrix44f class maintains its internal matrix in column-major order. Note that in the following table, the given indices are what the cells have to be called in C/C++ notation because we are putting them back to back. This is illustrated in Table 3.2. Column-major access indices.

As mentioned, all of this is done so that a given gmtl::Matrix44f that acts as a full transformation matrix can be passed to OpenGL directly (more or less). For example, with a given gmtl::Matrix44f object mat upon which painstaking transformations have been performed, the following can be done:

glMultMatrixf(mat.getData());

That could not be simpler. All the transformation efforts have culminated into one statement.

For further information, the best possible source of information, especially for this class, is the header file. Read it; understand it; love it.

As noted above, access to input device data is granted through device proxies allocated by the Gadgeteer Input Manager. For each type of input device (digital, analog, keyboard/mouse, etc.), there is a device proxy class. As a programmer of VR Juggler applications, knowledge of such proxies does not have to be terribly in-depth. The fact is, most VR Juggler application object programmers will probably never need to know more about the interface of a type-specific device proxy than the return type of its data request method (usually named getData()). We will see more about the data request method in the explanation of device interfaces below. Most of the perceived complexity in the type-specific proxy classes is only important to Gadgeteer's internal maintenance of the active proxies. The following is the complete list of proxy classes in Gadgeteer 1.0 (used by VR Juggler 2.0):

In summary, the important thing to know is that a proxy is a pointer to a physical device. Application object programmers should normally use the higher level device interface as the mechanism to acquire a proxy and read data from the proxied device. The device interface encapsulates some type of proxy that in turn points to an input device. That device can be a wand, a keyboard, a light sensor, or a home-brewed device that reads some input and returns it to Gadgeteer in a meaningful way. That is a lot of indirection, but it makes the handling of physical devices by Gadgeteer incredibly powerful.

Device interfaces are designed to act as wrappers around type-specific device properties. This is implemented through the (template) class gadget::DeviceInterface<T>. Applications could use the proxy classes directly, but as we have already noted, acquiring the desired proxies from the Gadgeteer Input Manager is not wholly straightforward. The type-specific instances of gadget::DeviceInterface<T> (such as gadget::PositionInterface, gadget::DigitalInterface, etc.) simplify acquisition of proxies. Thus, typical VR Juggler application objects will have one or more device interface member variables and no proxy member variables.

The class gadget::DeviceInterface<T> is a templated class based on the proxy type it wraps. The following is the complete list of available gadget::DeviceInterface<T> instantiations in Gadgeteer 1.0 (used by VR Juggler 2.0):

The typedefs are provided to make the application object code more readable.

In the application object, a device interface member variable is used as a smart pointer to the proxy. In C++, a smart pointer is not usually an actual object pointer. Instead, the class acting as a smart pointer overloads the dereference operator -> so that a special action can be taken when the “pointer” is dereferenced. The dereference operator is just another operator like the addition and subtraction operators, and overloading the deference operator allows some extra work to be done behind the scenes. On the surface, the code looks exactly the same as a normal pointer dereference, and in most cases, people reading and writing the code can think of the smart pointer as a standard pointer. It may also be convenient to think of a smart pointer as a handle.

With that background, we can move on to explain how gadget::DeviceInterface<T> uses these concepts. In user code, there will be instances of types such as gadget::DigitalInterface, gadget::PositionInterface, gadget::KeyboardMouseInterface, and the like. Once they are properly initialized, device interface objects (whatever their types may be) will act as smart pointers to the actual Gadgeteer device proxy objects that they encapsulate.

At this point, it is perfectly reasonable to wonder why Gadgeteer uses a concept that requires all sorts of documentation and explanation. The extra effort is worth it because it allows Gadgeteer to hide the actual type of the device being used. There is no need to know that some specific VR system uses a wireless mouse connected to a PC reading bytes from a PS/2 port that represent button presses. All that matters is knowing which buttons are pressed at a given instant. The class gadget::DigialInterface gives exactly that information, and it quietly hides the messiness of dealing with the mouse, its driver, and its communication protocol.

Before using a device interface, some objects must be declared. Programmers must choose the type that is appropriate for the type of devices relevant to a given application. All device interface objects must be initialized in the application object's override of the method vrj::App::init() method. Because we are dealing with a templated type (gadget::DeviceInterface<T>), every type-specific instantiation has the same interface. Hence, all type-specific device interfaces are initialized using the gadget::DeviceInterface<T>::init() method. This method takes a single string argument naming the proxy to which the interface will connect. The name can be the name of a proxy or a proxy alias, both of which are defined in VR Juggler configuration files. Example names are “VJHead”, “Wand”, “VJButton0”, and “Accelerate Button”. Using meaningful symbolic names makes them easier to remember, and it also contributes to hiding the details about the physical device. With this system, no one needs to care how transformation information from the user's head is generated. Gadgeteer cares, but there is no need for it to tell anyone else. All developers care about is the head transformation matrix. An example of initializing a gadget::PositionInterface that connects with the user head proxy is:

gadget::PositionInterface head;

head.init("VJHead");

Remember that this has to be done in an application object's init() method. The actual object used would be a member variable of the application class. Note that here, the normal syntax for calling the method of a C++ object is used rather than using the dereference operator. Until it is initialized, the device interface object cannot act as a smart pointer.

Once device interface objects are all initialized and ready to use, it is time to start using them as smart pointers. VR Juggler and Gadgeteer are already working hard in the background to update device proxies, and the application is free to access them. It is usually best to acquire data from the device proxy through the device interface in the preFrame() method, but this may not necessarily be true for all proxies. Continuing with our example of a gadget::PositionInterface to the user head proxy, the following code shows how to read the transformation matrix for the user's head (in feet):

gmtl::Matrix44f head_mat = head->getData();

Believe it or not, the code really is that easy. Simply use the overloaded dereference operator to get access to the position proxy object hidden in gadget::PositionInterface to read data from the proxy. We now move on to explain the use of type-specific device interfaces.

  1 void MyApp::preFrame()
    {
       if ( mButton0->getData() )
       {
  5       // Set state for when mButton0 is pressed, has been pressed
          // since the last frame, or has been released since the
          // last frame ...
       }
       else
 10    {
          // Set state for when mButton0 is not pressed ...
       }
    
       switch (mButton1->getData()
 15    {
          case gadget::Digital::OFF:
             // Set state for when mButton1 is not pressed ...
             break;
          case gadget::Digital::ON:
 20          // Set state for when mButton1 is pressed ...
             break;
          case gadget::Digital::TOGGLE_ON:
             // Set state for when mButton1 has been pressed since
             // the last frame ...
 25          break;
          case gadget::Digital::TOGGLE_OFF:
             // Set state for when mButton1 has been released since
             // the last frame ...
             break;
 30    }
    
       if ( mButton2->getData() == gadget::Digital::TOGGLE_ON )
       {
          // Set state when mButton2 goes "high" (is toggled on) ...
 35    }
       else if ( mButton2->getData() == gadget::Digital::TOGGLE_OFF )
       {
          // Set state when mButton2 goes "low" (is toggled off) ...
       }
 40 }

  1 #include <boost/shared_ptr.hpp>
    #include <gadget/Type/KeyboardMouseInterface.h>
    #include <gadget/Type/KeyboardMouse/KeyEvent.h>
    #include <gadget/Type/KeyboardMouse/MouseEvent.h>
  5 #include <vrj/Draw/OpenGL/App.h>
    
    
    // This is here to shorten the use of the function in preFrame()
    // boost::dynamic_pointer_cast<T,U>() below.
 10 using namespace boost;
    
    class MyApp : public vrj::opengl::App
    {
    public:
 15    MyApp() : vrj::opengl::App()
       {
          /* Do nothing. */ ;
       }
    
 20    virtual ~MyApp()
       {
          /* Do nothing. */ ;
       }
    
 25    void init()
       {
          mKeyboard.init("VJKeyboard");
       }
    
 30    void preFrame()
       {
          gadget::KeyboardMouse::EventQueue evt_queue =
             mKeyboard->getEventQueue();
          typedef gadget::KeyboardMouse::EventQueue::iterator iter_type;
 35 
          // Loop over all the keyboard and mouse events that
          // occurred since the last frame.
          for (iter_type i = evt_queue.begin(); i != evt_queue.end(); ++i)
          {
 40          const gadget::EventType type = (*i)->type();
    
             if (type == gadget::KeyPressEvent  ||
                 type == gadget::KeyReleaseEvent)
             {
 45             gadget::KeyEventPtr key_evt =
                   dynamic_pointer_cast<gadget::KeyEvent>(*i);
                // Handle the key press event ...
             }
             else if (type == gadget::MouseButtonPressEvent   ||
 50                   type == gadget::MouseButtonReleaseEvent ||
                      type == gadget::MouseMoveEvent)
             {
                gadget::MouseEventPtr mouse_evt =
                   dynamic_pointer_cast<gadget::MouseEvent>(*i);
 55             // Handle the mouse event ...
             }
          }
       }
    
 60    void draw()
       {
          // Draw something ...
       }
    
 65 private:
       gadget::KeyboardMouseInterface mKeyboard;
    };

  1 #include <gmtl/Matrix.h>
    
    #include <gadget/Type/Position/PositionUnitConversion.h>
    #include <gadget/Type/PositionInterface.h>
  5 
    #include <vrj/Draw/OpenGL/App.h>
    
    
    class MyApp : public vrj::opengl::App
 10 {
    public:
       MyApp() : vrj::opengl::App()
       {
          /* Do nothing. */ ;
 15    }
    
       virtual ~MyApp()
       {
          /* Do nothing. */ ;
 20    }
    
       void init()
       {
          mWand.init("VJWand");
 25    }
    
       // Use meters for the application units.
       float getDrawScaleFactor()
       {
 30       return gadget::PositionUnitConversion::ConvertToMeters;
       }
    
       void preFrame()
       {
 35       // Request the current wand transformation matrix in
          // application units (meters).
          const float units = getDrawScaleFactor();
          gmtl::Matrix44f wand_mat(mWand->getData(units));
          // Do something with the wand transformation ...
 40    }
    
       void draw()
       {
          // Draw something ...
 45    }
    
    private:
       gadget::PositionInterface mWand;
    };

The indirection provided by device proxies facilitates run-time reconfiguration of hardware devices. If a hardware device breaks down while an application is running, the device can be replaced without shutting down and restarting the application. To support this capability, proxies can become “stupefied,” which means that they are not connected to a device and cannot return new data.

In general, application programmers do not need to worry about stupefied proxies. Data will be returned by the proxy whether it is stupefied or not, but if the proxy is stupefied, it cannot return new data. Stupefied proxies can occur as a result of an error in the VR Juggler configuration or because the hardware device pointed at by the proxy failed to start up correctly.

To determine whether a proxy is stupefied, the method gadget::Proxy::isStupefied() can be used. The stupefied state cannot be changed programatically by user code, however. Only the Input Manager is capable of reconfiguring a proxy to point at a new valid device. Hence, changing the stupefication state of a proxy from an application object will have no effect and may cause the application to crash.

What is truly amazing about Gadgeteer device interfaces is, despite their seeming complexity, there is really nothing to them. Trying to trace through the source code is a little tricky, but conceptually, it is all about pointers. Keep in mind that all this documentation was written using nothing more than the Gadgeteer header files as a reference.

As mentioned, the class gadget::DeviceInterface<T> provides the method interface for all the type-specific instantiations, including the overloaded dereference operator. The base class of gadget::DeviceInterface<T>, gadget::BaseDeviceInterface, maintains the name of the proxy and the proxy reference itself, and it provides the all-important init() method.

The beauty of it all is that the proxy object being pointed to by the device interface can be changed without affecting the execution of the user application. In other words, the proxies can be changed at run time to point to different physical devices. All the while, the user code is still using the smart pointer interface and getting data of some sort. This flexibility is one of the most important features of Gadgeteer, and it is important to understand.

As described in previous chapters (see Chapter 1. Getting Started, for example), all VR Juggler applications derive from a base application object class (vrj::App). This class defines the basic interface that VR Juggler expects from all application objects. This means that when constructing an application, the user-defined application object must inherit from vrj::App or from a Draw Manager-specific application class that has vrj::App as a superclass. For example:

class userApp : public vrj::App
{
public:
   init();
   preFrame();
   postFrame();
}

This defines a new application class (userApp), instances of which can be used anywhere that VR Juggler expects an application object.

A user application does not have to (and in most cases does not) derive from vrj::App directly. In almost all cases, an application class is derived from a Draw Manager-specific application class. For example:

class userGlApp : public vrj::opengl::App
{
public:
   init();
   preFrame();
   postFrame();
   
   draw();
}

This is an example of an OpenGL application. The application class (userGlApp) has derived directly from the OpenGL Draw Manager-specific vrj::opengl::App application base class. This class provides extra definitions in the interface that are custom for OpenGL applications.

While there has already been a brief presentation about getting input in an application, we need something more. Since all device interfaces look the same, we will focus on an example of getting positional input. All other types are very similar. We begin with a simple application object skeleton.

class myApp : public vrj::App
{
public:
   init();
   preFrame();
private:
   gadget::PositionInterface mWand;
}

Note the declaration of the variable mWand of type gadget::PositionInterface. This is the first addition to an application. Device interfaces are usually member variables of the user application class, as in this example.

myApp::init()
{
   mWand.init("NameOfPosDevInConfiguration");
}

The device interface has to be told about the device from which it will get data. This is done by calling the device interface object's init() method with the symbolic string name of the device. This device name comes from the active configuration. We are now ready to read from the device.

...
const float units = getDrawScaleFactor();
gmtl::Matrix44f wand_pos(mWand->getData(units));
...

The above code shows an example of using the positional device interface in an application. It shows some sample code where the application copies the positional information from a device interface. When it is dereferenced, the device interface figures out what device it points to and returns the data from that device. Again, refer to Device Proxies and Device Interfaces for more information about using device proxies and device interfaces.

In the previous section, we showed how to get input from devices, but we never said where to put the code. The location, surprisingly, is application dependent. There are some very good guidelines regarding where applications should process input. Before explaining them, however, we should review the VR Juggler kernel control loop, presented again in Figure 4.1. VR Juggler kernel control loop.

Figure 4.1. VR Juggler kernel control loop

This diagram looks complicated, but the key here is the updateAllData() call near the bottom of the diagram. This is where the Gadgeteer Input Manager updates all the cached device data that will be used in drawing the next frame. This updated copy is used by all user references to device data until the next update and the end of the next frame of execution.

This means two things:

The first point is important because it means that the copy of the device data with the lowest latency is always available in the preFrame() member function. The second point is equally important because it says why user applications should not waste any time in preFrame(). Any time spent in preFrame() increases system latency and in turn decreases the perceived quality of the environment. Hence, it is crucial to avoid placing computations in preFrame().

Before describing how to render using OpenGL with VR Juggler, we must cover the more basic topic of clearing the color and depth buffers. We describe this part before explaining how to render graphics because these steps will be common to all VR Juggler applications based on OpenGL.

In VR Juggler 1.1 and beyond, there is support for drawing multiple OpenGL viewports in a single VR Juggler display window. This feature is useful for tiled displays where each viewport renders a specific part of the scene. In order for an OpenGL-based application to work with multiple viewports, the color and depth buffers need to be cleared at the correct times.

In a user application, the method vrj::opengl::App::bufferPreDraw() is overridden so that it clears the color buffer. For example, the following code clears the color buffer using black:

void userApp::bufferPreDraw()
{
   glClearColor(0.0f, 0.0f, 0.0f, 0.0f);
   glClear(GL_COLOR_BUFFER_BIT);
}

Now we need to clear the depth buffer. This must be done separately from the color buffer to ensure proper stereo rendering. The depth buffer must be cleared in the application object's draw() method, usually as the first step:

void userApp::draw()
{
   glClear(GL_DEPTH_BUFFER_BIT);

   // Rendering the scene ...
}

The most important (and visible) component of most OpenGL applications is the OpenGL drawing. The vrj::opengl::App class interface defines a draw() member function to hold the code for drawing a virtual environment. Hence, any OpenGL drawing calls should be placed in the vrj::opengl::App::draw() function of the user application object.

Adding drawing code to an OpenGL-based VR Juggler application is straightforward. The draw() method is called whenever the OpenGL Draw Manager needs to render a view of the virtual world created by the user's application. It is called for each defined OpenGL context, and it may be called multiple times per frame in the case of multi-surface setups and/or stereo configurations. Applications should never rely upon the number of times this member function is called per frame.

When the method is called, the OpenGL model view and projection matrices have been configured correctly to draw the scene. Input devices are guaranteed to be in the same state (position, value, etc.) for each call to the draw() method for a given frame.

Many readers may already be familiar with the specifics of OpenGL. In this section, we provide a very brief introduction to context-specific data within OpenGL, and we proceed to explain how it is used by VR Juggler. Those who are already familiar with context-specific data may skip ahead to Why it is Needed or to Using Context-Specific Data.

The OpenGL graphics API operates using a state machine that tracks the current settings and attributes set by the OpenGL code. Each window in which we render using OpenGL has a state machine associated with it. The state machines associated with these windows are referred to as OpenGL rendering contexts.

Each context stores the current state of an OpenGL renderer instance. The state includes the following:

using namespace vrj;

class userApp : public GlApp
{
public:
  draw();
public:
  int mDispListId;
};

userApp::draw()
{
   glCallList(mDispListId);
}

using namespace vrj;

class userApp : public GlApp
{
public:
   draw();
public:
   GlContextData<int> mDispListId; // Context-specific variable
};

userApp::draw()
{
   glCallList(*mDispListId);
}

The VR Juggler OpenGL graphics system is a complex, multi-headed beast. Luckily, developers do not have to understand how the system is working to use it correctly. As long as developers subscribe to several simple rules for allocating and using context data, everything will work fine. This section contains these rules, but it does not describe the rationale behind the rules. Those readers who are interested in the details of why these rules should be followed should please read the subsequent section. It contains much more (excruciating) detail.

  1 void userApp::contextInit()
    {
       // Allocate context specific data
       (*mDispListId) = glGenLists(1);
  5 
       glNewList((*mDispListId), GL_COMPILE);
          glScalef(0.50f, 0.50f, 0.50f);
          // Call func that draws a cube in OpenGL
          drawCube();
 10    glEndList();
       ...
    }

userApp::contextInit()
{
   if (have work to do)
   {
     // Do it
   }
}

Within this section, we provide the details of context-specific data in VR Juggler and justify the rules presented in the previous section.

Figure 5.2. VR Juggler OpenGL system

In an application using OpenGL Performer, the scene graph must be initialized before it can be used. The method vrj::pf::App::initScene() is provided for that purpose. Within this method, the root of the application scene graph should be created, and any required models should be loaded and attached to the root in some way. The exact mechanisms for accomplishing this will vary depending on what the application will do.

During the initialization of OpenGL Performer by VR Juggler, vrj::pf::App::initScene() is invoked after the Performer functions pfInit() and pfConfig() but before vrj::App::apiInit().

In order for Performer to render the application scene graph, it must get access to the scene graph root. The method vrj::pf::App::getScene() will be called by the Performer Draw Manager so that it can give the scene graph root node to Performer. Since the job of getScene() is straightforward, its implementation can be very simple. A typical implementation will have a single statement that returns a member variable that holds a pointer to the application scene graph root node.

Besides the two methods discussed so far, there are several other methods in vrj::pf::App that extend the basic vrj::App interface. Each is discussed in this section.

chan->clear();
pfDraw();

The Performer function pfExit() poses a problem for VR Juggler applications, and some background information will help ensure that readers understand the consequences of using pfExit() (or not). The main issue with pfExit() as it relates to VR Juggler is that calling pfExit() has the side effect of calling the system function exit(), which means that it should be (or has to be) the very last function call of a program. Prior to VR Juggler 2.0.1, the VR Juggler Performer Draw Manager was written to call pfExit() from within the method vrj::PfDrawManager::closeAPI(). Before VR Juggler 2.0 Beta 3, however, this method of the vrj::PfDrawManager interface had never been called—the result of the kernel shutdown process being incomplete. With the more complete kernel shutdown process in VR Juggler 2.0 Beta 3 and 2.0.0, authors of Performer-based VR Juggler applications saw their applications exiting prematurely after invoking the kernel shutdown. More specifically, any code that was intended to be executed after vrj::PfDrawManager::closeAPI() would not be executed. Such code includes vrj::App::exit() or an override thereof; an application object destructor; and anything else to be done after vrj::Kernel::waitForKernelStop() returned.

To remedy this problem, vrj::PfDrawManager::closeAPI() in VR Juggler 2.0.1 and newer does not call pfExit(). Rather, it is the responsibility of the application programmer to call pfExit() if s/he so desires. Failing to call pfExit() could result in resource leaks from Performer, but calling pfExit() has been known to cause application crashes (irrespective of whether VR Juggler is used). In general, users should call pfExit() at the end of their main() function, but if doing so causes the application to crash on exit, then not calling pfExit() is probably the better option.

The important thing to remember is that the application object destructor needs to be called before pfExit() is called. Refer to Example 5.2. Using pfExit() with a Heap-Allocated Application Object for an example of how pfExit() would be used with a VR Juggler application object allocated on the heap. For a stack-allocated application object, see Example 5.3. Using pfExit() with a Stack-Allocated Application Object.

  1 int main(int argc, char* argv[])
    {
       vrj::Kernel* kernel = vrj::Kernel::instance();
    
  5    // Allocate the application object on the heap.  Its
       // destructor will be called manually before calling
       // pfExit().
       simplePfApp* application = new simplePfApp();
    
 10    // Load config files.
       for ( int i = 2; i < argc; ++i )
       {
          kernel->loadConfigFile(argv[i]);
       }
 15 
       kernel->start();
    
       // Configure the application.
       application->setModel(argv[1]);
 20    kernel->setApplication(application);
    
       // Wait for the kernel to shut down.
       kernel->waitForKernelStop();
    
 25    // Final application clean-up.
       delete application;
    
       // Clean up Performer.
       // Calls system exit() function and therefore never returns.
 30    pfExit();
    
       return 0;
    }

  1 int main(int argc, char* argv[])
    {
       // Nested scope for stack-allocated data.
       {
  5       vrj::Kernel* kernel = vrj::Kernel::instance();
    
          // Load config files.
          for ( int i = 2; i < argc; ++i )
          {
 10          kernel->loadConfigFile(argv[i]);
          }
    
          kernel->start();
    
 15       // Allocate the application object on the stack.  Its
          // destructor will be called automatically at the end
          // of this nested scope.
          simplePfApp application;
    
 20       // Configure the application and give it to the kernel.
          application.setModel(argv[1]);
          kernel->setApplication(&application);
    
          // Wait for the kernel to shut down.
 25       kernel->waitForKernelStop();
       }
    
       // Clean up Performer.
       // Calls system exit() function and therefore never returns.
 30    pfExit();
    
       return 0;
    }

In an application using OpenSG, the scene graph must be initialized before it can be used. The method vrj::opensg::App::initScene() is provided for that purpose. Within this method, the root of the application scene graph should be created, and any required models should be loaded and attached to the root in some way. The exact mechanisms for accomplishing this will vary depending on what the application will do.

During the API initialization, vrj::opensg::App::initScene() is invoked. This happens after OSG::osgInit() has been called, so OpenSG should be fully initialized and ready to be used.

In order for OpenSG to render the application scene graph, it must get access to the scene graph root. The method vrj::opensg::App::getScene() will be called by the OpenSG application class wrapper so that it can get access to the currently active scene graph whenever the wrapper needs to use it (for example when rendering or updating). Since the job of getScene() is straightforward, its implementation can be very simple. A typical implementation will have a single statement that returns a member variable that holds a pointer to the current scene graph root node.

virtual OSG::NodePtr getScene()
{
   return mSceneRoot;  // Return the root of the graph
}

In an application using OSG, the scene graph must be initialized before it can be used. The method vrj::osg::App::initScene() is provided for that purpose. Within this method, the root of the application scene graph should be created, and any required models should be loaded and attached to the root in some way. The exact mechanisms for accomplishing this will vary depending on what the application will do.

In order for OSG to render the application scene graph, it must get access to the scene graph root. The method vrj::osg::App::getScene() will be called by the OSG application class wrapper so that it can get access to the currently active scene graph whenever the wrapper needs to use it (for example when rendering or updating). Since the job of getScene() is straightforward, its implementation can be very simple. A typical implementation will have a single statement that returns a member variable that holds a pointer to the current scene graph root node.

virtual osg::Group* getScene()
{
   return mSceneRoot;  // Return the root of the graph
}

One approach to implementing clustering for interactive graphics applications is to share all data received from input devices. This is based on an assumption that the interaction with the computer graphics will occur through input devices such as 6DOF trackers, pointing devices, etc. Using this approach, a distinct copy of the VR application is run on each cluster node, but they all see the same input data. Since changes to the scene are based on information from the input devices, all the nodes will make the same state changes each frame and therefore remain synchronized.

This capability is implemented through the Gadgeteer Remote Input Manager and the RIMPlugin used by the Cluster Manager. The basic goal of these components is to provide a distributed shared memory system for VR input device data. Through shared input data, applications can migrate transparently between shared memory VR systems and PC cluster VR systems.

Shared input data is the easiest VR Juggler clustering feature that can be utilized by application object programmers. In simple cases, nothing about an application will have to change to take advantage of shared input data because the details are hidden within the VR Juggler configuration. The Cluster Manager simply needs to be configured to load the RIMPlugin and the Start Barrier Plug-in (StartBarrierPlugin) to enable applications to take advantage of shared input data.

When input data sharing is not sufficient to enable a VR Juggler application to run on a cluster, the next option is to use application-specific shared data. Using this option, VR application developers can easily exchange any type of data across a cluster of machines. For example, we might have a GUI running on a hand-held device that interacts with the VR application to control it. We cannot expect this GUI to connect to all nodes in the cluster. Instead, the GUI connects to a single node that accepts the commands from the GUI and then relays them to the rest of the cluster nodes using application-specific shared data.

Application-specific shared data is implemented through the generic (templated) container type cluster::UserData<T> and the Application Data Manager plug-in (ApplicationDataManager in the Cluster Manager config element plug-in list). As is typically the case with generic containers, any sort of data can be stored and therefore shared. The only caveat is that the contained type must have the following two methods:

Respectively, these two methods are used for serializing and de-serializing shared data types. The simplest way to achieve this is to create a data structure that is a subclass of the abstract type vpr::SerializableObject and overriding its pure virtual writeObject() and readObject() methods.

Deriving from vpr::SerializableObject is not viable in all cases, however. If the data that must be shared is of a type defined in a third-party library, it cannot be modified to derive from vpr::SerializableObject. In that case, the type vpr::SerializableObjectMixin<T> can be used. The methods vpr::SerializableObjectMixin<T>::writeObject() and vpr::SerializableObjectMixin<T>::readObject() must be specialized for the desired type T.

In either case, the end result is a means to serialize the data to be shared across the cluster, and application object programmers will implement methods named writeObject() and readObject(). When writeObject() is invoked, it is passed a pointer to a vpr::ObjectWriter object. An object writer is a simple wrapper around an expandable block of memory. Each write operation appends some number of bytes to the memory block based on the size of the data written. The type vpr::ObjectWriter provides methods for writing all the basic C++ data types (int, float, bool, char, etc.), though they are named based on the cross-platform type identifiers provided by the VR Juggler Portable Runtime (vpr::Int32, vpr::Uint8, etc.). Byte ordering (endian) issues are handled internally by the object writer. The implementation of writeObject() for any shared data type simply copies the data members of the shared data structure into the object writer.

Inversely, the implementation of readObject() reads data from an object reader (an instance of vpr::ObjectReader) into the local copy of the data structure. The object reader contains a fixed-size block of memory and a pointer to the current location in that memory block. Each read operation moves the pointer some number of bytes in the memory block based on the size of the data read.

We now present two examples of using the serializable object concept. The first demonstrates the case when a new data structure can be created; the second is the case when a third-party type must be made serializable. When we make a new data structure, it is quite easy to enable serialization. Consider the basic type shown in Example 6.1. Declaration of a Serializable Type. It derives from vpr::SerializableObject and overrides writeObject() and readObject() just as it must. It has three data members of different types that define the state of an instance of our type. The serialization and de-serialization implementation, which is quite straightforward, is shown in Example 6.2. Serializing an Application-Specific Type.

#include <vpr/IO/SerializableObject.h>

class MyType : public vpr::SerializableObject
{
public:
   void writeObject(vpr::ObjectWriter* writer);
   void readObject(vpr::ObjectReader* reader);
   // Other public methods ...

private:
   unsigned int mIntData;
   char         mByteData;
   float        mFloatData;
};

void MyType::writeObject(vpr::ObjectWriter* writer)
{
   writer->writeUint32(mIntData);
   writer->writeInt8(mByteData);
   writer->writeFloat(mFloatData);
}

void MyType::readObject(vpr::ObjectReader* reader)
{
   mIntData   = reader->readUint32();
   mByteData  = reader->readInt8();
   mFloatData = reader->readFloat();
}

Now we consider the case when we need to serialize a third-party type. First, let us assume that we have a type, called SomeType, defined in a header file from a third-party C++ library. This is shown in Example 6.3. Sample Third-Party Type. The type has three accessor methods for reading its data and three for writing. We can then specialize the methods of vpr::SerializableObjectMixin<T> as shown in Example 6.4. Serializing a Third-Party Type Using vpr::SerializableObjectMixin<T>.

class SomeType
{
public:
   unsigned int getIntData();
   void setIntData(unsigned int v);

   char getByteData();
   void setByteData(char v);

   float getFloatDat();
   void setFloatData(float v);

private:
   // Private data ...
};

#include <vpr/IO/SerializableObject.h>

template<>
void vpr::SerializableObjectMixin<SomeType>::
writeObject(vpr::ObjectWriter* writer)
{
   writer->writeUint32(getIntData());
   writer->writeInt8(getByteData());
   write->writeFloat(getFloatData());
}

template<>
void vpr::SerializableObjectMixin<SomeType>::
readObject(vpr::ObjectReader* reader)
{
   setIntData(reader->readUint32());
   setByteData(reader->readInt8());
   setFloatData(reader->readFloat());
}

The magic of vpr::SerializableObjectMixin<T> allows the specialized methods to behave as member functions in SomeType. This means that the specialized members have easy access to all public and protected members of SomeType.

Now that we have data serialization out of the way, we can turn our attention to the use of cluster::UserData<T>, the special type that automates application-specific data sharing. For each type of shared data, the application object will have at least one instance of cluster::UserData<T>. Example instantiations of cluster::UserData<T> are shown in Example 6.5. Declaring Instances of cluster::UserData<T>.

#include <vrj/Draw/OpenGL/App.h>
#include <plugins/ApplicationDataManager/UserData.h>
#include <SomeType.h>
#include "MyType.h"

class AppObject : public vrj::opengl::App
{
public:
   void init();
   void preFrame();
   void latePreFrame();
   void draw();

   // Other public member functions ...

private:
   cluster::UserData<MyType> mMyTypeObj;
   cluster::UserData< vpr::SerializableObjectMixin<SomeType> > mSomeTypeObj;
};

Next, we must initialize the cluster::UserData<T> instances so that the Application Data Manager plug-in can identify the shared data types and so that the application can determine which cluster node will be allowed to write to the shared data. While there are two ways to do this, we will show only the recommended approach here. First, a globally unique identifier (GUID) must be defined for each and every shared data type instance. The command-line utility uuidgen is available on most operating systems for generating new GUIDs (also known as universally unique identifiers or UUIDs). These will be used in the application object init() method, as shown in Example 6.6. Initializing Application-Specific Shared Data.

void AppObject::init()
{
   vpr::GUID mytype_guid("99CFD306-32AB-11D9-A963-000D933B5E6A");
   mMyTypeObj.init(mytype_guid);

   vpr::GUID sometype_guid("A154B8E8-32AB-11D9-B4C9-000D933B5E6A");
   mSomeTypeObj.init(sometype_guid);
}

In conjunction with this, two config elements need to be created. These will be used by the Application Data Manager plug-in to identify which cluster node will be the writer node. The “guid” properties must match the string values used to initialize the vpr::GUID objects in Example 6.6. Initializing Application-Specific Shared Data. The “hostname” properties set the name of the cluster node that will be the shared data writer. An example of this is shown in Example 6.7. Application-Specific Shared Data Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration
   xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
   name="Example Shared Application Data Configuration"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">

   <elements>
      <application_data name="MyType Shared Data" version="1">
         <guid>99CFD306-32AB-11D9-A963-000D933B5E6A</guid>
         <hostname>machine1</hostname>
      </application_data>
      <application_data name="SomeType Shared Data" version="1">
         <guid>A154B8E8-32AB-11D9-B4C9-000D933B5E6A</guid>
         <hostname>machine1</hostname>
      </application_data>
   </elements>
</configuration>

Now that the shared data is initialized and ready to use, we can write to and read from it—the Application Data Manager plug-in will take care of the rest. Only one node can be allowed to write to the data. This is determined through the use of the method cluster::UserData<T>::isLocal(). This method returns a Boolean value that indicates whether the data is “local.” The local node is the one named in the configuration element, as shown earlier. Writes to shared data should only occur in preFrame() or postFrame() after testing the result of cluster::UserData<T>::isLocal(). This is shown in Example 6.8. Writing to Application-Specific Shared Data.

void AppObject::preFrame()
{
   if ( mMyTypeObj.isLocal() )
   {
      // Computations ...
      mMyTypeObj->setIntData(...);
      mMyTypeObj->setByteData(...);
      mMyTypeObj->setFloatData(...);
   }

   if ( mSomeTypeObj.isLocal() )
   {
      // Computations ...
      mSomeTypeObj->setIntData(...);
      mSomeTypeObj->setByteData(...);
      mSomeTypeObj->setFloatData(...);
   }
}

After the snapshot of the application-specific shared data for the current frame has been distributed to the cluster nodes, it is time to read the shared data and set up the application state for rendering the current frame. This should be done in the application object method latePreFrame() or in draw(). This is demonstrated in Example 6.9. Reading from Application-Specific Shared Data in latePreFrame() and in Example 6.10. Reading from Application-Specific Shared Data in draw(). All the nodes in the cluster will read the results of the computations made in preFrame() and set up the application state before rendering. In general, there should be no need to use cluster::UserData<T>::isLocal() at this point.

void AppObject::latePreFrame()
{
   mStateVar1 = mMyTypeObj->getIntData();
   mStateVar2 = mMyTypeObj->getByteData();
   // And so on ...
}

void AppObject::draw()
{
   int  state_var1 = mMyTypeObj->getIntData();
   char state_var2 = mMyTypeObj->getByteData();
   // And so on ...
   // Render the scene ...
}

The choice of which method to use depends on the application type and on the data flow of the application object. Scene graph-based application objects will not have a draw() method, so latePreFrame() must be used. For application object types not based on a scene graph (currently only vrj::opengl::App), there is a trade off to consider. If latePreFrame() is used, then the rendering state information must be stored in member variables of the application class. If draw() is used, then the state can be defined using stack variables within the method, but the additional function call overhead and pointer derference (resulting from the use of the Smart Pointer pattern) could impact the application frame rate. Remember that draw() is invoked for every window and every viewport within each window. The number of calls to draw() increases further when stereoscopic rendering is enabled. If latePreFrame() is used instead, the Smart Pointer overhead will only be exhibited once per frame.

With the tools for VR Juggler cluster programming in hand, we can turn our attention to specific, higher level areas that must be handled carefully when writing applications that may run on a graphics cluster.

static vpr::Interval last_frame; 
vpr::Interval current_frame = mHead->getTimeStamp();
vpr::Interval diff(current_frame - last_frame);
last_frame = current_frame; // You can get the delta in microseconds from 
                            // vpr::Uint64 delta = diff.usecs();

In this final section, we present some frequently asked questions regarding VR Juggler application programming and clustering.

We begin our explanation of adding sound to a VR Juggler application by presenting the direct use of the Sonix API. This requires more programming than using the VR Juggler Sound Manager, but it will be useful to understand how Sonix operates in order to take full advantage of the Sound Manager. In particular, reading this section is a necessary part of understanding general Sonix usage, and readers are encouraged to read both this section and the next before deciding on which approach to use in their VR Juggler applications.

Basic Sonix Usage

In Figure 6.1. Basic Sonix Interface, we see the API for Sonix (see Figure 6.2. The Sonix Design for the complete software architecture). The main parts that a sound programmer will use are the classes snx::SoundHandle and snx::sonix (a singleton). The snx::SoundHandle class is used to manipulate individual sounds. The snx::sonix singleton class is used to start, stop, and reconfigure the sound system. Both classes must be used for any sound to be heard.

Figure 6.1. Basic Sonix Interface

Starting the Sonix system is easy. Basically, the only call needed to start the system is snx::sonix::changeAPI(). The backend audio software is loaded into Sonix through a plug-in system. The plug-in to use is identified by a string name, one of “OpenAL”, “AudioWorks”, or “Audiere”, as shown in Example 6.12. Initializing the Sonix Sound APi. The choice of which to use depends on availability and compatibility. For example, OpenAL and Audiere on IRIX can only be used with a pthreads build of VR Juggler.

Example 6.12. Initializing the Sonix Sound APi

snx::sonix::instance()->changeAPI("OpenAL");

Setting up a sound is designed to be simple, and an example of doing so is shown in Example 6.13. Setting Up a Sonix Sound Handle. Here, we use an instance of snx::SoundInfo to configure the sound object, which is in turn accessed by an instance of snx::SoundHandle.

Example 6.13. Setting Up a Sonix Sound Handle

snx::SoundInfo info;
info.filename = "crack.wav";
info.datasource = snx::SoundInfo::FILESYTEM;

snx::SoundHandle crack_sound("crack");
crack_sound.configure(info);

Periodically, an update function must be called to keep Sonix running. The method is snx::sonix::step(), and it takes a single argument of type float representing the time since the last time it was called. In general, this should be invoked in the frame function of an application. In the context of VR Juggler, this would be either preFrame() or postFrame() in the application object interface. An example of using this function is shown in Example 6.14. Sonix Frame Update.

Example 6.14. Sonix Frame Update

void MyApp::preFrame()
{
   // Update application state for the current frame
   // ...

   float time_delta = getTimeChangeInSeconds(); // use a system call or other API
                                                // to get the time delta
   snx::sonix::instance()->step(time_delta);
}

Example 6.15. Complete Sonix Program Using OpenAL

  1 #include <iostream>
    #include <string>
    #include <snx/sonix.h>
    
  5 int main(int argc, char* argv[])
    {
       std::string filename(:808kick.wav"), api("OpenAL");
    
       if ( ! snx::FileIO::fileExists(filename.c_str()) )
 10    {
          std::cout << "File not found: " << filename << "\n" << std::flush;
          return 1;
       }
    
 15    // start sonix using OpenAL
       snx::sonix::instance()->changeAPI(api);
    
       // fill out a description for the sound we want to play
       snx::SoundInfo sound_info;
 20    sound_info.filename = filename;
       sound_info.datasource = snx::SoundInfo::FILESYSTEM;
    
       // create the sound object
       snx::SoundHandle sound_handle;
 25    sound_handle.init("my simple sound");
       sound_handle.configure(sound_info);
    
       // trigger the sound
       sound_handle.trigger();
 30    sleep(1);
    
       // trigger the sound from a different position in 3D space
       sound_handle.setPosition(10.0f, 0.0f, 0.0f);
       sound_handle.trigger();
 35    sleep(1);
    
       // this simulates a running application
       while ( 1 )
       {
 40       snx::sonix::instance()->step(time_delta);
       }
    
       return 0;
    }

  1 // start sonix using OpenAL
    snx::sonix::instance()->changeAPI("OpenAL");
    
    // fill out a description for the sound we want to play
  5 snx::SoundInfo sound_info;
    sound_info.filename = "808kick.wav";
    sound_info.datasource = snx::SoundInfo::FILESYSTEM;
    
    // create the sound object
 10 snx::SoundHandle sound_handle;
    sound_handle.init("my sound for testing");
    sound_handle.configure(sound_info);
    
    // trigger the sound
 15 sound_handle.trigger();
    sleep(1);
    
    // trigger the sound using a different audio system
    snx::sonix::instance()->changeAPI("AudioWorks");
 20 sound_handle.trigger();
    sleep(1);
    
    // trigger our sound object using different source data
    sound_info.filename = "303riff.wav";
 25 sound_handle.configure(sound_info);
    sound_handle.trigger();
    sleep(1);
    

Design and Implementation of Sonix

Before we conclude this section on using Sonix directly in applications, we examine the design details of Sonix. These details are beyond the scope of what needs to be understood in order for Sonix to be utilized by VR Juggler applications, so readers not interested in these details can skip ahead to Using the VR Juggler Sound Manager.

Sonix was designed using modern software design principles including design patterns and object oriented design. The complete design of Sonix is depicted in UML in Figure 6.2. The Sonix Design. As evidenced by the diagram, the design of Sonix is quite simple, though the classes tend to have relatively large interfaces. Refer to the Sonix Programmer Reference, found on the Sonix documentaiton web page, for complete documentation of these interfaces.

Figure 6.2. The Sonix Design

Design Patterns Overview

Design patterns describe simple and elegant solutions to specific problems in object oriented software design. When designing Sonix, we used many design patterns appropriate for a simple audio system.

• Adapter (snx::SoundImplementation). This adapter provides a common interface to the underlying sound API.

• Prototype (snx::SoundImplementation). Making snx::SoundImplementation a Prototype allows a new cloned object to be created from it that has duplicate state.

• Store/plugin-method (snx::SoundFactory). Each sound implementation is registered with a Store called snx::SoundFactory. This Store allows users to select items from its inventory. Another name for Store is “Abstract Factory.”

• Abstract Factory (snx::SoundFactory). The Store can create new instances of the requested sound implementation. The Abstract Factory consults its Store of registered objects, and if found, makes a clone of that object (Prototype pattern). The Abstract Factory is used in Sonix to configure the Bridge.

• Bridge (snx::sonix interface class and snx::SoundImplementation). The snx::sonix class is the audio system abstraction which is decoupled from its implementation snx::SoundImplementation. This way the two can vary independently. Bridge also facilitates run-time configuration of the sound API.

• Proxy (std::string and snx::SoundHandle). snx::SoundHandle is how users manipulate their sound object. snx::SoundHandle is actually a proxy to a std::string proxy. The std::string Proxy is what allows Sonix reconfiguration of resources. Rather than using pointers which can easily be left to dangle, the std::string serves as a lookup for a protected sound resource located internally to the Sonix run-time memory space. The snx::SoundHandle wraps this std::string to provide a simple and familiar C++ object to use as the sound handle. The Sonix class acts as Mediator between every Proxy method and the actual audio system Adapter.

Pluggable Audio Subsystems

Sonix supports the selection of several audio subsystems by the application through implementation plug-ins (see Figure 6.3. Use of Plug-ins in Sonix). Each plug-in implements an adapter to an underlying audio subsystem. The adapter supports a common interface that Sonix knows how talk to. Each adapter is then registered with a factory object, which may ask that adapter to clone itself for use by whomever called the factory.

Figure 6.3. Use of Plug-ins in Sonix

Now that we understand how Sonix works and how to use its simple API, we can go one step further and simplify the usage even more. Similar to the graphics API-specific VR Juggler Draw Managers, there exists the concept of a Sound Manager. There is a Sonix-specific Sound Manager implementation that handles many of the details of Sonix usage.

The Sonix Sound Manager is configured using a config element of type sound_manager_sonix. The config element sets the sound API to use, defines the llistener position, and sets up all the sound objects that will be used by the application. All of this would normally have to be done by the application programmer using the snx::sonix singleton, as presented above in Basic Sonix Usage. In Example 6.17. Example Sonix Sound Manager Conifguration, we show a small example of configuring the Sonix Sound Manager. Note that some parts of the config file are removed for brevity. Aspects of this will be referenced in the code examples shown below.

<sound_manager_sonix version="1">
   <api>OpenAL</api>
   <listener_position>0.0</listener_position>
   <listener_position>0.0</listener_position>
   <listener_position>0.0</listener_position>
   <sound>
      <sound name="bump" version="1">
         <filename>${VJ_BASE_DIR}/share/vrjuggler/data/sounds/bump.wav</filename>
         <ambient>false</ambient>
         <retriggerable>false</retriggerable>
         <loop>1</loop>
         <pitch_bend>1.0</pitch_bend>
         <cutoff>1.0</cutoff>
         <volume>1.0</volume>
         <position>0.0</position>
         <position>0.0</position>
         <position>0.0</position>
      </sound>
   </sound>
   <sound>
      <sound name="step" version="1">
         <filename>${VJ_BASE_DIR}/share/vrjuggler/data/sounds/footstep.wav</filename>
         <ambient>false</ambient>
         <retriggerable>false</retriggerable>
         <loop>1</loop>
         <pitch_bend>1.0</pitch_bend>
         <cutoff>1.0</cutoff>
         <volume>1.0</volume>
         <position>0.0</position>
         <position>0.0</position>
         <position>0.0</position>
      </sound>
   </sound>
   <!-- Other sound objects ... -->
</sound_manager_sonix>

All sound files named in the config element are automatically loaded by the Sonix Sound Manager. User applications simply declare sound handles that refer to the loaded sound objects. The VR Juggler application class will then include one snx::SoundHandle instance for each sound object declared in the Sonix Sound Manager config element, as shown in Example 6.18. Declaring Sound Handles in Application Object Class. This is very similar to the use of Gadgeteer device interfaces that provide access to device input.

class MySoundApp : public vrj::opengl::App
{
public:
   void init();
   void preFrame();
   // Other application object interface methods ...

private:
   // Determines if the "bump" sound should be triggered.
   bool shouldTriggerBump();

   // Determines if the "step" sound should be triggered.
   bool shouldTriggerStep();

   snx::SoundHandle mBumpSound;
   snx::SoundHandle mStepSound;
   // And so on ...
};

To get access to the sounds through the snx::SoundHandle objects, the sound handles must be initialized. This is done in the same way as described earlier in the explanation of direct use of the Sonix API. The sound handle initialization should be performed in the init() method of the VR Juggler application object, as shown in Example 6.19. Initializing Sound Handles in an Application Object. The string value passed to snx::SoundHandle::init() is the name given in the Sonix Sound Manager config element. Again, we see similarity with the usage of Gadgeteer device interfaces.

void MySoundApp::init()
{
   mBumpSound.init("bump");
   mStepSound.init("step");
   // And so on ...
}

Finally, the sounds can be triggered in the application object preFrame() method, shown below in Example 6.20. Triggering Sounds in an Application Object. They should not be triggered in the draw() method because, as we have seen in earlier sections, draw() can be invoked multiple times per frame. There is no need to call the function snx::sonix::step() in preFrame() or in postFrame(). This is done automatically within the Sonix Sound Manager each time through the kernel control loop.

void MySoundApp::preFrame()
{
   if ( shouldTriggerBump() )
   {
      mBumpSound.trigger();
   }

   if ( shouldTriggerStep() )
   {
      mStepSound.trigger();
   }
}

Other methods in the snx::SoundHandle class interface can be invoked on the sound handle objects. We have focused on simple rendering of sounds here. Refer to the Sonix Programmer Reference, found on the Sonix documentation web page, for complete documentation on the interface of snx::SoundHandle.

Unlike the CAVElibs™ software, VR Juggler does not have to manage shared memory with other VR Juggler instances. Thus, when writing a VR Juggler application, memory can be created as in a normal, single-threaded C or C++ application.

As a result of the shared memory model described above, VR Juggler has different requirements for context-specific data than the CAVElibs™ software. Information such as display lists and texture objects must be managed using context-specific data. A display context is the location to which OpenGL rendering commands draw. Compiled OpenGL commands such as display lists do not get shared across multiple contexts (or windows), and thus, they must be initialized once per display context. In a VR Juggler application, these OpenGL initializations must be placed in vrj::opengl::App::contextInit(). It is called once per display context after each context has become active. For a more detailed description of these concepts and a tutorial on how to use them, please refer to Context-Specific Data.

  1 void app_shared_init();
    void app_compute_init();
    void app_init_gl();
    void app_draw();
  5 void app_compute();
    
    void main(int argc, char **argv)
    {
       CAVEConfigure(&argc,argv,NULL);
 10    app_shared_init(argc,argv);
       CAVEInit();
       CAVEInitApplication(app_init_gl,0);
       CAVEDisplay(app_draw,0);
       app_compute_init(argc,argv);
 15    while (!getbutton(ESCKEY))
       {
           app_compute();
       }
       CAVEExit();
 20 }

  1 class MyApplication : public vrj::opengl::App
    {
    public:
    // Data callbacks  (Do not put OpenGL code here)
  5    virtual void init();
       virtual void preFrame();
       virtual void intraFrame();
       virtual void postFrame();
          
 10 // OpenGL callbacks (put only OpenGL code here)
       virtual void contextInit();
       virtual void draw();
    };
    
 15 int main(int argc, char* argv[]) 
    {
       // configure kernel with *.config files
       vrj::Kernel* kernel = vrj::Kernel::instance(); // Get the kernel
       for(int i=1; i<argc; i++)
 20    {
          // loading config file passed on command line...
          kernel->loadConfigFile(argv[i]);
       }
    
 25    // start the kernel
       kernel->start();
    
       // set the application for the kernel to run
       MyApplication* application = new MyApplication();
 30    kernel->setApplication(application);
    
       // Block until the kernel exits.
       kernel->waitForKernelStop();
    
 35    return 0;
    }

VR Juggler is multi-threaded, and it uses a shared memory model across all threads. Thus, when writing a VR Juggler application, memory can be created as in a normal, single-threaded C or C++ application. VR Juggler is written entirely in C++, and as such, new and delete must be used instead of malloc() and free().

As a result of the shared memory model described above, VR Juggler has different requirements for context-specific data than GLUT. Information such as display lists and texture objects must be managed using context-specific data. A display context is the location to which OpenGL rendering commands draw. Compiled OpenGL commands such as display lists do not get shared across multiple contexts (or windows), and thus, they must be initialized once per display context. In a VR Juggler application, these OpenGL initializations must be placed in vrj::opengl::App::contextInit(). It is called once per display context after each context has become active. For a more detailed description of these concepts and a tutorial on how to use them, please refer to Context-Specific Data.

  1 void main(int argc, char* argv[])
    {
       /* initialize the application data here */
       OnApplicationInit();
  5 
       /* create a window to render graphics in
        * In VR Juggler, window creation is done for you based on your configuration file
        * settings.
        */
 10    glutInitWindowSize( 640, 480 );
       glutInit( &argc, argv );
       glutInitDisplayMode( GLUT_RGBA | GLUT_DEPTH | GLUT_DOUBLE );
       glutCreateWindow( "GLUT application" );
    
 15    /* display callbacks.
        * NOTE: the first time OnIdle is called is when you should 
        *       initialize the display context for each window
        *       (doing this is analogous to VR Juggler's 
        *       vrj::opengl::App::contextInit() function)
 20     */
       glutReshapeFunc( OnReshape );
       glutIdleFunc( OnIdle );
       glutDisplayFunc( OnIdle );
    
 25    /* tell glut to not call the keyboard callback repeatedly 
        * when holding down a key. (uses edge triggering, like the mouse does)
        */
       glutIgnoreKeyRepeat( 1 );
    
 30    /* keyboard callback functions. */
       glutKeyboardFunc( OnKeyboardDown );
       glutKeyboardUpFunc( OnKeyboardUp );
       glutSpecialFunc( OnSpecialKeyboardDown );
       glutSpecialUpFunc( OnSpecialKeyboardUp );
 35 
       /* mouse callback functions... */
       glutMouseFunc( OnMouseClick );
       glutMotionFunc( OnMousePos );
       glutPassiveMotionFunc( OnMousePos );
 40 
       /* start the application loop, your callbacks will now be called
        * time for glut to sit and spin.  In Juggler this is the same as the while(1)
        * (see below)
        */
 45    glutMainLoop();
    }

  1 class MyApplication : public vrj::opengl::App
    {
    public:
    // Data callbacks  (Do not put OpenGL code here)
  5    virtual void init();
       virtual void preFrame();
       virtual void intraFrame();
       virtual void postFrame();
          
 10 // OpenGL callbacks (put only OpenGL code here)
       virtual void contextInit();
       virtual void draw();
    };
    
 15 int main(int argc, char* argv[]) 
    {
       // configure kernel with *.config files
       vrj::Kernel* kernel = vrj::Kernel::instance(); // Get the kernel
       for(int i=1; i<argc; i++)
 20    {
          // loading config file passed on command line...
          kernel->loadConfigFile(argv[i]);
       }
    
 25    // start the kernel
       kernel->start();
    
       // set the application for the kernel to run
       MyApplication* application = new MyApplication();
 30    kernel->setApplication(application);
    
       // Block until the kernel exits.
       kernel->waitForKernelStop();
    
 35    return 0;
    }

The following code example shows the basics of declaring the class interface and data members for an application that will use context-specific data. This is an extension of the simple OpenGL application presented in Tutorial: Drawing a Cube with OpenGL. Note the addition of the contextInit() declaration and the use of the context-specific data member mCubeDlId.

  1 using namespace vrj;
    
    class MPApp : public opengl::App
    {
  5 public:
       MPApp() {;}
       virtual void init();
       virtual void preFrame();
       virtual void draw();
 10    virtual void intraFrame();
        ...
    public:
       // The Mesh object used for computing and rendering.
       Mesh mMesh;
 15    ...
    };

We now show the implementation of MPApp::preFrame(). In the initial version of the application, the computation for the mesh animation is done here.

  1 void MPApp::preFrame()
    {
       mCurTime += 0.005;
       mMesh.compute(mCurTime);
  5 
       // Other once-per-frame operations follow ...
    }

When we enter draw(), the computations for this frame's animation are complete. Thus, we can call the render() method to display the new calculations.

  1 using namespace gmtl;
    
    void MPApp::draw()
    {
  5    glClear(GL_DEPTH_BUFFER_BIT);
    
       // --- Setup for drawing --- //
       glMatrixMode(GL_MODELVIEW);
    
 10    glColor3f(0.0f, 0.5f, 0.75f);
       glPushMatrix();
          glScalef(15.0f,15.0f,15.0f);
          glRotatef(-90.0f,1.0,0.0,0.0);
          mMesh.render();                // Render the mesh
 15    glPopMatrix();
    }

In the tutorial application code, perform the computations asynchronously to the rendering process by using intraFrame(). Recall from vrj::App::intraFrame() (in Frame Functions) that intraFrame() is invoked in parallel to the execution of draw().

When considering multi-threaded programming, it is important to know that with great power comes great responsibility. The power is being able to provide multiple threads of control in a single application. The responsibility is making sure those threads get along with each other and do not step on each other's data. VR Juggler is a multi-threaded library which makes it very powerful and very complex.

As a cross-platform framework, VR Juggler uses an internal threading abstraction that provides a uniform interface to platform-specific threading implementations. That cross-platform interface is available to programmers to make applications multi-threaded without tying them to a specific operating system's threading implementation.

The threading interface in VPR is modeled after the POSIX thread specification of POSIX.1b (formerly POSIX.4). The main difference is that VPR's interface is object-oriented while POSIX threads (pthreads) are procedural. The basic principles are exactly the same, however. A function (or class method) is provided to the vpr::Thread class, and that function is executed in a thread of control that is independent of the creating thread.

Threads are spawned (initialized and begin execution) when the vpr::Thread constructor is called. That is, when instantiating a vpr::Thread object, a new thread of execution is created. The semantics of threads says that a thread can begin execution at any time after being created, and this is true with vpr::Threads. Do not make any assumptions about when the thread will begin running. It may happen before or after the constructor returns the vpr::Thread object. If the thread fails to spawn, an exception of type vpr::IllegalArgumentException, vpr::ResourceException, or vpr::Exception is thrown from the vpr::Thread constructor.

Passing arguments to threads can done through the thread functor. An argument is not required, of course, but any number of arguments can be passed by using boost::bind(). We explain more about that in the following section (see Thread Functors).

Once a vpr::Thread object is created, it acts as an interface into controlling the thread it encapsulates. Thread signals can be sent, priority changes can be made, execution can be suspended, etc. This interface is the focus of this section.

In this section, we explain the concept and use of functors. As with much of VR Juggler, a functor is a high-level concept that encapsulates something quite simple. A functor is defined as “something that performs an operation or a function.” While this is not very detailed, it is clear and concise. In VPR, functors can be used as the code executed by a thread.

In VPR, a functor is simply another object type that happens to encapsulate a user-defined function. The details on how this is done are not important here; what is important to know is that a functor can be thought of as a normal function. When using them, programmers simply implement callable code (a free function, a static member function, a non-static member function—virtual or non-virtual, or a class that overloads operator()) and then pass a reference to the callable to the boost::function<T> constructor. Boost.Function does the rest, and it does its job very well.

If the callable code takes parameters, they must be bound to the functor instance using boost::bind(). boost::bind() creates a new functor with a different signature than the original. For thread functors, the functor signature must match the Boost.Function type boost::function<void()> (or the portable form boost::function0<void>). The C type is void(*)(). No matter how we say it, this means a function that takes no arguments and returns nothing. With boost::bind(), however, we can have our thread functor take any number of arguments. Indeed, boost::bind() is required to use a class member function as a thread functor, and we will get back to that case shortly.

First, let us look at some examples of creating thread functors. In the first example (Example 10.1. Thread Functors from Free Functions), we have two free functions and a class that creates threads to call those functions. The first function, threadFunc(), takes no arguments. The creation of the vpr::Thread object assigned to mThread0 in MyClass::startThreads() is therefore very simple. The second function, threadFuncArgs() takes two arguments: a constant 32-bit integer and a reference to a vector of 32-bit integers. In this case, we have to use boost::bind() to bind function parameter to the functor. Notice that the vector is passed by reference, and we have to use boost::ref() (declared in boost/ref.hpp) to indicate this fact. Otherwise, mResults would be copied into the functor object, and no results would ever be available to the instance of MyClass. For objects that are to be passed by constant reference, use boost::cref().

#include <vector>
#include <boost/bind.hpp>
#include <boost/ref.hpp>
#include <vpr/Thread/Thread.h>

bool gDoWork(true);

void threadFunc()
{
   while ( gDoWork )
   {
      // Do work ...
   }
}

void threadFuncArgs(const int val, std::vector<int>& vecRef)
{
   for ( int i = 0; i < val; ++i )
   {
      vecRef.push_back(computeResult(i));
   }
}

int computeResult(const int input)
{
   // Do expensive operation on input ...
}

class MyClass
{
public:
   MyClass()
      : mThread0(NULL)
      , mThread1(NULL)
   {
   }

   ~MyClass()
   {
      // Stop threadFunc().
      gDoWork = false;

      // Wait for mThread0 to complete and delete it.
      if ( NULL != mThread0 )
      {
         mThread0->join();
         delete mThread0;
         mThread0 = NULL;
      }

      // Wait for mThread1 to complete and delete it.
      if ( NULL != mThread1 )
      {
         mThread1->join();
         delete mThread1;
         mThread1 = NULL;
      }
   }

   void startThreads()
   {
      mThread0 = new vpr::Thread(threadFunc);

      // Create a thread that adds 100 results to mthResults.
      mThread1 = new vpr::Thread(boost::bind(threadFuncArgs, 100,
                                             boost::ref(mResults)));
   }

   const std::vector<int>& getResults()
   {
      // Wait for mThread1 to complete its work on mResults.
      if ( NULL != mThread1 )
      {
         mThread1->join();
      }

      return mResults;
   }

private:
   vpr::Thread* mThread0;
   vpr::Thread* mThread1;
   std::vector<int> mResults;
};

The next example, Example 10.2. Thread Functor from a Static Member Function, demonstrates the use of a static member function as the thread functor. The usage of vpr::Thread is very similar to what we saw above with free functions. Since static member functions of a class are closely related to free functions, this is to be expected.

#include <vpr/Thread/Thread.h>

class MyClass
{
public:
   MyClass()
      : mThread(NULL)
   {
   }

   ~MyClass()
   {
      // Stop threadFunc().
      mDoWork = false;

      // Wait for mThread to complete and delete it.
      if ( NULL != mThread )
      {
         mThread->join();
         delete mThread;
         mThread = NULL;
      }
   }

   void startThread()
   {
      mThread = new vpr::Thread(MyClass::threadFunc);
   }

private:
   static void threadFunc()
   {
      while ( mDoWork )
      {
         // Do work ...
      }
   }

   static bool mDoWork;
   vpr::Thread* mThread;
};

bool MyClass::mDoWork(true);

Now, we have what is likely to be the most common usage of vpr::Thread. Namely, the use of a non-static class member function as the thread functor. In Example 10.3. Thread Functor from a Non-Static Member Function, we see how boost::bind() is used to make the functor that is passed to the vpr::Thread constructor. This is example of vpr::Thread usage is almost identical to that shown in Example 10.2. Thread Functor from a Static Member Function. The key differences are the lack of the static keyword and the use of boost::bind(). Remember that boost::bind() can be used for passing arguments into the function executed in the spawned thread, so we can combine ideas from the free functions example (Example 10.1. Thread Functors from Free Functions) with the binding of the this variable to the non-static member function. Simply put the arguments to be bound after the this parameter in the call to boost::bind().

#include <vpr/Thread/Thread.h>

class MyClass
{
public:
   MyClass()
      : mThread(NULL)
      , mDoWork(true)
   {
   }

   ~MyClass()
   {
      // Stop threadFunc().
      mDoWork = false;

      // Wait for mThread to complete and delete it.
      if ( NULL != mThread )
      {
         mThread->join();
         delete mThread;
         mThread = NULL;
      }
   }

   void startThread()
   {
      mThread = new vpr::Thread(boost::bind(&MyClass::threadFunc,
                                            this));
   }

private:
   void threadFunc()
   {
      while ( mDoWork )
      {
         // Do work ...
      }
   }

   bool mDoWork;
   vpr::Thread* mThread;
};

#include <vpr/Thread/Thread.h>

class Callable
{
public:
   Callable()
      : mDoWork(true)
   {
   }

   void stop()
   {
      mDoWork = false;
   }

   void operator()()
   {
      while ( mDoWork )
      {
         // Do work ...
      }
   }

private:
   bool mDoWork;
};

class MyClass
{
public:
   MyClass()
      : mThread(NULL)
   {
   }

   ~MyClass()
   {
      // Stop the functor().
      stopThread();

      // Wait for mThread to complete and delete it.
      if ( NULL != mThread )
      {
         mThread->join();
         delete mThread;
         mThread = NULL;
      }
   }

   void startThread()
   {
      mThread = new vpr::Thread(mFunctor);
   }

   void stopThread()
   {
      mFunctor.stop();

      if ( NULL != mThread )
      {
         mThread->join();
      }
   }

private:
   Callable     mFunctor;
   vpr::Thread* mThread;
};

What we have not yet seen is how to handle the case of a thread failing to spawn. In this case, an exception will be thrown from the vpr::Thread constructor when using the auto-spawning constructor. Otherwise, if the other vpr::Thread constructor is used (the non-spawning form), the exception handling would have to be around the invocation of vpr::Thread::start(). The case for the auto-spawning constructor is shown in Example 10.5. Handling Thread Spawn Failure. In general, it would be sufficient to catch vpr::Exception alone since the others are subclasses of that type.

try
{
   // Nothing will be assigned to mThread if an exception is
   // thrown from the constructor.
   mThread = new vpr::Thread(/* Args here... */);
}
// No thread functor was set.
catch (vpr::IllegalArgumentException& ex)
{
   // Handling code...
}
// The platform-specific thread object could not be allocated.
catch (vpr::ResourceException& ex)
{
   // Handling code...
}
// Something else went wrong during thread allocation.
catch (vpr::Exception& ex)
{
   std::cerr << ex.what() << std::endl;
}

The most important part of multi-threaded programming is proper thread synchronization so that access to shared data is controlled. Doing so results in consistency among all threads. Semaphores are a very common synchronization mechanism and have been used widely in concurrent systems. This short section describes the cross-platform semaphore interface provided with and used by VPR. It does not explain what semaphores are or how to use them—it is assumed that readers are already familiar with the topic lest they probably would not be reading this chapter on advanced classes at all.

As with threads, a cross-platform abstraction layer has been written into VPR to provide a consistent way to use semaphores on all supported platforms. The primary goal behind the interface design is to provide the common P (acquire) and V (release) operations. A given semaphore controls access to n resources. Thus, n threads can acquire a semaphore without blocking, but the n + 1 attempt to acquire the semaphore will block until a resource release occurs. The interface does include methods for read/write semaphores, but as of this writing, that part of the interface is not complete.

In addition to cross-platform semaphores, VPR provides an abstraction for cross-platform mutexes. Mutexes are a special type of semaphore known as a binary semaphore. Exactly one thread can hold the lock at any time. This very short section, however, is not about mutexes but rather about the vpr::Mutex interface provided with VPR and used by VR Juggler.

The cross-platform mutex abstraction in VPR is critical for synchronizing access to shared data. Those who have read the section on vpr::Semaphore will find this section very, very familiar. The interface for vpr::Mutex is a subset of that for vpr::Semaphore since mutexes are binary semaphores. In other words, they control access to exactly one resource. They can be locked and unlocked. That is all there is to know. The vpr::Mutex interface does include some methods for read/write mutexes, but this implementation is incomplete and is not documented here for that reason. When the implementation is finished, this documentation will be expanded.

To work around this, we can use multiple buffers. More specifically, we will use three buffers: one for reading, one for writing, and one as temporary storage of the most recently completed write(s). This is called triple buffering, and it allows us to perform computation and rendering in parallel without causing one process to wait on the other. The rendering buffer can be accessed without locking, as can the computation buffer. The only time a lock must be held is when the latest computations are copied into the temporary storage buffer or when the contents of the temporary storage buffer are copied into the rendering buffer. Thus, the key to triple buffering is the temporary storage buffer.

Implementing triple buffering is relatively straightforward, once the basic idea is understood. For this discussion we will refer to the buffers as follows:

Of the three, Working Copy is the only one that is shared between the threads, and thus, only one mutex must be used. The mutex must be locked when swapping the contents of Stable and Working Copy and when swapping the contents of Working and Working Copy. No lock must be held when reading from Stable or when writing to Working. This is where the major benefit of triple buffering is realized.

In the thread that will write to Working, the implementation will follow this basic structure:

while ( KeepWriting )
{
   Write to Working

   Lock Working Copy mutex
      Swap Working and Working Copy
   Unlock Working Copy mutex
}

In the thread that will read from Stable, the implementation is (roughly) the reverse:

while ( KeepReading )
{
   Lock Working Copy mutex
      Swap Stable and Working Copy
   Unlock Working Copy mutex

   Read from Stable
}

It is possible to optimize triple buffering to reduce the amount of time spent in the locked section. Instead of swapping the buffers, we can swap the pointers to the buffers. The result is that we only have to swap (up to) eight bytes of memory, regardless of the size of the actual data.

A very simple way to implement this is to use a three-element array to hold the buffers and three variables to use as the indices into the array. The variables can be named stable, working, and working_copy, for example. All accesses into the array of buffers use one of those three values. In other words, the thread reading from Stable will use buffer[stable] to get its buffer. Similarly, the thread writing to Working will use buffer[working]. Swapping the buffers simply involves changing the values of stable and working_copy or working and working_copy.

In the thread that will perform the writing, the pseudo-code for swapping is as follows:

Lock Working Copy mutex
   temp = working
   working = working_copy
   working_copy = working
Unlock Working Copy Mutex

Similarly, in the thread that will perform the reading, the pseudo-code for swapping is as follows:

Lock Working Copy mutex
   temp = stable
   stable = working_copy
   working_copy = stable
Unlock Working Copy Mutex

In these examples, it takes three memory copies to swap the two values. Use of the temporary storage is required (at the C/C++ level), and thus, swapping the memory cannot be done any faster, regardless of the size of the data buffers.

Triple buffering can be used in VR Juggler applications in two ways: in intraFrame() or in a separate thread. In both cases, the operations will happen asynchronously to the draw() thread, so the uses are roughly equivalent. Using intraFrame() is easier than creating a separate thread because the parallel processing comes “for free” with intraFrame(). No special actions must be taken on the part of the application developer. Programmers must keep in mind, however, that if the computations will take longer than the rendering, the application frame rate will drop. This is because the next frame cannot start until after intraFrame() completes. Thus, using a thread will increase the complexity of the application code somewhat, but it will ensure that the frame rate will not be adversely affected.

In this tutorial, we will use MPApp again to do parallel computation and rendering. This time, however, we will use triple-buffered, protected data instead of simply writing in intraFrame() and reading (simultaneously) in draw(). It will be best to begin with an unmodified version of MPApp to ensure that no changes made for the previous tutorial affect this exercise.

Using the information presented earlier in this section, the exercise is to extend the Mesh class (found in Mesh.h) so that it uses triple buffering for computation and rendering. It is up to the reader to decide whether to use threads (refer to the documentation for vpr::Thread in vpr::Thread and in the online Programmer Reference) or to use intraFrame(). Either way, a single vpr::Mutex instance will be needed, so it may be helpful to review Using the vpr::Mutex Interface as well.

The first step in adding dynamic reconfiguration capabilities to an application is to decide what aspects of the application should be configurable. Naturally, this is very application-specific, but some of the following choices are common:

Once decisions are made regarding configuration information, it is time to define the kinds of configuration elements that will contain it. This essentially means creating a file containing one or more configuration definitions. To understand this better, consider the following example. One might define an “Object” definition in an application. The definition would have properties that include the name and type of an object, its color and size, and so forth.

There are several ways to ensure that custom configuration definitions are read by the application. One way is to load the definition file explicitly (described below), but the simplest way is to include the custom definition file from one of the configuration files the application loads at startup. Instructions for editing configuration definition files and creating new kinds of definitions are included in the VRJConfig User's Guide.

The next step is to implement the dynamic reconfiguration interface for the application object. This interface is defined by the jccl::ConfigElementHandler class and consists of three methods:

When an application receives a configuration element to process via configAdd() or configRemove(), it needs to retrieve the data in that element in order to decide what to do. Configuration elements can be very complex, but the interface has been designed to be as simple as possible. We now describe a few of the most important methods in the jccl::ConfigElement API.

For definitive information about the jccl::ConfigElement API, refer to the JCCL Programmer's Reference.

The following application class is called ConfigApp. It is derived from vrj::opengl::App and has custom configCanHandle(), configAdd(), init(), and draw() methods declared. Note that the application declares several device interface members that are used by the application for getting device data.

  1 using namespace vrj;
    using namespace gadget;
    
    class simpleApp : public GlApp
  5 {
    public:
       simpleApp();
       virtual bool configCanHandle(jccl::ConfigElementPtr element);
       virtual bool configAdd(jccl::ConfigElementPtr element);
 10    virtual void init();
       virtual void draw();
    
    public:
       PositionInterface mWand;
 15    DigitalInterface mButtons[3];
    
       GLfloat mSurfaceColor_ll[3];
       GLfloat mSurfaceColor_lr[3];
       GLfloat mSurfaceColor_ur[3];
 20    GLfloat mSurfaceColor_ul[3];
    };

In the example application ConfigApp, we will see how to configure the color of the ground in the 3D scene using JCCL. The configuration is based on a configuration element definition that defines four properties, each with three values. The ground is defined as a rectangular polygon, and each property corresponds to one of the corners of the rectangle. The values of the property are the red, green, and blue values for the color of the corresponding corner vertex.

In Example 11.1. Complete listing of config_app.jdef, we show all of config_app.jdef. This contains many key pieces of information. The “name” attribute defines the type of the configuration element(s) that will appear in a configuration file. In our case, our config element type is “config_app.” Under the definition_version tag, the category for our configuration element is defined to be “Application.” This is done to indicate that this is an application-specific configuration definition. Finally, we see the property description for the corner colors, each of which has three floating-point values. The values have defaults of 1.0 for red, 0.0 for green, and 0.0 for blue. As such, the lower left corner vertex color defaults to red. The property definitions for the other three corners are similar.

<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings definition.version="3.1"?>
<definition xmlns="http://www.vrjuggler.org/jccl/xsd/3.1/definition"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.1/definition http://www.vrjuggler.org/jccl/xsd/3.1/definition.xsd"
            name="config_app">
   <definition_version version="1" label="ConfigApp configuration">
      <help>This is an application-specific configuration definition for use with the ConfigApp OpenGL sample application.</help>
      <parent/>
      <category>/Application</category>
      <property valuetype="float" variable="false" name="lower_left_color">
         <help>Specifies the RGB values for the lower left corner color.</help>
         <value label="Red value" defaultvalue="1.0"/>
         <value label="Green value" defaultvalue="0.0"/>
         <value label="Blue value" defaultvalue="0.0"/>
      </property>
      <property valuetype="float" variable="false" name="lower_right_color">
         <help>Specifies the RGB values for the lower right corner color.</help>
         <value label="Red value" defaultvalue="1.0"/>
         <value label="Green value" defaultvalue="0.0"/>
         <value label="Blue value" defaultvalue="0.0"/>
      </property>
      <property valuetype="float" variable="false" name="upper_right_color">
         <help>Specifies the RGB values for the upper right corner color.</help>
         <value label="Red value" defaultvalue="1.0"/>
         <value label="Green value" defaultvalue="0.0 "/>
         <value label="Blue value" defaultvalue="0.0"/>
      </property>
      <property valuetype="float" variable="false" name="upper_left_color">
         <help>Specifies the RGB values for the upper left corner color.</help>
         <value label="Red value" defaultvalue="1.0"/>
         <value label="Green value" defaultvalue="0.0 "/>
         <value label="Blue value" defaultvalue="0.0"/>
      </property>
      <upgrade_transform/>
   </definition_version>
</definition>

Using this configuration definition, we can create an instance of our configuration type in a configuration file. An example instance is shown in Example 11.2. ConfigApp.jconf. Here, we see the configuration for all four corners of the rectangular ground polygon. Note also that no special steps have to be taken in the configuration file to load the definition file. This is handled automatically by the JCCL Configuration Manager as long as the environment variable $JCCL_DEFINITION_PATH includes the directory where config_app.jdef sits. A typical way of setting this environment variable for this application would be the following:

% JCCL_DEFINITION_PATH = $VJ_BASE_DIR/share/vrjuggler/data/definitions:$VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple/ConfigApp

<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
               name="ConfigApp Example Configuration"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">
   <elements>
      <config_app name="Config App Example" version="1">
         <lower_left_color>1.0</lower_left_color>
         <lower_left_color>0.0</lower_left_color>
         <lower_left_color>0.0</lower_left_color>
         <lower_right_color>1.0</lower_right_color>
         <lower_right_color>1.0</lower_right_color>
         <lower_right_color>0.0</lower_right_color>
         <upper_right_color>0.0</upper_right_color>
         <upper_right_color>1.0</upper_right_color>
         <upper_right_color>0.0</upper_right_color>
         <upper_left_color>0.0</upper_left_color>
         <upper_left_color>0.0</upper_left_color>
         <upper_left_color>1.0</upper_left_color>
      </config_app>
   </elements>
</configuration>

The implementation of configCanHandle() is located in ConfigApp.cpp. It will be invoked whenever a new configuration element is found, and its job is to tell the JCCL Configuration Manager if it can be handled or not. The full implementation is as follows:

bool ConfigApp::configCanHandle(jccl::ConfigElementPtr element)
{
   const std::string my_type("config_app");
   return my_type == element->getID();
}

We define the element type that the application knows how to handle (named “ConfigApp”, as shown above), and we return true if that type matches the type of the newly loaded configuration element.

When a configuration element matching our type is loaded, the method configAdd() is invoked. The parameter passed in is the full configuration element that was loaded. The job of configAdd() is to read the information from the configuration element and configure the application based on what is read. In this specific case, we will read color information used for coloring the ground polygon in the scene. A partial implementation of ConfigApp::configAdd() follows:

bool ConfigApp::configAdd(jccl::ConfigElementPtr element)
{
   const std::string ll_color("lower_left_color");

   // Get the color settings for the lower left corner (ll).
   for ( int i = 0; i < element->getNum(ll_color); ++i )
   {
      mSurfaceColor_ll[i] = element->getProperty<float>(ll_color, i);
   }

   // Get the color settings for the other three corners ...
}

Note that we are reading the values from the property named “lower_left_color.” While we know that there are three (3) values to read, we ask the configuration how many values it has just to be safe.

For this application, the draw() member function is not terribly interesting. It renders the ground, and the colors for the four vertices are set using the member variables. Of course, the values for these member variables are set using the configuration file, and that is the interesting aspect.

The class MyDelegate has a single data member, mLoadConfigs, that determines how instances of this class will respond to certain messages sent by NSApplication. The value will be changed if vrj::CocoaWrapper sends the -setLoadConfigs: message as a result of the property VRJConfigHandling being set in Contents/Resources/vrjuggler.plist.

Every NSObject subclass has a designated initializer. In the case of the VR Juggler NSApplication delegate, this is the basic -init method. The current usage of the application delegate requires that this method be the designated initializer, meaning that it is the only initializer that will be invoked upon creating the delegate instance. This limitation may be fixed in a future version of vrj::CocoaWrapper. If the custom delegate does not accept the -init message, then the inherited NSObject version will be used.

In the meantime, this is where all object initialization takes place. What this means exactly is up to the delegate author. In this case, we set the data member mLoadConfigs to YES, send our base class the -init message, and return the result. This last step (a widely used convention) is what must be done by any custom delegate implementation of -init.

This method is a unique aspect of the delegate as it is handled by vrj::CocoaWrapper. Specifically, vrj::CocoaWrapper will examine Contents/Resources/vrjuggler.plist to see if it contains the property VRJConfigHandling. If it does, it will send this message to the delegate instance with the value as it is set in the property list. This happens before the delegate object is handed off to the NSApplication singleton. The consequences of setting and using the VRJConfigHandling property were described in Application Execution.

A custom delegate does not have to implement this method. If it does not, the Objective-C runtime will print a warning on the console stating that the object does not receive this message. (A future version of vrj::CocoaWrapper may examine the delegate interface to determine if it receives the message just to avoid having that message printed.) It is up to the delegate author to determine if implementing this method is necessary and, if so, how it should behave. In our example, we set mLoadConfigs to the value of the parameter, just as VRJBasicDelegate does.

This method is used by NSApplication to allow customization of application shutdown. In the case of an application delegate instantiated and used by vrj::CocoaWrapper, it is critical that this method return the value NO. The VR Juggler kernel knows about vrj::CocoaWrapper and knows how to shut it down when the time is right. Because of that, we want the kernel to control the termination process.

When the application finishes launching, NSApplication sends this message to its delegate. In the case of VR Juggler, this is when we know that it is safe to allow threads for Gadgeteer input windows and VR Juggler graphics pipes to open windows. Until now, any such threads have been blocking on the global window lock, acquired when vrj::CocoaWrapper was instantiated. When the delegate receives this message, it is time to release that lock. Other operations can be performed in this method implementation, but this step is absolutely critical.

Now, we get to one of the methods used by NSApplication to tell its delegate when to open a single data file. Remember that our simple delegate just handles VR Juggler configuration files. Moreover, it is assuming (probably unsafely) that the only files that it will be given to load are VR Juggler configuration files.

In any case, NSApplication sends this message to its delegate at well-defined times. The response of our simple delegate is based on the value of mLoadConfigs. If it is true (set to YES), that means that our delegate will load configuration files as a result of the user double-clicking on .jconf files in the Finder or through the use of the open command. Loading of configuration files is done through the usual means of passing the file name to the vrj::Kernel instance. Note that we convert the NSString Unicode value to a UTF8 string because that is what vrj::Kernel::loadConfigFile() knows how to handle. A future version of VR Juggler may have proper Unicode support so that this step is not necessary.

Note that this method returns YES regardless of the value of mLoadConfigs. This has the effect of making NSApplication think that the file was loaded even if it was ignored. In some cases, it may make more sense to return NO instead. As with just about everything in the custom delegate, the exact response to this message is up to the author.

This method is the multi-file counterpart to -application:openFile:. The behavior is essentially the same except that it iterates over the contents of the given NSArray object and calls vrj::Kernel::loadConfigFile() for each of the contained NSString objects.