Introduction:
This directory contains the latest NT OpenGL debugger images. This
version of ogldebug is an ongoing work in progress and contains
more recent changes and fixes than the officially released version.
Newer versions will continue to be provided here.
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 ."
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:
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.
From the Command Line
Put OGLDEBUG.DLL and OGLDEBUG.EXE in your path. From the command
line type "ogldebug ." 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.
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 " 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:
The command line version of the OpenGL debugger does not work
with some applications due to the way the applications invoke
OpenGL at startup.
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.
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.
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.
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.
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.
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.
The Control Drawing option does not work at this time.
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/98 - Removed swapbuffer workaround.
- 05/07/99 - Removed foregotten instance of swapbuffer
workaround in wglDescribePixelFormat.