[About] [News] [Documentation] [Screenshots]


bugle — An OpenGL debugging library


BUGLE_CHAIN=chain LD_PRELOAD=libbugle.so program [argument...]


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.

The 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 distribution.

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 ignored. Each chain is specified as

chain chain

Filter-sets are specified as

filterset filterset [key [inactive]]
    option value
    option value
    option value

The 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 KeySyms (see <X11/keysymdefs.h> for a list). They may also be prefixed with C-, A- or 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 Shift modifiers).

If you don't need to specify any options, it is also legal to omit the braces. Boolean options may be specified as yes/no, as true/false or as 1/0.


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.,

$ BUGLE_CHAIN=help LD_PRELOAD=libbugle.so glxgears



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 $HOME/.bugle/filters.


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 opengl32.dll on the PATH ahead 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.



Lists the possible filter-set chains. See the section called “Configuration” for a description of the format.


Definitions of statistics; see bugle-statistics(5) for more information.


  • 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.


bugle is written and maintained by Bruce Merry.

Get BuGLe at SourceForge.net. Fast, secure and Free Open Source software downloads