Debugging Utility

NAME

ogldebug - OpenGL debugging utility

SYNOPSIS

ogldebug <application> <application parameters if any>

DESCRIPTION

Ogldebug is a development tool that allows you to examine OpenGL calls generated by an application. Ogldebug has two parts: a user interface control application (ogldebug.exe) and a special library that sits between an application and openg32.dll (ogldebug.dll).

Ogldebug should be in a directory that is included in your $PATH environment variable. ogldebug.dll can be in the same directory as openg32.dll.

USAGE

To debug an OpenGL application, enter the command:

ogldebug <application> <application parameters if any>

Ogldebug becomes active when the application makes it's first OpenGL call. Each Ogldebug represents a different application process. If the application were to fork, then 2 Ogldebug windows would appear.

The main window is described below:

• At the top is the application's process ID and current GL context.
• Below is the current call to be executed.
• Below is a status field. Status for both ogldebug and the application are displayed here.

Below is a row of control buttons:

• Halt
  • Stop at the next OpenGL call.
• Continue
  • Continue execution of application.
• Step
  • Single step to the next OpenGL call.
• Skip
  • Skip the current call and step to the next one.

For both Step and Skip, if the application is running, ogldebug will halt at the next OpenGL call.

Below is a series of user option toggle buttons:

• Check for GL error
  • Calls glGetError after every call to check for errors. Note that glGetError cannot be called between glBegin and glEnd pairs (see glGetError). Also, only one glGetError call is made.
• Control drawing
  • Allows the user to inspect drawing in progress. Also allows the user to control drawing speed.
• Trace
  • Trace OpenGL calls to file. Use the adjacent Setup button to select which calls to trace and to set the file name. The default file name is <application name>.trace.c.
• Stop on API error
  • Halt if ogldebug detects a problem with a call.
• Break on API calls
  • Halt on OpenGL calls. Use the adjacent Setup button to select which calls to halt on.
• Skip API calls
  • Skip OpenGL calls. Use the adjacent Setup button to select which calls to skip.

Note that the Break on API calls, Skip API calls and Trace setup panels allow you to save/recall up to three custom set/unset groups at a time. Also, you can set any file name to "stdout". Information will then be sent to Standard Output rather then to file.

The menu items are described below:

• Under the File menu:
  • About ogldebug
    • Shows ogldebug version number.
  • Save Configuration
    • Save current configuration to a file. The default file name is ogldebug.cfg.
  • Recall Configuration
    • Recall configuration from a file. The default file name is ogldebug.cfg.
  • Quit
    • Exits ogldebug (and the application).
• Under the Command menu, you will find duplicate functionality of the control buttons.
  • This provides you with keyboard equivalence.
• Under the Options menu:
  • Call Count
    • Brings up a panel with information about the total number of calls as well as individual counts for each call.
  • Call History
    • Brings up a panel with a history of calls. Performance hints are also included. The number of calls remembered can be customized. The initial size is 100 calls.
  • Display List
    • Brings up a panel with information about the application's display lists. You can view the contents of each display list by selecting that display list.
  • Enumerates
    • A reference to the OpenGL enumerant values.
  • Primitive
    • Brings up a panel with information about the primitives used in the application.
  • State
    • Brings up a panel with state information. You can view individual state information by selecting that stat .
  • Window
    • Brings up a panel with information on application's windows.

FILES

You can download the ogldebug package containing the files below:

• ogldebug.exe
• ogldebug.dll
• opengl32.dll
• README.txt
• glsplay.exe
• GLS32.DLL
• teapot.gls
• teapot.exe
• tumbleQ.dll

TIPS AND TRICKS

While Ogldebug is an excellent tool in its own right, its power can be increased through the use of post-processing its data files to look for patterns in the applications Open GL command use.

For example, Ogldebug will display OpenGL call counts, but not details on those calls. A case in point is glEnable and glDisable calls. An application may make 100's of these calls, but which features are being enabled and disabled? To answer that question, save the OpenGL call history to a file (default name is history.txt) and then run that file throug a filter to extract the specific call and then sort, group and count the unique calls. That task is easliy accomplished with the following Bourne shell script:

  #!/bin/sh
  #
  # Here's a simple tool for filtering Ogldebug histories and grouping/counting
  # functions with similar parameters.
  # For example, searching for glEnable in a history file, will result in a 
  # list of all like parameter glEnable calls, with numbers of each similar call
  #
  grep $1 $2 | sort | uniq -c | sort

Example use of the script:

  > ./ogl_filter.txt glEnable history1.txt
  1 glEnable(GL_NORMALIZE);
  10 glEnable(GL_SCISSOR_TEST);
  20 glEnable(GL_LIGHT0);
  20 glEnable(GL_LIGHT1);
  21 glEnable(GL_CULL_FACE);
  40 glEnable(GL_BLEND);
  40 glEnable(GL_DEPTH_TEST);
  41 glEnable(GL_DITHER);
  80 glEnable(GL_COLOR_MATERIAL);
  80 glEnable(GL_LIGHTING);
  977 glEnable(GL_TEXTURE_2D);

  > ./ogl_filter.txt glDisable history.txt
  10 glDisable(GL_SCISSOR_TEST);
  40 glDisable(GL_BLEND);
  99 glDisable(GL_TEXTURE_2D);
  120 glDisable(GL_LIGHT0);
  120 glDisable(GL_LIGHT1);
  120 glDisable(GL_LIGHT2);
  120 glDisable(GL_LIGHT3);
  120 glDisable(GL_LIGHT4);
  120 glDisable(GL_LIGHT5);
  120 glDisable(GL_LIGHT6);
  120 glDisable(GL_LIGHT7);
  139 glDisable(GL_ALPHA_TEST);

From this example, which turned out to be 10 frames of a simulation application, we notice that lights 0 and 1 are being enabled twice in every frame, while other states are enabled 4 times per frame, some 8. In the glDisable case, we can see lights 0..7 are turned off 12 times (each) per frame. Based upon this and other feedback, the developer was able to obtain about a 5-10% speedup in redraw times by maintaining local OpenGL state in his application and only makig changes when necessary.