SGI Windows NT Toolbox
|Download Files|
ogldebug, the OpenGL Debugger

May 7, 1999
Thomas J. True
true@sgi.com



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:

  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 ." 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 " 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/98 - Removed swapbuffer workaround.
  • 05/07/99 - Removed foregotten instance of swapbuffer workaround in wglDescribePixelFormat.






Web Accessible Files of the utilities/ogldebug directory:

This is an automatically derived categorization of files of this directory. Only files which can be displayed or heard in some manner are included. Files may be immediately accessed by clicking the corresponding link. The Zip Archive (if present) contains all files in this directory/subtree (including executables, subdirectories, etc.)

Documentation

Zip Archive


Copyright © 1999, Silicon Graphics, Inc.