.TH BUGLE 3 "May 2006" BUGLE "User Manual"
.SH NAME
bugle \- An OpenGL debugging library
.SH SYNOPSIS
.BI "BUGLE_CHAIN=" chain
.B "LD_PRELOAD=libbugle.so"
.I program
.RI "[" arguments "...]"
.SH DESCRIPTION
.B 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
.IR filter-sets ,
including one that invokes the original call.

In addition, the utility
.BR gldb (1)
can be used to interface with the library, and do useful things like
stopping on OpenGL errors. For common usage this may be the most
convenient way to use
.BR bugle .
There is also a GUI version of the debugger (currently undocumented,
but relatively user-friendly) called
.BR gldb-gui .

The
.B BUGLE_CHAIN
environment variable specifies a
.IR "filter-set chain" ,
which is simply a collection of filter-sets with options. Chains are
defined in the configuration file (see
.BR CONFIGURATION ).
.SH CONFIGURATION
You can create filter-set chains in the file
.BR $HOME/.bugle/filters .
It is possible to use
.B 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
.BR gldb or gldb-gui .

The file is text-based. Comments begin with a
.B "#"
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

.nf
\fB    chain\fI chain
\fB    {
\fI        filter-set
\fI        filter-set
\fR        .
\fR        .
\fR        .
\fB    }\fR
.fi

Filtersets are specified as

.nf
\fB    filterset\fI filterset\fB [\fIkey\fB [inactive]]\fR
\fB    {
\fI        option "value"
\fI        option "value"
\fR        .
\fR        .
\fR        .
\fB    }\fR
.fi

The
.I key
may be used to toggle the filter-set at run-time (not all filter-sets
support this yet, and even those that do will not always work). Key
names are based on X KeySyms (see
.B "<X11/keysymdefs.h>"
for a list). They may also be prefixed with
.BR "C-" ,
.BR "A-" ,
and/or
.B "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
.BR yes/no ,
as
.BR true/false ,
or as
.BR 1/0 .

.SH "FILTER-SETS"
Each filter-set is documented in its own manual page e.g., the
.B trace
filter-set is documented in
.BR bugle-trace (7).
You can get a brief list of available filter-sets and their options by
specifying an undefined chain e.g.
.IP
.nf
.B BUGLE_CHAIN=help LD_PRELOAD=libbugle.so glxgears
.fi
.P
.SH ENVIRONMENT
.TP
.B BUGLE_CHAIN
Specifies the filter-set chain to use. If absent, the first chain in
the configuration file is used.
.TP
.B BUGLE_FILTERS
If present, specifies an alternative configuration file to use, instead of
.BR "$HOME/.bugle/filters" .
.TP
.B BUGLE_FILTER_DIR
If present, 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.
.TP
.B LD_PRELOAD
Used to tell the linker to load
.BR bugle .
.SH FILES
.TP
.B "$HOME/.bugle/filters"
Lists the possible filter-set chains. See
.B CONFIGURATION
above for a description of the format.
.SH 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.
.SH AUTHOR
.B gldb
and the
.B bugle
library are written and maintained by Bruce Merry
<bmerry@users.sourceforge.net>.
.SH "SEE ALSO"
.BR gldb (1),
.BR bugle-camera (7),
.BR bugle-checks (7),
.BR bugle-eps (7),
.BR bugle-error (7),
.BR bugle-frontbuffer (7),
.BR bugle-log (7),
.BR bugle-screenshot (7),
.BR bugle-showerror (7),
.BR bugle-showextensions (7),
.BR bugle-showstats (7),
.BR bugle-stats (7),
.BR bugle-trace (7),
.BR bugle-unwindstack (7),
.BR bugle-wireframe (7)