ogldebug(3G)
ogldebug - OpenGL debugging utility
Showing IRIX 6.5.30 (default release). Last changed in IRIX 6.5.5.
NAME ogldebug - OpenGL debugging utility SYNOPSIS ogldebug [options] DESCRIPTION ogldebug 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. 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. 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. 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. FILES ogldebug 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 $ROOT/usr/lib64/libogldebug.so /usr/share/catman/u_man/cat3/OpenGL/ogldebug.z SEE ALSO glsintro(3G)