BuGLe: questions that nobody has asked yet, but which they might...
===================================================================
Note that compilation problems are addressed in TROUBLESHOOTING.

Q. My program crashes, somewhere deep inside the OpenGL driver and I
can't get a stack trace. How can I tell what caused it?
A. Use the "unwindstack" filterset, and see the manual page for
documentation.
A. Use the "log" filterset, and turn on the flush option (see the example
in doc/examples/filters). Then after your program crashes, the last entry
in the log file will most likely be the one just before the crash.

Q. I wrote LD_PRELOAD=libbugle.so glxgears and it failed, what's up?
A. You either need to specify a full path to libbugle.so, or else place it
somewhere that the linker will find. On GNU systems, you can add the
appropriate path to /etc/ld.so.conf.

Q. I don't want to have to set BUGLE_CHAIN all the time; can't I
specify a default?
A. The first chain in the configuration file is the default.

Q. I don't want to have to set LD_PRELOAD all the time, or it is not
available on my system. Can I just link directly to BuGLe?
A. Yes, you can specify -lbugle in place of -lGL when you link. If it
is not installed in a standard directory, you may need extra compiler
flags, such as -L/path/to/bugle -Wl,-rpath -Wl,/path/to/bugle

Q. How do I build a 32-bit version of BuGLe on an AMD64 system?
A. The exact details will depend on your OS. Here is what I do on Gentoo:

./configure --x-libraries=/usr/lib32 CC="gcc -m32" CXX="g++ -m32" \
   --libdir=/usr/local/lib32 --bindir=/usr/local/bin32

Gentoo also tries to be clever by putting in a libGL.la to make linking
against OpenGL work better, but in some cases it causes libtool to pick
up the 64-bit version of OpenGL. I work around this by copying
/usr/lib/libGL.la into the compilation directory, and replacing all
references to /usr/lib with /usr/lib32.

Q. How do you get SDL-based apps to use BuGLe?
A. On GNU systems, they should work as is. On some systems, it may be
necessary to run them as

LD_PRELOAD=/path/to/libbugle.so SDL_VIDEO_GL_DRIVER=/path/to/libbugle.so tuxracer

Q. How do you get Quake3 or Doom3 to use BuGLe?
A. On GNU systems, they should work as is. On some systems, run it as

LD_PRELOAD=/path/to/libbugle.so quake3 +set r_glDriver /path/to/libbugle.so

Note that Quake3 and Doom3 are 32-bit binaries, so if you have an AMD64
system you will need to compile a 32-bit bugle, specify the correct
paths to it and probably set LD_LIBRARY_PATH to cover 32-bit libraries
(give paths to find libGL.so, libX11.so and libbugle.so to be safe).

Q. How do you get QT-based apps to use BuGLe?
A. On GNU systems, they should work as is. There is currently no known
workaround for systems that don't support dlsym with the RTLD_NEXT flag.

Q. What is the performance penalty?
A. That depends on what you're doing with the library. If you only use
filter-sets that intercept a few functions (like showstats), then all
other functions suffer only a small penalty. Using filter-sets that
check for error after every function (including showerror and the
debugger) adds a much bigger penalty.

To give you an example, here are some rough numbers for Quake3 1.32c on
demo 'four'.

without BuGLe: 683.7fps
with no filter-sets: 668.4fps
with the logfps chain: 661.8fps
with the showfps chain: 616.7fps
with no filter-sets, but in the debugger: 131.3fps
with tracing: 181.6fps

Tracing is particularly slow because it does file I/O, as well as a lot
of text formatting.

The overhead will also depend on the CPU/GPU balance. GPU-bound
programs will be less affected by overheads.

Q. Why is there a mix of C and C++ code?
A. The library itself is written entirely in C. This is mainly because
a C++ library will drag libstdc++ in with it, and this has been found to
create some problems when forcing linking to an application that already
depends on a conflicting version of libstdc++. There is still a
dependence on libc, but libc is less of a moving target. The code
generator is written in C++, since it makes the coding easier and does
not introduce the dependency issues above.

Q. Why is a recent (>3.0) version of gcc required?
A. BuGLe is driven by a number of tables that list all the information
about the various types and functions in OpenGL. To capture this
information, it is necessary to parse the OpenGL header files. It would
be very difficult to write a parser to do this robustly, but gcc
already knows how to do this. Unfortunately, the ability to extract a
parse tree from gcc (the -fdump-translation-unit option)
was only added sometime after 3.0, and is also broken in 4.0 (fixed in
4.1).