The only code that should execute in this function is calls to OpenGL drawing routines. It is permissible to read from input devices to determine what to draw, but application data members should not be updated in this function.

The draw() method should not be used to perform any time-consuming computations. Code in this member function should not change the state of any application variables.

The following application class is called simpleApp. It is derived from vrj::GlApp and has custom 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 void init();
       virtual void draw();
 10 
    public:
       PositionInterface mWand;
       PositionInterface mHead;
       DigitalInterface mButton0;
 15    DigitalInterface mButton1;
    };

The implementation of draw() is located in simpleApp.cpp. Its job is to draw the environment. A partial implementation follows.

  1 using namespace gmtl;
    
    void simpleApp::draw()
    {
  5    ...                                                     
       // Create box offset matrix
       Matrix44f box_offset;		
       const EulerAngleXYZf euler_ang(Math::deg2Rad(-90.0f), Math::deg2Rad(0.0f),
                                      Math::deg2Rad(0.0f));
 10    box_offset = gmtl::makeRot<Matrix44f>(euler_ang);
       gmtl::setTrans(box_offset, Vec3f(0.0, 1.0f, 0.0f));     
       ...
       glPushMatrix();                                         
          // Push on offset
 15       glMultMatrixf(box_offset.getData());
          ...
          drawCube();
       glPopMatrix();
       ...
 20 }

	This creates a gmtl::Matrix44f object that defines the offset of the cube in the virtual world.
	The new matrix is pushed onto the OpenGL modelview matrix stack.
	Finally, a cube is drawn.

In the above, there is no projection code in the function. When the function is called by VR Juggler, the projection matrix has already been set up correctly for the system. All the user application must do is draw the environment; VR Juggler handles the rest. In this example, the draw() member function renders a cube at an offset location.

Change the code so that the cube is drawn at the position of the wand instead of at the box_offset location.

As outlined in the VR Juggler architecture documentation, VR Juggler uses a single memory area for all application data. All threads can see the same memory area and thus share the same copy of all variables. This makes programming normal application code very easy because programmers never have to worry about which thread can see which variables. In the case of context-specific data, however, it presents a problem.

To understand the problem, consider an environment where we use a single display list. That display list is created to draw some object in the scene. We would like to be able to call the display list in our draw() method and have it draw the primitives that were captured in it.

The following class skeleton shows an outline of this idea. Do not worry for now that we do not show the code where we allocate the display list—that will be covered later. For now, we see that there is a variable that stores the display list ID (mDispListId), and we use it in the draw() method.

using namespace vrj;

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

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

Now, imagine that we have a VR system configured that needs more than one display window (a multi-wall projection system, for example). There is a thread for each display, and all the display threads call draw() in parallel.

Since all threads share the same copy of the variables, they all use the same mDispListId when calling glCallList(). This is an error because we call draw from multiple windows (that is, multiple OpenGL rendering contexts). The display list ID is not the same in each context. What we need, then, is a way to use a different display list ID depending upon the OpenGL context within which we are currently rendering. Context-specific data comes to the rescue to address this problem.

Context-specific data provides us with a way to get a separate copy of a variable for each OpenGL rendering context. This may sound daunting at first, but VR Juggler manages this special variable so that it appears just as a normal variable. The developer never has to deal with contexts directly. VR Juggler transparently ensures that the correct copy of the variable is being used.

The following shows how a context-specific variable appears in a VR Juggler application:

using namespace vrj;

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

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

This code looks nearly the same as the previous example. In this case, mDispListId is treated as a pointer, and it has a special template-based type that tells VR Juggler it is context-specific data. When defining a context-specific data member, use the vrj::GlContextData<T> template class and pass the “true” type of the variable to the template definition. From then on, it can be treated as a normal pointer.

Curious readers are probably wondering how all of this works. To satisfy any curiosity, we now provide a brief description.

The context data items are allocated using a template-based smart pointer class (vrj::GlContextData<T>). Behind the scenes, VR Juggler keeps a list of currently allocated variables for each context. When the application wants to use a context data item, the smart pointer looks in the list and returns a reference to the correct copy for the current context.

This is all done in a fairly light-weight manner. It all boils down to one memory lookup and a couple of pointer dereferences. Not bad for all the power that it gives.

With the background in how to make a context-specific data member and how to use it in a draw() member function, we can move on to how and where the context-specific data should be allocated. If we want to create a display list, we need to know where we should allocate it.

  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
   }
}

Rule 1 says that context-specific data should not be allocated in an application object's draw() method. We have already stated that the main reason is that draw() is called too many times, and it is called at the wrong time for allocation of context-specific data. To be more specific, the draw() method is called for each surface, or for each eye, every frame. Static context-specific data only needs to be allocated when a new window is opened. (Dynamic context-specific data is handled separately.)

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 the section called “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 contextApp : public GlApp
    {
  5 public:
       contextApp() {;}
       virtual void init();
       virtual void contextInit();
       virtual void draw();
 10     ...
    public:
       // Id of the cube display list
       GlContextData<GLuint> mCubeDlId;
       ...
 15 };

We now show the implementation of contextApp::contextInit(). Here the display list is created and stored using context-specific data. Recall Example 4.1, “Initializing context-specific data”, presented in the section called “Using Context-Specific Data”. That example was based on this tutorial application.

  1 void contextApp::contextInit()
    {
       // Allocate context specific data
       (*mCubeDlId) = glGenLists(1);
  5 
       glNewList((*mCubeDlId), GL_COMPILE);
          glScalef(0.50f, 0.50f, 0.50f);
          drawCube();
       glEndList();
 10    ...
    }

Now that we have a display list ID in context-specific data, we can use it in the draw() member function. We render the display list by dereferencing the context-specific display list ID.

  1 using namespace gmtl;
    
    void contextApp::draw()
    {
  5    // Get Wand matrix
       gmtl::Matrix44f wand_matrix(mWand->getData());
       ...
       glPushMatrix();
          glPushMatrix();
 10          glMultMatrixf(wand_mat.getData());    
             glCallList(*mCubeDlId);
          glPopMatrix();
          ...
       glPopMatrix();
 15 }

In the tutorial application code, replace the call to drawAxis() with a display list call.