bugle — An OpenGL debugging library
Bugle is a library that intercepts calls to OpenGL functions, in much the same way that many memory debuggers do. Calls are run through a number of user-specified filter-sets, including one that invokes the original call.
In addition, gldb-gui(1) allows an OpenGL application to be debugged by detecting OpenGL errors and showing OpenGL state. For common usage this may be the most convenient way to use bugle.
BUGLE_CHAIN environment variable specifies a
filter-set chain, which is simply a
collection of filter-sets with options. Chains are
defined in the configuration file,
$HOME/.bugle/filters (see the section called “Configuration”).
You can create filter-set chains in the file
$HOME/.bugle/filters. It is possible to use
bugle without creating this file, but
it will simply pass all calls straight through to the real OpenGL
library. This is not particularly useful unless you are using
gldb-gui(1). A sample file is available in
doc/examples/filters in the source
The file is text-based. Comments begin with a
and continue to the end of the line. Strings should be quoted with
double-quotes, and backslash acts as an escape character in the
usual way (including escaping of newlines). Other white-space is
Each chain is specified as
Filter-sets are specified as
value” ... }
key may be used to toggle the
filter-set at run-time (not all filter-sets support this yet, and
those that do will not always work). Key names are based on X
<X11/keysymdefs.h> for a
list). They may also be prefixed with
S- to indicate that
the key must be combined with Ctrl,
Alt or Shift respectively. Some
filter-sets have options which are keys; these take the same
format. The Windows build current only supports alphabetic keys
(together with the Ctrl, Alt and
If you don't need to specify any options, it is also legal to omit
the braces. Boolean options may be specified as
false or as
Each filter-set is documented in its own manual page e.g., the trace filter-set is documented in bugle-trace(7). You can get a brief list of available filter-sets and their options by specifying an undefined chain e.g.,
Specifies the filter-set chain to use. If absent, the first chain in the configuration file is used.
If set, specifies an alternative configuration file to use instead of
If set, specifies an alternative directory in which to find modules. This option is currently used by the test suite, and is not intended for general use.
Tells the linker to load bugle on Linux and similar systems. On Windows, you need to put the bugle version of
PATHahead of the real version; the easiest way to do this is to copy it into the same directory as the executable you are debugging.
Configuration for remote TCP/IP debugging. Refer to gldb-gui(1) for details.
OpenGL color-index mode is not well supported.
Multi-threaded applications that call the GL from more than one thread will break in various ways. The debugger filter-set is particularly fragile.
Display lists may cause things to go wrong, depending on how they are created and what calls go into them.
For an up to date list of bugs, see the bug tracker online. Also see the pages for individual filter-sets for specific bugs affecting each.