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

oglstub - An OpenGL stub library.  This library is used to "stub out"
          OpenGL functions when analyzing the performance of an 
          application.

Files
-----

dll.c		- Main shared library entry point.

ogltrace.c     - Stubs for OpenGL calls.

wgltrace.c     - Stubs for WGL calls.

xgltrace.c     - Stubs for GLX calls.


Setup
-----

Stub library behaviour is library is controlled by a set of
build-time environment variables.  The details of what each
variable do is outlined in detail below.  The variables are 
set by arguments specified on the 'make' command line.  
These arguments are:

no_rast: Enable NO_RAST environment variable. 
no_geom: Enable NO_GEOM environment variable. 
no_vertex: Enable NO_VERTEX environment variable. 
no_normal: Enable NO_NORMAL environment variable.
no_texture: Enable NO_TEXTURE environment variable.
no_pixel: Enable NO_PIXEL environment variable.
no_data: Enable NO_DATA environment variable.
no_pixops: Enable NO_PIXOPS environment variable.
no_snormal: Enable NO_SNORMAL environment variable.
no_material: Enable NO_MATERIAL environment variable.
color_prim: Enable COLOR_PRIM environment variable.
no_light: Enable NO_LIGHT environment variable.
small_line: Enable SMALL_LINE environment variable.

These arguments also specify unique names for the resulting 
DSO or DLL libraries so that more than one version of the stub 
library can exist at any one time.  OS specifics are outlined
below.

NT

Building makefile creates DLLs of the form opengl32_foo.dll
where 'foo' is one of the command line arguments to 'make'
specified above.  To use, rename the appropriate DLL to
opengl32.dll and place it in the applications directory or
in another directory in the PATH ahead of the directory
which contains the system opengl32.dll.

IRIX:

Building makefile creates DSOs of the form liboglstub_foo.so
where 'foo' is one of the command line arguments to 'make'
specified above.  To use, set the following environment
variable using the appropriate DSO.

set _RLDN32_LIST directory/liboglstub._fooso:DEFAULT

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

LINUX:

Building makefile creates DSOs of the form libGL_foo.so where
'foo' is one of the command lind arguments to 'make' specified
above.  To use, rename the appropriate DSO to libGL.so and
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 loading the correct libGL.so.  It may be necessary when
renaming the DSO to add a version number.


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.

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. 


