[About] [News] [Documentation] [Screenshots]
Name
bugle — An OpenGL debugging library
Synopsis
[BUGLE_CHAIN
=chain
LD_PRELOAD
=libbugle.so
program
argument
...]
Description
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”).
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
chainchain
{filter-set
filter-set
filter-set
... }
Filter-sets are specified as
filtersetfilterset
[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
.
Filter-sets
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
=helpLD_PRELOAD
=libbugle.so
glxgears
Environment
BUGLE_CHAIN
Specifies the filter-set chain to use. If absent, the first chain in the configuration file is used.
BUGLE_FILTERS
If set, specifies an alternative configuration file to use instead of
$HOME/.bugle/filters
.BUGLE_FILTER_DIR
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.
LD_PRELOAD
Tells the linker to load bugle on Linux and similar systems. On Windows, you need to put the bugle version of
opengl32.dll
on thePATH
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.BUGLE_DEBUGGER
,BUGLE_DEBUGGER_HOST
,BUGLE_DEBUGGER_PORT
Configuration for remote TCP/IP debugging. Refer to gldb-gui(1) for details.
Files
$HOME/.bugle/filters
Lists the possible filter-set chains. See the section called “Configuration” for a description of the format.
$HOME/.bugle/statistics
Definitions of statistics; see bugle-statistics(5) for more information.
Bugs
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.