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 five main chapters:

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 allocations 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 (vjApp) and a base class for each Draw Manager interface (vjPfApp, vjGlApp, etc.). See Figure 2.1 for a visual representation of the application interface hierarchy. The kernel interface defined in vjApp specifies methods for initialization, shutdown, and execution of the application. The Draw Manager interfaces specified in the vj*App classes define the API-specific functions necessary to render the virtual environment. For example, a Draw Manager interface could have functions for drawing the scene and for initializing context-specific information.

Figure 2.1. vjApp 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.

Previously, we explained how VR Juggler applications do not have a main() function. 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 VR Juggler 1.0 applications, there is a main(), but it only starts the VR Juggler kernel and gives the kernel the application to run.

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 <simpleApp.h>
    
    int main (int argc, char* argv[])
    {
  5    vjKernel* kernel = vjKernel::instance(); // Get the kernel             
       simpleApp* app   = new simpleApp();      // Create the app object      
    
       kernel->loadConfigFile(...);             // Configure the kernel       
       kernel->start();                         // Start the kernel thread    
 10    kernel->setApplication(app);             // Give application to kernel 
    
       while ( ! exit )
       {
         // sleep
 15    }
    }

	This line finds (and may create) the VR Juggler kernel. The kernel reference is stored in the handle so that we can use it later.
	We instantiate a copy of the user application object (simpleApp) here. Notice that we include the header file that defines the simpleApp class.
	This statement represents the code that will be in the main() function for passing configuration files to the kernel's loadConfigFile() method. These configuration files may come from the command line or from some other source. If reading the files from the command line, it can be as simple as looping through all the arguments and passing each one to the kernel.
	As a result of this statement, the VR Juggler kernel begins running. It creates a new thread of execution for the kernel, and the kernel begins its internal processing. From this point on, any changes made reconfigure the kernel. These changes can come in the form of more configuration files or in the form of an application object to execute. At this point, it is important to notice that the kernel knows nothing about the application. Moreover, there is no need for it to know about configuration files yet. This demonstrates how the VR Juggler kernel executes independently from the user application. The kernel will simply work on its own controlling and configuring the system even without an application to run.
	This statement finally tells the kernel what application it should run. The method call reconfigures the kernel so that it will now start invoking the application object's member functions. It is at this time that the application is now running in the VR system.

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; it makes up all the lines within the “while(running)” 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.

The OpenGL application base class adds several methods to the application interface that allow rendering of OpenGL graphics. The extensions to the base vjApp class are shown in Figure 2.4. In the following, we describe the method vjGlApp::draw(), the most important element of the interface. More details about the vjGlApp class are provided in the section called “OpenGL Applications”, found in Chapter 4.

Figure 2.4. vjGlApp interface extensions to vjApp

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. The following is a description of only two methods in the vjPfApp interface. More detailed discussion on this class is provided in the section called “OpenGL Performer Applications”, found in Chapter 4.

Figure 2.5. vjPfApp interface extensions to vjApp

The classes vjVec3 and vjVec4 are designed to work the same was as three- and four-dimensional mathematical vectors. That is, a vjVec3 object can be thought of as a vector of the form <x, y, z>. Similarly, a vjVec4 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 used typically 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. VR Juggler's vectors retain this generality and can be used wherever vectors come in handy.

vjVec3 and vjVec4, 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:

Knowing this and keeping in mind that vjVec3 and vjVec4 can be thought of at this high level, using them should be a snap.

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 either Math/vjVec3.h, Math/vjVec4.h, or both as necessary. 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 vjVec3s, but the example is equally applicable to vjVec4. To create a vjVec3, use the default constructor which initializes the vector to <0.0, 0.0, 0.0>:

vjVec3 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:

vjVec3 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 VR Juggler 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:

vjVec3 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:

vjVec3 vec1(1.0, 1.5, -1.0);

vec1.normalize();

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 ( vec.isNormalized() )
{
   // Go here if vec is normalized
}

This only works with vjVec3s, however.

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

vjVec3 vec1(1.0, 1.5, -1.0);
float length;

length = vec1.length();

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, the vjVec3 class (but not vjVec4) provides a method called lengthSquared() that returns the length of the vector without calculating the square root.

The VR Juggler 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:

vjVec3 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:

vjVec3 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:

vjVec3 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:

vjVec3 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 vjVec3, two conversion functions are provided for converting a vjVec3 to a pfVec3 and vice versa. The first works as follows:

vjVec3 vj_vec;
pfVec3 pf_vec;

// Do stuff to vj_vec...

pf_vec = vjGetPfVec(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 vjVec3, do the following:

pfVec3 pf_vec;
vjVec3 vj_vec;

// Do stuff to pf_vec...

vj_vec = vjGetVjVec(pf_vec);

Here again, pf_vec is passed by reference for efficiency, and vj_vec gets a copy of a vjVec3. Both of these functions are found in the header Kernel/Pf/vjPfUtil.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:

vjVec3 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 types of assignments of VR Juggler vectors.

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

vjVec3 vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);

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

or

vjVec3 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

vjVec3 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. VR Juggler's 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:

vjVec3 vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0);
float dot_product;

dot_product = vec1.dot(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:

vjVec3 vec1(1.0, 1.5, -1.0), vec2(1.5, 1.0, -1.0), vec3;

vec3 = vec1.cross(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.

vjVec3 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>.

vjVec3 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.

vjVec3 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>.

vjVec3 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 method xformFull() does this job. For the following example, assume that there is a vjMatrix transformation matrix xform_mat:

vjVec3 vec(1.0, 1.0, 1.0);

vec.xformFull(xform_mat);

Depending on the transformations contained within xform_mat, 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.

Besides full transformations, it is possible to apply all transformations in a matrix except translation. (The usefulness of this is left as an exercise for the reader.) Again assume that there is a vjMatrix transformation matrix xform_mat:

vjVec3 vec(1.0, 1.0, 1.0);

vec.xformVec(xform_mat);

In this case, all transformations in xform_mat except translation will be applied to vec. The naming convention here is not terribly helpful, but this documentation is intended to get around that.

The details behind vjVec3 and vjVec4 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 public member variable vec. For example, this access can be used in the following way:

vjVec3 pos(4.0, 1.0982, 10.1241);

glVertex3fv(pos.vec);

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 vec member variable 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 vec follows:

vjVec4 my_vec;

my_vec.vec[0] = 4.0;
my_vec.vec[1] = 1.0982;
my_vec.vec[2] = 10.1241;
my_vec.vec[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, vjMatrix 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 vjMatrix 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 vjMatrix. The class provides a degree convenience not found with a normal C++ array, especially when programming with OpenGL. The complications surrounding the vjMatrix 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 vjMatrix.

As a representation of mathematical matrices, vjMatrix 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 vjMatrix 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 vjMatrix 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 vjMatrix, make sure to include Math/vjMatrix.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 vjMatrix, the default constructor can be used. It initializes the matrix to be an identity matrix:

vjMatrix 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 vjMatrix 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:

vjMatrix 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 vjMatrix object, programmers can use either the overloaded [] operator or the overloaded () operator. The overloaded [] operator returns the specified row of the vjMatrix, 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:

vjMatrix 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:

vjMatrix 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 vjMatrix to another happens using the normal = operator as follows:

vjMatrix 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);
vjMatrix 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):

vjMatrix 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);
vjMatrix 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.equal(mat2) )
{
   // Go here if mat1 and mat2 are equal.
}

or

vjMatrix 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);
vjMatrix 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

vjMatrix 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);
vjMatrix 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:

vjMatrix mat1;
vjMatrix 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.transpose(mat2);

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

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

vjMatrix mat1;
vjMatrix 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.invert(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 vjMatrix: 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 vjMatrix objects.

vjMatrix 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);
vjMatrix 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);
vjMatrix mat3;

Using the add() method:

mat3.add(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 vjMatrix: 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 vjMatrix objects.

vjMatrix 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);
vjMatrix 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);
vjMatrix mat3;

Using the sub() method:

mat3.sub(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 vjMatrix: using the mult() method or using the overloaded * operator. We recommend the use of the mult()method, 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 vjMatrix objects.

vjMatrix 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);
vjMatrix 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);
vjMatrix mat3;

Using the mult() method:

mat3.mult(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:

vjMatrix 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);
vjMatrix 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.postMult(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:

vjMatrix 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);
vjMatrix 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:

vjMatrix 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);
vjMatrix 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.preMult(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 scale() method or the overloaded * and / operators that take a single scalar value and returns a vjMatrix. 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 scale() method works as:

vjMatrix 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);
vjMatrix mat2;

mat2.scale(3.0, mat1);

Using the overloaded * operator works as:

vjMatrix 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);
vjMatrix mat2;

mat2 = mat1 * 3.0;

or

vjMatrix 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);
vjMatrix mat2;

mat2 = 3.0 * mat1;

Using the overloaded / operator works as:

vjMatrix 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);
vjMatrix mat2;

mat2 = mat1 / 3.0;

In all cases, the result of the scaling is stored (via a copy) in mat2.

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

vjMatrix 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);

mat1.makeIdent();

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 vjMatrix, this can be done in one step:

vjMatrix 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);

mat1.zero();

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:

vjMatrix mat1;
float x_rot = 0.4, y_rot = 0.541, z_rot = 0.14221;

mat1.makeXYZEuler(x_rot, y_rot, y_rot);
mat1.makeZYXEuler(z_rot, y_rot, x_rot);
mat1.makeZXYEuler(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.

The rotation values can be read from a matrix that previously had one of the above operations applied to it. This is done as follows:

float x_rot, y_rot, z_rot;

mat1.makeXYZEuler(x_rot, y_rot, y_rot);
mat1.makeZYXEuler(z_rot, y_rot, x_rot);
mat1.makeZXYEuler(z_rot, x_rot, y_rot);

In real code, one would use only the call that is appropriate for extracting the rotation values from mat. The float variables are passed by reference to the method so that the rotation values can be returned in them.

In a matrix that has rotations about more than one axis, it may be useful to get a transformation matrix that constrains the rotation to certain axes. A method is provided to do just this. It is called constrainRotAxis(), and it is used as follows (assume that old_mat is already defined as a transformation matrix with rotations about all three axes):

vjMatrix new_mat;

old_mat.constrainRotAxis(true, false, false, new_mat);

The result of this is that new_mat is a transformation matrix containing all of old_mat's transformations with the exception that rotation is constrained about the x-axis alone. The first three arguments are Boolean values that specify the axis constraints for the x-, y-, and z-axes respectively. new_mat is passed by reference, and the results of the constrained transformations are stored in it.

Creating a direction cosine matrix is another part of the vjMatrix interface. The method requires values for the x-, y-, and z-axes of the secondary coordinate system in terms of the first. These must be passed as objects of type vjVec3. Use of the method is shown below (assuming that sec_x_axis, sec_y_axis, and sec_z_axis are already defined and have appropriate values):

vjMatrix mat;

mat.makeDirCos(sec_x_axis, sec_y_axis, sec_z_axis);

The result is that mat becomes a direction cosine matrix.

Converting a quaternion to its corresponding matrix is possible with vjMatrix objects. Two methods are provided to do this, each taking a different type of argument as the quaternion to be converted. The first takes a four-element array of floats:

vjMatrix mat;
float quat[4];

// Fill in quat...

mat.makeQuaternion(quat);

Here, quat is assigned its values appropriately. The other version takes a reference to a vjQuat object:

vjMatrix mat;
vjQuat quat;

// Fill in quat...

mat.makeQuaternion(quat);

The result in both cases is that mat is the transformation matrix represented by the quaternion.

To make a rotation matrix where the rotation is about a single axis, a simple method is provided as part of the vjMatrix interface. It takes the rotation about the axis in degrees and the axis vector as a vjVec3 object. Its use is as follows:

vjMatrix mat;
vjVec3 axis(1.0, 0.0, 0.0);

mat.makeRot(45.0, axis);

The makeRot() method causes mat to become a transformation matrix with only the given rotation. This rather boring example therefore illustrates making a transformation matrix with only a 45° rotation about the x-axis.

Further capabilities are available with the rotations. Similar to the preMult() and postMult() methods described earlier, one can perform pre-rotations and post-rotations in degrees about a given axis on a matrix. To do a pre-rotation, the code would look similar to the following:

vjMatrix mat1, mat2;
vjVec3 axis(1.0, 0.0, 0.0):

// Perform various transformations on mat2...

mat1.preRot(45.0, axis, mat2);

where axis is passed by reference. The result is that mat1 is a transformation matrix assigned the value of multiplying the given rotation by mat2 in that order. mat2 is passed by reference to improve efficiency.

To do post-rotation, the code is similar:

vjMatrix mat1, mat2;
vjVec3 axis(1.0, 0.0, 0.0):

// Perform various transformations on mat2...

mat1.postRot(mat2, 45.0, axis);

where axis is passed by reference. The result in both cases is that mat1 is a transformation matrix assigned the value of multiplying mat2 by the given rotation in that order. mat2 is passed by reference to improve efficiency. Note that for post-rotation, the matrix argument is given before the rotation arguments as a reminder that it comes first in the multiplication order.

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):

vjMatrix mat;
vjVec3 trans(4.0, -4.231, 1.0);

mat.makeTrans(trans);

or

vjMatrix mat;

mat.makeTrans(4.0, -4.231, 1.0);

The only difference between these two is that the first takes a reference to a vjVec3 object specifying the translation.

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

vjVec3 trans(4.0, -4.231, 1.0);

mat.setTrans(trnas);

or

mat.setTrans(4.0, -4.231, 1.0);

There are further extensions to translations. Similar to the preMult() and postMult() methods described earlier, one can perform pre-translations and post-translations on a matrix. To do a pre-translation, the code would look similar to the following:

vjMatrix mat1, mat2;
vjVec3 trans(4.0, -4.231, 1.0):

// Perform various transformations on mat2...

mat1.preTrans(trans, mat2);

(where trans is passed by reference) or

vjMatrix mat1, mat2;

// Perform various transformations on mat2...

mat1.preTrans(4.0, -4.231, 1.0, mat2);

The result in both cases is that mat1 is a transformation matrix assigned the value of multiplying the given translation by mat2 in that order. mat2 is passed by reference to both methods to improve efficiency.

To do post-translation, the code is similar:

vjMatrix mat1, mat2;
vjVec3 trans(4.0, -4.231, 1.0):

// Perform various transformations on mat2...

mat1.postTrans(mat2, trans);

(where trans is passed by reference) or

vjMatrix mat1, mat2;

// Perform various transformations on mat2...

mat1.postTrans(mat2, 4.0, -4.231, 1.0);

The result in both cases is that mat1 is a transformation matrix assigned the value of multiplying mat2 by the given translation in that order. mat2 is passed by reference to both methods to improve efficiency. Note that for post-translation, the matrix argument is given before the translation argument(s) as a reminder that it comes first in the multiplication order.

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

vjMatrix mat;

mat.makeScale(1.5, 1.5, 1.5);

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.

As with the previous operations, more advanced changes can be made. Similar to the preMult() and postMult() methods described earlier, pre-scale and post-scale operations can be performed on a matrix. To do a pre-scale, the code would look similar to the following:

vjMatrix mat1, mat2;

// Perform various transformations on mat2...

mat1.preScale(1.5, 1.5, 1.5, mat2);

The result in both cases is that mat1 is a transformation matrix assigned the value of multiplying the given scaling factors by mat2 in that order. mat2 is passed by reference to both methods to improve efficiency.

To do a post-scale, the code is similar:

vjMatrix mat1, mat2;

// Perform various transformations on mat2...

mat1.postScale(mat2, 1.5, 1.5, 1.5);

The result in both cases is that mat1 is a transformation matrix assigned the value of multiplying mat2 by the given scale factors in that order. mat2 is passed by reference to both methods to improve efficiency. Note that for post-scaling, the matrix argument is given before the scale factor arguments as a reminder that it comes first in the multiplication order.

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 vjMatrix object representing arbitrary translation, rotation, and scaling transformations. To get the roll information, use the following:

float roll = mat.getRoll();

or

float z_rot = mat.getZRot();

The value return is in the range -180.0° to 180.0°. To get the pitch information, use:

float pitch = mat.getPitch();

or

float x_rot = mat.getXRot();

Again, the value return is in the range -180.0° to 180.0°. Finally, to get the yaw information, use:

float yaw = mat.getYaw();

or

float y_rot = mat.getYRot();

Though it may not need to be restated, the value return is in the range -180.0° to 180.0°.

Getting translations is even simpler because translations are collected into a single vector easily. There are two forms for getting the translation. The first takes three floats by reference:

float x, y, z;

mat.getTrans(x, y, z);

After this, the translation in mat is stored in x, y, and z. The second form returns a copy of a vjVec3 object:

vjVec3 trans;

trans = mat.getTrans();

That is all there is to reading translations.

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

vjMatrix vj_mat;
pfMatrix pf_mat;

// Perform operations on vj_mat...

pf_mat = vjGetPfMatrix(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 vjMatrix, do the following:

pfMatrix pf_mat;
vjMatrix vj_mat;

// Perform operations on pf_mat...

vj_mat = vjGetVjMatrix(pf_mat);

Here again, pf_mat is passed by reference for efficiency, and vj_mat gets a copy of a vjMatrix. Both of these functions are found in the header Kernel/Pf/vjPfUtil.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

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 vjMatrix 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.

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

glMultMatrixf(mat.getFloatPtr());

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.

Physical devices are never accessed directly by VR Juggler applications. Instead, the applications are granted access to the device through a proxy. A proxy is nothing more than an intermediary who forwards information between two parties. In this case, the two parties are a VR Juggler application and an input device. The application makes requests on the input device through the proxy.

The class vjDeviceInterface is designed to be a wrapper class around the proxies. Applications could use the proxy classes directly, but vjDeviceInterface and its subclasses simplify use of the proxy object they contain. Thus, typical VR Juggler application objects will have one or more device interface member variables.

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 “magic” to occur 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 vjDeviceInterface uses these concepts. First, know that vjDeviceInterface is a base class for all other device interface classes such as digital interfaces (wand buttons), position interfaces (wands, a tracked user's head), etc. In user code, there will be instances of objects such as vjDigitalInterface, vjPosInterface, vjKeyboardInterface, and the like. Once they are properly initialized, device interface objects (whatever their types may be) will act as smart pointers to the actual VR Juggler proxy objects they wrap.

All the subclasses of vjDeviceInterface encapsulate a pointer to a VR Juggler proxy object. (Remember that these proxy objects act as an intermediary between the application and an input device.) The subclasses also overload the dereference operator -> which allows them to act as smart pointers. The dereference operator on a device interface object gives access to the object's hidden proxy pointer. With that access, the methods of the encapsulated proxy object can be invoked, usually to read data. The end result is that user applications get access to the proxy objects they need but through a simpler interface than using the proxies directly.

At this point, it is perfectly reasonable to wonder why VR Juggler uses a concept that requires all sorts of documentation and explanation. The extra effort is worth it because it allows VR Juggler 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 vjDigialInterface gives exactly that information, and it quietly hides the messiness of dealing with that crazy mouse, its ugly driver, and its overly complex protocol.

VR Juggler applications do not usually use vjDeviceInterface directly. Instead, the subclasses mentioned above will be used. Within this section, we will refer to subclasses of vjDeviceInterface as “device interfaces”. The high-level description has already made use of this convention.

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 init() method. Each device interface object inherits a method called init() from vjDeviceInterface. This method takes a single string argument naming the proxy to which the interface will connect. Example names are “VJHead”, “VJWand”, “VJButton0”, and “VJAccelerate”. These are all symbolic names specified in VR Juggler configuration files. This 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. VR Juggler 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 vjPosInterface that connects with the user head proxy is:

vjPosInterface head;

head.init("VJHead");

Remember that this is 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. This is best part! VR Juggler is already working hard in the background to update device proxies, and the application is free to access them. (It is usually best to reference them in the preFrame() method, but this may not necessarily be true for all proxies.) Continuing with our example of a vjPosInterface to the user head proxy, the following code shows how to read the transformation matrix for the user's head:

vjMatrix* head_mat;

head_mat = head->getData();

But wait, that was easy! Believe it or not, the code really is that simple. Simply use the overloaded dereference operator to get access to the position proxy object hidden in vjPosInterface to read data from the proxy. Of course, we have not explained the getData() method at all yet. That comes from the position proxy class, and that is documented elsewhere.

What is truly amazing about VR Juggler 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 header files as a reference.

As mentioned, the class vjDeviceInterface is a base class for all the specific types of device interfaces such as positional interfaces, digital interfaces, and analog interfaces. This class maintains the name of the proxy and the proxy index, and it provides the all-important init() method, but it is up to the inheriting classes to handle the proxy pointer and to overload the dereference operator.

Subclasses of vjDeviceInterface are used to provide the wrapper to a specific type of proxy. They each contain a pointer to a proxy object of the same conceptual type (positional, digital, and so on). The way in which the dereference operator is overloaded can vary from class to class, but the end result is always the same: a pointer to the proxy is returned so that the calling code has access to that proxy.

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 VR Juggler, and it is important to understand.

The class vjProxy is the base class for all the proxies in the VR Juggler Input Manager. A better name would be vjInputProxy, and it may help to think of it with that name. 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 programmers will probably never need to know more about a specific device proxy's interface than the return type of its getData() method. Most of the apparent complexity in the specific device proxy classes is only important to VR Juggler's internal maintenance of the active proxies.

That said, this section is relatively short. As a programmer, the important thing to know is that a proxy is a pointer to a physical device. Application programmers use the higher level device interface as the mechanism to read data in some form from the 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 VR Juggler in a meaningful way. That is a lot of indirection, but it makes the handling of physical devices by VR Juggler incredibly powerful.

To be blunt, application programmers do not use vjProxy. Instead, access to a subclass of vjProxy is given through a device interface acting as a smart pointer. The getData() method of that subclass is used. That method is the window into the soul of an input device. The device interface allows calling getData() for the specific proxy object it encapsulates, and the current state of the device pointed to by the proxy is returned.

Therefore, what must be known is the return type of the specific proxy to which access is granted through the device interface. The naming conventions for the proxies and their interfaces makes it relatively simple to determine which proxy object is being encapsulated by which device interface. For example, a vjDigitalInterface holds a vjDigitalProxy pointer. In that case, refer to the documentation for the vjDigitalProxy class and find the return type of getData() (int in this case). The proxy header files have the information, too. These are located in $VJ_BASE_DIR/Input/InputManager. Just search for the getData() methods therein.

The gory details of vjProxy and its subclasses are not really relevant to this particular section. The subclasses look complicated, and they can be. It is important to note, however, that the complication is part of the interface used internally by VR Juggler rather than the interface used by the application programmer. Because of that and because each device proxy class is different, those details will not be addressed here. It is sufficient to deal with getData() alone in applications. Leave the ugliness up to VR Juggler; it can handle it.

As described in previous chapters (see Chapter 1, for example), all VR Juggler applications derive from a base application object class (vjApp). 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 vjApp or from a Draw Manager-specific application class that has vjApp as a superclass. For example:

class userApp : public vjApp
{
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 vjApp. In most cases, an application class is derived from a Draw Manager-specific application class. For example:

class userGlApp : public vjGlApp
{
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 vjGlApp 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 vjApp
{
public:
   init();
   preFrame();
private:
   vjPosInterface mWand;
}

Note the declaration of the variable mWand of type vjPosInterface. 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.

...
vjMatrix wand_pos;
wand_pos = *(mWand->getData());
...

The above code shows an example of using the 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 the section called “The vjDeviceInterface Helper Class” for more information about using vjDeviceInterface.

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.

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 VR Juggler 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().

The most important (and visible) component of most OpenGL applications is the OpenGL drawing. The vjGlApp 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 vjGlApp::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 the section called “Why it is Needed” or to the section called “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:

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

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

class userApp : public vjGlApp
{
public:
  draw();
public:
  vjGlContextData<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 4.3. VR Juggler OpenGL system

In an application using OpenGL Performer, the scene graph must be initialized before it can be used. The method vjPfApp::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, vjPfApp::initScene() is invoked after the Performer functions pfInit() and pfConfig() but before vjApp::apiInit().

In order for Performer to render the application scene graph, it must get access to the scene graph root. The method vjPfApp::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 vjPfApp that extend the basic vjApp interface. Each is discussed in this section.

chan->clear();
pfDraw();

The following lists the draw, frame, and initialize routines used in the CAVElib™ software.

With VR Juggler, no C function pointers are necessary, but a pointer to an application object must be given to the VR Juggler kernel. As described in earlier sections of this chapter, the first step is to derive a new application class from vjGlApp. For more information on application objects, it may be helpful to review Chapter 2. Briefly, the application class definition would appear similar to the following:

class MyApplication : public vjGlApp
{
   ...
};

The draw, frame, and initialize routine concepts in VR Juggler are presented in the following list.

Readers who find some of these concepts unfamiliar are encouraged to read the section called “OpenGL Applications”. For information about context-specific data, refer to the section called “Context-Specific Data”.

To get tracking information, the following functions are used:

For button input, the following macros are used:

To get device input, use the classes derived from vjDeviceInterface. They include the following:

For more information about the VR Juggler device interfaces, refer to Chapter 3. A tutorial on getting device input in VR Juggler applications can be found in the section called “Getting Input”.

All configurable parameters go in a single file called .caverc. The configuration mechanism is proprietary and not usable by external VR system software. In particular, VR Juggler cannot get its configuration information from an existing .caverc file.

Configuration of VR Juggler is much more powerful and flexible than what is used by the CAVElib™ software. As a result, it is also more complex. All configurable parameters could be in one or more files with any names desired. VR Juggler comes with example configuration files that may be found in the directory $VJ_BASE_DIR/share/Data/configFiles.

The VR Juggler configuration system is completely extensible and could be used outside of VR Juggler. Indeed, it could be used outside of any VR paradigm altogether. Refer to the VjControl book for more information on configuring VR Juggler.

Unlike the CAVElib™ 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 CAVElib™ 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 vjGlApp::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 the section called “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 vjGlApp
    {
    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
       vjKernel* kernel = vjKernel::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);
    
       // hit CTRL-C to exit.
       while (1)
       {
 35       // Juggler executes within other threads, so sleep here.
          usleep( 100000 );
       }
    }

In GLUT, the initialize, draw, and frame routines are known as callbacks implemented with C function pointers. In VR juggler, the equivalent routines are called back using an application object. An application object is a C++ class that defines methods to encapsulate the functionality of the application within a single C++ object.

With VR Juggler, no C function pointers are necessary, but a pointer to an application object must be given to the VR Juggler kernel. As described in earlier sections of this chapter, the first step is to derive a new application class from vjGlApp. For more information on application objects, it may be helpful to review Chapter 2. Briefly, the application class definition would appear similar to the following:

class MyApplication : public vjGlApp
{
   ...
};

The draw, frame, and initialize routine concepts in VR Juggler are presented in the following list.

Readers who find some of these concepts unfamiliar are encouraged to read the section called “OpenGL Applications”. For information about context-specific data, refer to the section called “Context-Specific Data”.

For keyboard input, the following functions are used:

For mouse input, the following functions are used:

To get device input, use the classes derived from vjDeviceInterface. They include the following:

For more information about the VR Juggler device interfaces, refer to Chapter 3. A tutorial on getting device input in VR Juggler applications can be found in the section called “Getting Input”.

There is no built-in configuration system. All system settings are coded using the GLUT API.

VR Juggler has a powerful and flexible configuration system. As a result, it is also complex. All configurable parameters could be in one or more files with any names desired. VR Juggler comes with example configuration files that may be found in the directory $VJ_BASE_DIR/share/Data/configFiles.

The VR Juggler configuration system is completely extensible and could be used outside of VR Juggler. Indeed, it could be used outside of any VR paradigm altogether. Refer to the VjControl book for more information on configuring VR Juggler.

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 vjGlApp::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 the section called “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 
        *       vjGlApp::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 vjGlApp
    {
    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
       vjKernel* kernel = vjKernel::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);
    
       // hit CTRL-C to exit.
       while (1)
       {
 35       // Juggler executes within other threads, so sleep here.
          usleep( 100000 );
       }
    }

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.

void run(void* args);

vjThread* thread;

thread = new vjThread(run);

struct ThreadArgs
{
   int id;
   char name[40];
   // And so on...
};

void someFunc ()
{
   // Other code ...

   ThreadArgs* args;
   vjThread* thread;

   args = new ThreadArgs();

   // Fill in the elements of args ...

   thread = new vjThread(run, (void*) args);
}

vjThread* thread;

thread = new vjThread(run);

// Do other things while the thread is going ...

thread->join();

// Now that the thread is done, continue.

thread->suspend();

thread->resume();

int prio;

thread->getPrio(&prio);

int prio;

// Assign some priority value to prio ...

thread->setPrio(prio);

thread->kill(SIGINT);

thread->kill();

vjBaseThread* my_id;

my_id = vjThread::self();

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 VR Juggler, functors can be used as the code executed by a thread (refer to the section called “Using the vjThread Interface” for more detail on the topic of vjThreads). This section describes how to use functors for exactly that purpose.

void methodName(void* arg);

vjThreadMemberFunctor<MyObject>* my_functor;
thread_args_t* args;
vjThread* thread;

args = new thread_args_t();

// Fill in the arguments to be passed to the thread...

my_functor = new vjThreadMemberFunctor<MyObject>(my_obj, &MyObject::run, (void*) args);
thread = new vjThread(my_functor);

thread_args_t* args = new thread_args_t();

// Fill in args ...

my_functor->setArg(args);

vjThreadNonMemberFunctor* my_functor;
thread_args_t* args;
vjThread* thread;

args = new thread_args_t();

// Fill in the arguments to be passed to the thread...

my_functor = new vjThreadNonMemberFunctor(run, (void*) args);
thread = new vjThread(my_functor);

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 VR Juggler. 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.

vjSemaphore sema(5);

sema.reset(4);

sema.acquire();

sema.release();

In addition to cross-platform semaphores, VR Juggler 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 vjMutex interface provided with and used by VR Juggler.

vjMutex mutex;

mutex.acquire();

mutex.tryAcquire();

int state = mutex.test();

sema.release();

Using basic class declaration for MyNewButtonDevice from above, we will proceed with the implementation of the driver class. First, there are six member functions that must be implemented:

There are other methods that must be implemented depending on the classes from which a given driver class derives. In the joystick example given earlier, the method getAnalogData() would have to be implemented in addition to getDigitalData(). The prototype for getAnalogData() is:

virtual float getAnalogData(int devNum = 0)

The joystick driver would use this to return values for the X and Y axes. The data here is more complex because it would be for triple-buffered two-dimensional samples. An implementation might look similar to the following:

float MyNewJoystickDevice::getAnalogData(int axis)
{
   vjASSERT(axis >= 0 && axis <= 1 && "only 2 axes (x and y) available");
   return mSampledAnalogData[current][axis];
}

In this driver, the integer argument to the method is used to represent either the X or the Y axis. The assertion ensures that a valid axis index is passed.

Device driver registration is done through a templated constructor called vjDeviceConstructor. It is used as follows:

#include <Input/InputManager/vjDeviceFactory.h>

vjDeviceConstructor<MyNewButtonDevice>* this_ptr_not_used =
   new vjDeviceConstructor<MyNewButtonDevice>;

The new device driver can be compiled along with the vjDeviceConstructor call into a standalone library (.a, .so, .lib, and .dll are common). This library can then be linked with applications. In this way, there is no need to modify the VR Juggler source code to add a new driver. The driver code can be centralized into a single, neat driver that can be distributed as a “plug-in” for VR Juggler.

Before configuring a device, a new configuration chunk description must be created. We recommend that this be done using VjControl. For the button device, the chunk description will look similar to the following:

chunk MyButtonDevice "MyButtonDevice" "Configuration for my one-button device"
   Name String 1 "Name" "Unique name of an instance of this chunk type"
   port String 1 "Port" "Serial port this device is connected to"
   baud Int 1 "Baud Rate" "Serial port speed"
   end

For a real device, all of these parameters may or may not be needed. (In VR Juggler 1.0, vjInput requires baud and port, but this has been corrected in newer versions.) Again, the VjControl chunk description editor simplifies the creation of this description so that only the required elements are present.

Once the chunk description is in place, a new configuration chunk can be created. Once again, VjControl makes the step easier. The following is an example configuration file that configures the one-button device we have been using thus far:

vjincludedescfile
  Name "mybuttondevice.desc"
  end
MyButtonDevice
  Name"Button Device"
  port { "/dev/ttyd4" }
  baud { "9600" }
  end
End

In the driver, there are two methods that must be implemented in order to handle config chunks: