Linux Certif

Toute la documentation sur la certification Linux LPI

bugle

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

 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.