OpenGL Debugger README
May 7, 1999

Thomas J. True
true@sgi.com

Introduction:
-------------

This directory contains the latest NT OpenGL debugger images.

The OpenGL debugger on Windows NT can be invoked in two different
ways.  The first is by placing the OPENGL32.DLL in this directory
ahead of the system OPENGL32.DLL in your PATH.  The second is by
using the new command line interface which utilizes the OGLDEBUG.EXE
and OGLDEBUG.DLL files found in this directory.  

Also included in this directory is GLSPLAY.EXE, a standalone
application for playing back history files created with the
OpenGL debugger.


Files:
------

opengl32.dll - OpenGL debugger DLL, put this in your PATH ahead
               of the system OPENGL.DLL to invoke the OpenGL
               debugger each time an OpenGL application starts.

ogldebug.exe - OpenGL debugger command line executable.  This
               program and OGLDEBUG.DLL provide a command line
               interface to the debugger.  To invoke the debugger,
               put OGLDEBUG.DLL in your path and type 
               "ogldebug <application>."

ogldebug.dll - OpenGL debugger DLL for command line invocation.

glsplay.exe - Standalone history playback application.

gls32.dll - Streaming OpenGL DLL needed for glsplay.exe.

teapot.exe - Simple test application, requires TUMBLEQ.DLL which
             is also found in this directory.

tumbleQ.dll - Additional DLL needed for teapot.exe test application.

teapot.gls - Sample history file for testing glsplay.


Invoking the OpenGL Debugger:
-----------------------------

1) Automatically at Application Startup

Put OPENGL32.DLL into a directory which is in your path ahead of the
system OPENGL32.DLL.  Then, simply run the application, the debugger
will start on the first OpenGL call.

2) From the Command Line

Put OGLDEBUG.DLL and OGLDEBUG.EXE in your path.  From the command
line type "ogldebug <application name>."  If the application is
not in the current directory, the full path must be specified.
If the application name is ommitted, a File Open dialog box will be
displayed so that the applications .EXE may be specified.

3) Using the mouse.

Put OGLDEBUG.DLL and OGLDEBUG.EXE in the same directory to ensure 
that OGLDEBUG.DLL is in the path.  Double click on OGLDEBUG.EXE.
A File Open dialog box will be displayed so that the applications
.EXE may be specified.


Saving OpenGL Call History Traces
---------------------------------

In the OpenGL debugger, select Call History from the Information menu
and then select the GL context.  This should display a dialog box
which contains the OpenGL call history for the selected GL context
in addition to some GLS commands which encapsulate other information.
To save it, simply press the Save button.  This creates a GLS (OpenGL
Stream) file that can be used with the glsplay utility described 
below.


Playing Back History Traces Using glsplay:
------------------------------------------

After using the OpenGL debugger to save a history trace.  On the command
line simply type "glsplay <history file>" giving the fully qualified
path to the history file if necessary.  The glsplay application will
bring up a window.  To start playback press the Play button,  to quit 
press the Done button.  Like all NT application, glsplay must be in 
your current working directory or in your PATH to execute.


Known Problems:
---------------

1. The command line version of the OpenGL debugger does not work
   with some applications due to the way the applications invoke
   OpenGL at startup.

2. On the SGI 320 and 540, versions 4.0.x of the ICD (installable 
   client driver) for OpenGL do not recognize SwapBuffer calls from 
   the OpenGL debugger OPENGL32.DLL.  A work around in previous 
   versions of this DLL, which forced applications to run in 
   single-buffer mode has been removed.  Therefore, this version 
   of the OpenGL debugger requires version 4.1.0 or later of the
   OpenGL ICD for the SGI 320 and 540.

3. The initial size of the glsplay window is determined by the
   values contained in the "Viewport Info" glsString.  Subsequent
   changes in the viewport are not recorded in such a string so
   the window will not be resized once it is created.  The window
   can be resized manually, but the gls playback will not resize
   the new window size because it will always be reset to the
   original size by the OpenGL calls executed during playback.

4. The command line version of the OpenGL debugger generates trace
   files which do not contain SwapBuffer calls necessary for glsplay
   to function correctly.  Please use the OPENGL32.DLL to generate 
   trace files.  Because of the way the command line version traps
   OpenGL calls, the command line version uses the ICD (installable
   client driver) SwapBuffer functionality which is not traced.
   In this case, SwapBuffers which is a GDI call actually loads
   and calls the system wglSwapBuffers function rather than 
   the OpenGL debugger version of wglSwapBuffers.

5. One cannot stop on SwapBuffer calls when using the command line
   version of the OpenGL debugger.  SwapBuffer calls in the command
   line version are handled by the ICD (installable client driver) as
   a side effect of how it traps OpenGL calls.  Specifically,
   SwapBuffers which is a GDI call actually loads and calls 
   wglSwapBuffers from the system OPENG32.DLL which the ICD 
   understands rather than the OpenGL debugger version of 
   OPENGL32.DLL.

6. The OpenGL debugger and glsplay utility do not track changes in
   the window/viewport size.  Once ogldebug records the size of
   an applications OpenGL window into the GLS history, ogldebug does
   not rerecord this information, so changes to the window/viewport
   size are not recorded.  Subsequently, on playback, the playback
   window remains the initial size even though the GLS trace file
   may make one or more calls to glViewport.  To work around this
   problem edit the GLS trace file and change the values in
   glsString("Viewport Info", x, y, w, h) accordingly.  It might 
   also be necessary to cange to size values in glViewPort, glOrtho,
   etc.

7. The OpenGL debugger saves the history for each OpenGL context
   in temporary files in C:\temp.  If the C: drive is full or close 
   to full, these files will become imcomplete without warning.
   The OpenGL debugger also does not delete these files upon
   exit, so it may be necessary to manually delete them to prevent
   the C: drive from becoming full.

8. The Control Drawing option does not work at this time.

9. Quitting from an application while inside ogldebug results
   in an Application Error.  To work around this, always quit
   an ogldebug session by using Quit from the ogldebug File menu.

Changes:
--------

02/02/98 - Fixed "About ogldebug..."
02/02/98 - Changed glsplay to always be single buffered.
01/15/98 - Finally finished new glsplay UI.
12/21/98 - Added wglUseFontOutlines support.
04/16/99 - Removed swapbuffer workaround.
05/07/99 - Removed foregotten instance of swapbuffer 
           workaround in wglDescribePixelFormat.