pyglet includes a number of debug paths that can be enabled during or before application startup. These were primarily developed to aid in debugging pyglet itself, however some of them may also prove useful for understanding and debugging pyglet applications.
Each debug option is a key in the pyglet.options dictionary. Options can be set directly on the dictionary before any other modules are imported:
import pyglet pyglet.options['debug_gl'] = False
They can also be set with environment variables before pyglet is imported.
The corresponding environment variable for each option is the string
PYGLET_ prefixed to the uppercase option key. For example, the
environment variable for
PYGLET_DEBUG_GL. Boolean options
are set or unset with
A summary of the debug environment variables appears in the table below.
Option Environment variable Type
debug_font options are used to debug the
pyglet.font modules, respectively. Their behaviour
is platform-dependent and useful only for pyglet developers.
The remaining debug options are detailed below.
graphics_vbo option enables the use of vertex buffer objects in
pyglet.graphics (instead, only vertex arrays). This is useful when
graphics module as well as isolating code for determining if
a video driver is faulty.
debug_graphics_batch option causes all Batch objects to dump their
rendering tree to standard output before drawing, after any change (so two
drawings of the same tree will only dump once). This is useful to debug
applications making use of Group and Batch rendering.
debug_gl option intercepts most OpenGL calls and calls
afterwards (it only does this where such a call would be legal). If an error
is reported, an exception is raised immediately.
This option is enabled by default unless the
-O flag (optimisation) is
given to Python, or the script is running from within a py2exe or py2app
debug_gl_trace option causes all OpenGL functions called to be dumped
to standard out. When combined with
debug_gl_trace_args, the arguments
given to each function are also printed (they are abbreviated if necessary to
avoid dumping large amounts of buffer data).
debug_trace option enables Python-wide function tracing. This causes
every function call to be printed to standard out. Due to the large number of
function calls required just to initialise pyglet, it is recommended to
redirect standard output to a file when using this option.
debug_trace_args option additionally prints the arguments to each
debug_trace_depth is greater than 1 the caller(s) of each function
(and their arguments, if
debug_trace_args is set) are also printed. Each
caller is indented beneath the callee. The default depth is 1, specifying
that no callers are printed.
debug_lib option causes the path of each loaded library to be printed
to standard out. This is performed by the undocumented
which on Linux and Mac OS X must sometimes follow complex procedures to find
the correct library. On Windows not all libraries are loaded via this module,
so they will not be printed (however, loading Windows DLLs is sufficiently
simple that there is little need for this information).
X11 errors are caught by pyglet and suppressed, as there are plenty of X
servers in the wild that generate errors that can be safely ignored.
debug_x11 option causes these errors to be dumped to standard out,
along with a traceback of the Python stack (this may or may not correspond to
the error, depending on whether or not it was reported asynchronously).
debug_win32 option causes all library calls into
gdi32.dll to be intercepted. Before each library
SetLastError(0) is called, and afterwards
called. Any errors discovered are written to a file named
debug_win32.log. Note that an error is only valid if the function called
returned an error code, but the interception function does not check this.