Rob Jenkins (robj++at++quid)
Mon, 7 Jul 1997 11:20:43 -0700
Cheers
Rob
--------------------------------------------------------------------------
Ogldebug: An Overview
Published: March/April 1997 in Pipeline Volume 8, Number 2
Revision: 1.1
Ogldebug(3G) is a tool that allows a programmer to capture
and examine the underlying OpenGL calls of selected
sections of an application.
This article presents a brief overview of ogldebug, some of
its practical uses, and some of the features added to
ogldebug recently. This article is intended for programmers
who are already familiar with OpenGL.
System Requirements
Ogldebug will run on all SGI systems with graphics that
support OpenGL. Ogldebug is part of the subsystem
gl_dev.sw.ogldebug on the IRIS Development Option (IDO)
CD-ROM. This subsystem is not installed by default.
The IRIS GL equivalent of ogldebug is gldebug(1) which is
part of the subsystem gl_dev.sw.gldebug on the IRIS
Development Option (IDO) CD-ROM. This subsystem is not
installed by default.
Purpose
Because only OpenGL calls are captured by ogldebug, it is
extremely useful for identifying and solving OpenGL
programming errors. It is also very good at uncovering
OpenGL programming style issues that may slow an
application. Note that the OpenGL debugger isn't a
general-purpose debugger. Use dbx(1) and related tools such
as cvd(1) (CASEVision/Workshop Debugger) to find problems
in the non-OpenGL portions of a program. Ogldebug has a
user interface control application (ogldebug) and a special
library (libogldebug.so) that intercepts OpenGL or GLX
calls from the application to the OpenGL library
(libGL.so).
Using Ogldebug
The manual OpenGL on Silicon Graphics Systems is available
on-line with InSight(1) if the subsystem gl_dev.books is
installed. Chapter 10 of this manual provides information
on using ogldebug to debug OpenGL programs. Rather than
duplicate that information here, this article assumes
familiarity with that manual and suggests some practical
uses for ogldebug. There are some changes to the latest
version of ogldebug which make it slightly different from
the version described in the on-line manual. Although the
changes represent improvements in performance, user
interaction and functionality, the core of the tool and
principles of use remain close to those documented. Changes
to ogldebug are outlined below, and should be used in
conjunction with the on-line manual.
New Features
The most recent version of ogldebug is version V14.0 which
is available on the MIPSPro 7.1 IRIX Development Option
CD-ROM. The majority of the changes in this version of
ogldebug are in the user interface. These changes include:
o smaller main window
o call information is now separated
o only one call is displayed in the main window
o a new call history panel is provided where the
programmer can adjust how much of the call history
to retain (10 to 1000 calls)
o only one main window appears for all application
GLX contexts (previously, ogldebug opened a new
main window for each GLX context)
In addition, a significant improvement has been made in
call history. In previous versions of ogldebug, call
history updating could be suspended to allow an application
to run faster. In the latest version, call history is
always produced, and if the call history panel is not open
the application still runs reasonably fast.
A number of minor bug fixes have also been made to
ogldebug. Refer to the gl_dev release notes for more
information.
When to Use Ogldebug
This section describes a few of the many possible uses for
ogldebug.
To Improve Application Performance
The manual OpenGL on Silicon Graphics Systems contains two
chapters on tuning: Chapter 11, "Tuning Graphics
Applications: Fundamentals" and Chapter 12, "Tuning the
Pipeline". Ogldebug can be used as an aid to performing
some of the techniques suggested in those chapters. For
example, ogldebug can be used to look for frequent OpenGL
mode changes, or unnecessary vertex bindings. This could
include things like unneeded per-vertex colors, or normals
being defined for a flat-shaded object. In extreme cases it
may be found that operations are repeated, or large parts
of the scene are drawn more than once by mistake.
To Isolate Programming Errors
OpenGL never signals errors but simply records them.
Within an application, glGetError(3G) can be used to look
for errors, or ogldebug can be used to automatically call
glGetError after every OpenGL call. Ogldebug also attempts
to highlight programming style issues that although
correct, may be inefficient. For example, if an application
loads an identity matrix with glLoadMatrix(3G), ogldebug
will suggest using glLoadIdentity(3G) instead. Although the
two operations are semantically equivalent, glLoadIdentity
can be more efficient in some cases.
To Isolate Parts of an Application
Isolating parts of a large application can help in
narrowing down potential bugs and in analyzing the
performance of discrete stages in an application. Tracing
the very first frame of an application is most likely to
show a majority of the graphics state initialization and
selection. This would be useful for examining and tuning
operations that happen only once at program start time.
Tracing a later frame would be useful for examining the
application during normal drawing.
The following steps can be used to examine one frame of a
double buffered application in an ogldebug session:
1. Run ogldebug with the application.
2. Turn breakpoints and output off from the control
panel.
3. Set a breakpoint at glXSwapBuffers(3G).
4. Click on the "Continue" button and manipulate
the application to the area of interest.
5. Turn on breakpoints.
6. When the execution stops at glXSwapBuffers,
turn on tracing.
7. Click on the "Continue" button
8. When execution stops at the next
glXSwapBuffers, one full scene frame of OpenGL
calls will have been written to a trace file.
The ogldebug trace file is legal C code and may be compiled
and executed. To compile the trace file, change the file
name to <someName>.c and the use the command:
cc <someName>.c -lGL -lX11
It might be useful to experiment with customizing the trace
output to reduce the size of the trace file by omitting
commands that are not of interest or that are repeated
often. For example, a scene with geometry generates a lot
(potentially thousands), of glVertex(3G) commands each
frame, and it may not be useful to trace them all.
The process described above can be applied to any
application that calls OpenGL directly or that makes OpenGL
calls via a library, including SGI libraries like IRIS
Performer, Open Inventor or Imagevision.
To Generate Benchmarks
It is possible to create test cases to represent the
graphics workload for different stages of an application by
tracing parts of the application.
When Opening a Support Call
The techniques discussed in this article can be used to
create a small test case. Providing a test case is
extremely helpful when a support call on OpenGL or any of
the SGI libraries that use OpenGL is opened with your
support provider. Depending on the problem, it may also
reduce the time needed to resolve the issue.
When Developing New Applications
Ogldebug can be used when developing new applications or
adding graphics code to an existing application. Use an
iterative coding process: add some graphics-related code
and then build and test to ensure expected results.
As a Learning Aid
Using ogldebug to examine an application can help to
visualize what the application is doing and how OpenGL is
being used.
Conclusion
The intent of this article is to encourage graphics
developers to use ogldebug as part of their development
environment. Ogldebug can contribute to the design and
development of new applications, the improvement of
existing applications, and in learning more about OpenGL or
any library that uses OpenGL.
For More Information
More information on OpenGL is available on the SGI Web site
(http://www.sgi.com). Use the find or search tool with the
keywords "OpenGL WWW Center", or use the direct URL
http://www.sgi.com/Technology/OpenGL/index.html.
Customers interested in OpenGL may subscribe to the
public newsgroup comp.graphics.api.opengl.
The document "Frequently Asked Questions About Graphics and
user environment customization" is regularly updated and
posted to the comp.sys.sgi.misc, news.answers and
comp.answers newsgroups twice per month. FAQs are also
available on the SGI Web site http://www.sgi.com under
"Sales & Support".
--
________________________________________________________________
Rob Jenkins mailto:robj++at++csd.sgi.com
Silicon Graphics, Mtn View, California, USA
=======================================================================
List Archives, FAQ, FTP: http://www.sgi.com/Technology/Performer/
Submissions: info-performer++at++sgi.com
Admin. requests: info-performer-request++at++sgi.com
This archive was generated by hypermail 2.0b2 on Mon Aug 10 1998 - 17:55:35 PDT