ogldebug(3G) OpenGL Reference ogldebug(3G)NAMEogldebug - OpenGL debugging utility
SYNOPSISogldebug [options]
DESCRIPTIONogldebug is a development tool that allows you to examine OpenGL calls
generated by an application.
ogldebug command line options:
-display <display> Set the display for the user interface of
ogldebug. ogldebug will use $DISPLAY if
-display is not specified
-appdisplay <display> Set the display for the application.
-glsplay <gls trace file> Play back a gls trace file recorded by
ogldebug. Note that a gls trace file is not
standard c.
-gls2c <gls trace file> Convert a gls trace file to a c code snippet.
Output is to stdout.
-gls2x <gls trace file> Convert a gls trace file to a compile-able X
Window System program. Output is to stdout.
-gls2glut <gls trace file> Convert a gls trace file to a compile-able
GLUT program. Output is to stdout.
To debug an OpenGL application, enter the command:
ogldebug <ogldebug options if any> <o32 app> <app options if any>
ogldebug32 <ogldebug options if any> <n32 app> <app options if any>
ogldebug64 <ogldebug options if any> <64 app> <app options if any>
ogldebug becomes active when the application makes its first OpenGL call.
Each ogldebug represents a different application process. If the
application uses fork, sproc or pthread, then multiple instances of
ogldebug may appear.
The main window is described below:
At the top are two fields that display the application's process ID and
current OpenGL context.
Page 1
ogldebug(3G) OpenGL Reference ogldebug(3G)
Below is the current OpenGL call to be executed.
Below is a field that displays information/status from ogldebug.
Below is a row of control buttons:
Halt Stop at the next OpenGL call.
Continue Continue execution of application. No updates will occur as
long as the application is running.
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 warning/error Calls glGetError after every OpenGL call to
check for errors. Note that glGetError cannot
be called between glBegin and glEnd pairs. If
an error is detected, glGetError is called
repeatedly.
Control drawing Allows the user to inspect drawing in
progress (force front buffer rendering). Also
allows the user to control drawing speed.
History Save calls to history. Use the adjacent Setup
button to select which calls to include into
history as well as control additional history
information.
Break on GL calls Halt on OpenGL calls. Use the adjacent Setup
button to select which calls to halt on.
Break on SwapBuffers Halt on SwapBuffers. This is not a core
OpenGL function but a windowing system
dependent call.
Skip GL calls Skip selected OpenGL calls. Use the adjacent
Setup button to select which calls to skip.
Note that the History, Break on GL calls and Skip GL calls setup panels
allow you to save/recall up to three custom set/unset groups at a time.
Also, these panels support the standard shift, control, shift-control
keystrokes for multiple item selection/deselection. For convienence,
glFlush is selected by default for Break on GL calls but is not active
unless Break on GL calls is toggled on.
Page 2
ogldebug(3G) OpenGL Reference ogldebug(3G)
The menu items are described below:
Under the File menu:
About ogldebug Shows ogldebug version number.
Save Configuration Saves current configuration to a file. The default
file name is ogldebug.cfg.
Recall Configuration Recalls configuration from a file. The default file
name is ogldebug.cfg.
Quit Exits ogldebug.
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 counts for OpenGL, GLU, GLX and
GLC calls. You can show all or only non-zero calls.
Call History Brings up a panel with a history of OpenGL calls. The
history is in the form of a gls trace.
Display List Brings up a panel with information about the
application's display lists. You can show all or only
non-empty display lists.
Primitive Count Brings up a panel with primitive counts for the
application.
State Brings up a panel with state information. You can show
all or only non-default state. You can also take a
snapshot of the current state for later comparison. Note
that state cannot be queried between glBegin and glEnd
pairs.
Window Brings up a panel with information on application's
windows.
Under the Reference menu:
Enumerates A reference to the OpenGL enumerant values.
NOTES
Here is an example of how to get a gls trace of an application:
1) ogldebug <application>. Make sure you match ogldebug (ogldebug,
ogldebug32 or ogldebug64) with your application's compiled type.
Page 3
ogldebug(3G) OpenGL Reference ogldebug(3G)
2) Run until application has passed the point of interest. You may want
to ensure that a complete frame has been capture by breaking on
glFlush or SwapBuffer.
3) Select Call History from the Information menu. You will be first
presented with a panel to select which OpenGL context of which you
want a gls trace. There may be more then one OpenGL context available,
depending on the application.
4) Select the OpenGL context you want a gls trace of. A Call History
panel will appear. You now can save a gls trace file. Note that if the
call history is large (slow to load), you have the option of directly
saving to a file.
A gls trace is meant to be pure OpenGL and window-system independent.
However, comments have been added to indicate when GLX, GLU and GLC calls
were made. Any OpenGL calls made from within these higher level calls are
indented. Performance hints are also included.
At this point, you may play back the gls trace file with the -glsplay
option or convert the gls trace file to various c files with the -gls2c,
-gls2x and -gls2glut options. Any comments or hints in the gls trace file
are removed during the conversion.
You may want to use the No History feature for large application such as
Performer. If you need to run the application to a particular point and
do not care about the call history until that point, turn on No History
to speed things up.
FILESogldebug has two parts: a user interface control application (ogldebug)
and a special library that sits between an application and libGL.so
(libogldebug.so).
ogldebug should be in a directory that is included in your $PATH
environment variable (normally /usr/sbin). libogldebug.so must be in the
same directory as libGL.so (normally /usr/lib).
At startup, ogldebug will look for the configuration file ./ogldebug.cfg
then $HOME/ogldebug.cfg then $HOME/.ogldebug.cfg.
If ogldebug should quit abnormally, it may leave files behind. ogldebug
stores all of it's work files in a directory named OGLDEBUG_<unique ID>.
The default location for this work directory is /tmp. However, ogldebug
will use $TMPDIR if set.
/usr/sbin/ogldebug
/usr/sbin/ogldebug32
/usr/sbin/ogldebug64
$ROOT/usr/lib/libogldebug.so
$ROOT/usr/lib32/libogldebug.so
Page 4
ogldebug(3G) OpenGL Reference ogldebug(3G)
$ROOT/usr/lib64/libogldebug.so
/usr/share/catman/u_man/cat3/OpenGL/ogldebug.z
SEE ALSOglsintro(3G)
Page 5
