.TH GLDB 1 "May 2006" BUGLE "User Manual"
.SH NAME
gldb \- Debugger front-end for the BuGLe library
.SH SYNOPSIS
.B gldb
.I program
.RI [ arguments ]
.SH DESCRIPTION
.B gldb
is a front-end debugger to be used with the
.BR bugle (3)
library, modelled on
.BR gdb (1).
It can set breakpoints on OpenGL functions, and by default will stop
whenever the program causes a GL error. Pressing Ctrl-C will also cause
the running program to stop.
.SH COMMANDS
.TP
.B chain \fIname
Specify the name of the filter-set chain to use from the config file
.BR $HOME/.bugle/filters .
If
.I name
is none, then the default (no filters) is used.
.TP
.B help
Show the list of commands, with brief descriptions.
.TP
.B run
Start your program.
.TP
.B continue
Continue running the program.
.TP
.B step
Run the program until the next OpenGL call.
.TP
.B kill
Kill the running program.
.TP
.B break \fIfunction
Set a breakpoint at
.I function
(an OpenGL function).
.TP
.B break error
Break on OpenGL errors. This is the default.
.TP
.B unbreak \fIfunction
Do not break on
.IR function.
.TP
.B unbreak error
Do not break on OpenGL errors.
.TP
.B quit
Exit
.BR gldb .
.TP
.B backtrace
Call
.BR gdb (1)
to obtain a stack trace.
.TP
.B gdb
Start
.BR gdb (1)
and attach it to the program. Note that the program will be waiting for
commands from
.BR gldb ,
so even if you continue the program it will not appear to go anywhere.
Killing the program from within
.B gdb
is not recommended, since
.B gldb
may not notice.
.TP
.B state \fI[state]\fB
Queries the OpenGL
.IR state .
If omitted, all state for the current context is output. Otherwise,
.I state
is expected to be relative to the current context. Try first running
the command without argument to see how the states are arranged, as
some state is nested. For example, the width of the default 2D texture
is referenced as

.B GL_TEXTURE_2D.0.0.GL_TEXTURE_WIDTH

(the first zero is the texture object name). Tab completion is also
supported.
.TP
.B screenshot \fIfilename\fR.ppm\fB
Captures a screenshot from the back buffer, and saves it to
.IR filename .ppm
in
.BR PPM (5)
format. Since the back buffer is used, you are not guaranteed a
complete picture. For a complete picture, put a breakpoint on
.B glXSwapBuffers
and call this command from there.
.TP
.B enable\fR|\fBdisable \fIfilter-set\fB
Enables or disables a filter-set on the fly. This is still
experimental, and won't work for most filter-sets (because they expect to
perform initialisation when the context is created). In addition,
.B enable
will automatically load dependent
filter-sets, but
.B disable
will not unload them again.
.SH FILES
.TP
.B $HOME/.bugle/filters
A configuration file for filters. See
.BR bugle (3).
.SH ENVIRONMENT
.TP
.B BUGLE_CHAIN
.TP 
.B BUGLE_DEBUGGER
.TP
.B BUGLE_DEBUGGER_FD_IN
.TP
.B BUGLE_DEBUGGER_FD_OUT
Internal environment variables used to communicate between the debugger
and the library.
.TP
.B LD_PRELOAD
Used internally to force loading of the library.
.SH BUGS
On some systems, the
.B gdb
command will cause some of the processes involved to be stopped. The
cause is currently unknown. The work-around is to use another terminal
to manually connect
.BR gdb (1)
to the process.

.B gldb
will probably do strange things if you try to use it on a
multi-threaded program. If only one thread does rendering, then the
result is predicable: when the program is ``stopped'', only that thread
will actually be stopped. If multiple threads attempt to render, then
the results will be unpredictable.
.SH AUTHOR
.B gldb
and the
.B bugle
library
are written and maintained by Bruce Merry <bmerry@users.sourceforge.net>.
.SH "SEE ALSO"
.BR bugle (3),
.BR gdb (1),
.BR ppm (5)