BUGLE(3) Bugle user manual BUGLE(3)NAMEbugle - An OpenGL debugging library
SYNOPSIS
BUGLE_CHAIN=chain LD_PRELOAD=libbugle.so program [argument...]
DESCRIPTIONbugle 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
chain chain
{
filter-set
filter-set
filter-set
...
}
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.
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=help LD_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.
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.
See the pages for individual filter-sets for specific bugs affecting
each.
AUTHORbugle is written and maintained by Bruce Merry.
BUGLE 0.0.20091026 Jan 2009 BUGLE(3)