bugle

bugle
Prev	Appendix C. Bugle manual pages	Next

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

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.

Author

bugle is written and maintained by Bruce Merry.

Name

Synopsis