Introdution
-----------

oglstub - An OpenGL stub library.

Files
-----

dll.c		- Contains main shared library entry point which
                  checks environment variables which control the
                  behaviour of the stub library.

ogltrace.c     - Stubs for OpenGL calls.

wgltrace.c     - Stubs for WGL calls.

xgltrace.c     - Stubs for GLX calls.


Setup
-----

NT

Building makefile creates opengl32.dll.  Put this DLL in the
applications directory or into another directory in the LIB
path ahead of the directory which containts the system opengl32.dll.

IRIX:

Building makefile creates liboglstub.so.  Use this DSO
by setting the following environment variable.

set _RLDN32_LIST directory/liboglstub.so:DEFAULT

This directs the runtime linker to resolve the OpenGL, and
GLX symbols in this DSO before resolving them in libGL.so.

LINUX:

Building makefile create libGL.so.1.  Set then environment
variable LD_LIBRARY_PATH to the directory which contains this
DSO.  When the application executes, the run-time loader will
resolve the OpenGL and GLX symbols using this DSO.  Use the
ldd command to verify that the application is find the
correct libGL.so.


Usage
-----

Behaviour is controlled by a set of environment variables which 
must be defined at build time at the top of the oglstub.cxx 
source file.  As a result, changing behaviour of the stub library 
requires that the shared library be rebuilt.

Set/unset in olgstub.cxx.

*** These environment variables are a work in progress ***

NO_RAST : When set, all primitives are sent to the graphics
          subsystem using a stub vertex.  In this case, vertex 
	  coordinates passed in by the  application are ignored, 
          and the coordinates (1, 0), (1, 0, 0) or (1, 0, 0, 1) 
          are sent for each vertex depending upon the number of 
          coordinates required. 

          This behavior effectively is a method to eliminate 
          rasterization while maintaining geometric calculations 
          inorder to determine if an application is geometry 
          limited or fill limited.  If the performance of an
          application does not improve when the stub library
          is built with this variable defined, then an application 
          is most definitely geometry limited.  However, if the
          performance of an application improves when the
          stub library is used with this variable defined, it
          cannot be concluded that an application is fill 
          limited.  An increase in performance is a clue that
          perhaps an application is infact fill limited, but it
          is not definitive proof.  Further testing is required.

          This approach generates degenerate triangles which 
          have no area.  So, one caveat to be aware of is that
          some graphics subsystems may try and do something
          with these triangles instead of just discarding them.
          This may infact consume more rasterization time than 
          the original non-stubbed triangles did.  Simple testing 
          should uncover this, and if this is indeed the case, 
          then this test becomes invalid.
          
NO_GEOM : When set, vertex data is sent to the graphics subsystem
          as color data.  This maintains the data flow within the
          application but removes any required graphics processing.

NO_VERTEX : When set, no vertex data is sent to the graphics subsystem.
            In this case, glVertex functions are stubbed out and 
            simply return without doing any processing.

NO_NORMAL : When set, no normal data is sent to the graphics subsystem.
            This simulates the performance that can be achieved if no
            normal data were sent to the graphics system.  In this 
            case glNormal functions are stubbed out and simply return
            without doing any processing.

NO_TEXTURE : When set, no texture data is sent to the graphics 
             system.  In this case, glTexImage and glTexSubImage
             calls are stubbed out and simply return without sending 
             any texture data to the graphics subsystem.  This 
             functionality is useful to remove texture download 
             operations.  If performance improves when this variable 
             is defined, then texture downloads may be a bottleneck.

NO_PIXEL : When set, no pixel data is sent to the graphics subsystem.
           In this case, glDrawPixel calls are stubbed out and simply
           return without sending any pixel data to the graphics
           subsystem.  This mode of operation is useful to remove
           image down load time.  If the performance improves with
           this variable set, then image download time from host to
           graphics may be a bottleneck.

NO_DATA : When set, no vertex, normal, texture, or pixel data is sent 
          to the graphics subsystem.  All glVertex, glNormal, glTexImage,
          glTexSubImage and glDrawPixel functions are stubbed out and
          simply return after doing no processing.  Setting this variable
          is the same as setting NO_VERTEX, NO_NORMAL, NO_TEXTURE and
          NO_PIXEL.  This simulates an infinitely powerful graphics 
          system and the performance that could be achieved if the 
          graphics processing took no time.  

NO_PIXOPS : When set, all pixel operations are stubbed out.  As
            a result, all alpha testing, blending, logic op,
            dithering, fog, antialiasing, stippling, scissor
            and stencil operations are disabled.  Calls to
            glEnable for these operations simply return.

SHORT_NORMALS : When set, the normal vector (1, 0, 0) is sent as short
                integers to the graphics subsystem.  Normal vector
                values sent by the application are ignored.  This
                reduces the host-to-graphics bandwidth required by
                the application and simulates the performance that
                could be achieved if normals within the application
                were converted to short integers. 

NO_MATERIAL : When set, glMaterial calls are stubbed out so that calls
              to glMaterial functions simply return without providing
              any useful functionality.

COLOR_PRIM : When set, triangle strips are drawn in red, triangle fans
             in blue, independent triangles in green , quads in purple
             and quad strips in yellow to display the decomposition
             of the scene into the various primitive types. 

NO_LIGHT : When set, calls to enable lighting are ignored so that 
           lighting remains disabled within the application.

SMALL_LINE : When set, calls to glLineWidth are ignored.  This is
             useful to test the performance impact of wide lines
             which may not be hardware accelerated.  This simulates
             the ultimate line performance that can be obtained. 

*** Are there others which are missing? ***

