For various reasons, debugging OpenGL related code can be tricky. This article provides suggestions for how to improve your efficiency while debugging OpenGL code in Gecko.
OpenGL debug mode
When running a debug build, you can enable the OpenGL debug mode by defining the environment variable MOZ_GL_DEBUG. If you start up Firefox with this variable defined, the following behavior changes occur:
- Each time you issue an OpenGL call, a check is performed to ensure that the GL context is current, using a thread-local static variable to keep track of this. If the context isn't current, the call aborts.
- Every time an OpenGL call completes,
glFinish()gets run automatically. This flushes out each call, essentially turning OpenGL into a synchronous API. This makes debugging crashes caused by an OpenGL call much easier, since the stack you see will match where the call was issued, rather than some time in the future when it happens to run and crash. - If an OpenGL error occurred when executing the call, an error message is output.
If you need more verbose debug output, you can enable the verbose debug mode by defining the environment variable MOZ_GL_DEBUG_VERBOSE. With this enabled, messages are printed before and after every OpenGL call. This can help make it much easier to debug crashes and hangs that make the computer unusable (thereby stymieing attempts to debug).
The MOZ_GL_DEBUG_ABORT_ON_ERROR environment variable, if set, causes Firefox to abort as soon as an OpenGL error occurs. This is generally only useful in cases where you know that no error should occur, since there are cases where perfectly valid WebGL code may generate OpenGL errors.
You don't have to define more than one of these; for example, if you set MOZ_GL_DEBUG_ABORT_ON_ERROR, the MOZ_GL_DEBUG setting is assumed.