GLDB(1)
User Manual
GLDB(1)
NAME
gldb − Debugger front-end for the BuGLe library
SYNOPSIS
gldb program [arguments]
DESCRIPTION
gldb is a front-end debugger to be used with the bugle(3) library, modelled on 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.
COMMANDS
chain name Specify the name of the filter-set chain to use from the config file $HOME/.bugle/filters. If name is none, then the default (no filters) is used. help run Show the list of commands, with brief descriptions. Start your program.
continue Continue running the program. step kill Run the program until the next OpenGL call. Kill the running program.
break function Set a breakpoint at function (an OpenGL function). break error Break on OpenGL errors. This is the default. unbreak function Do not break on function. unbreak error Do not break on OpenGL errors. quit Exit gldb. backtrace Call gdb(1) to obtain a stack trace. gdb Start gdb(1) and attach it to the program. Note that the program will be waiting for commands from gldb, so even if you continue the program it will not appear to go anywhere. Killing the program from within gdb is not recommended, since gldb may not notice.
state [state] Queries the OpenGL state. If omitted, all state for the current context is output. Otherwise, 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 GL_TEXTURE_2D.0.0.GL_TEXTURE_WIDTH (the first zero is the texture object name). Tab completion is also supported. screenshot filename.ppm Captures a screenshot from the back buffer, and saves it to filename.ppm in PPM(5) format. Since the back buffer is used, you are not guaranteed a complete picture. For a complete picture, put a breakpoint on glXSwapBuffers and call this command from there.
BUGLE
May 2006
1
GLDB(1)
User Manual
GLDB(1)
enable|disable filter-set Enables or disables a filter-set on the fly. This is still experimental, and won’t work for most filtersets (because they expect to perform initialisation when the context is created). In addition, enable will automatically load dependent filter-sets, but disable will not unload them again.
FILES
$HOME/.bugle/filters A configuration file for filters. See bugle(3).
ENVIRONMENT
BUGLE_CHAIN BUGLE_DEBUGGER BUGLE_DEBUGGER_FD_IN BUGLE_DEBUGGER_FD_OUT Internal environment variables used to communicate between the debugger and the library. LD_PRELOAD Used internally to force loading of the library.
BUGS
On some systems, the 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 gdb(1) to the process. 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.
AUTHOR
gldb and the bugle library are written and maintained by Bruce Merry <bmerry@users.sourceforge.net>.
SEE ALSO
bugle(3), gdb(1), ppm(5)
BUGLE
May 2006
2