Debugging Guide¶
This guide explains the debugging tools and features available in the project, specifically focusing on the OpenGL Debug Output system.
OpenGL Debug Output¶
The engine initializes the OpenGL debug output synchronously if the context is created with the GL_CONTEXT_FLAG_DEBUG_BIT. This allows the application to intercept and log messages generated by the OpenGL driver.
High Sensitivity Mode¶
When the debug context is active, the system enters "High Sensitivity" mode. In this mode:
- All debug messages are intercepted, including
GL_DEBUG_SEVERITY_NOTIFICATION. - Synchronous output is enabled, meaning the callback is executed immediately when the driver generates the message (allowing for accurate stack traces in a debugger).
- A deduplication mechanism prevents the log from being flooded with identical messages (e.g., inside a draw loop).
Log Level Mapping¶
To avoid polluting the logs with excessive warnings, the system maps OpenGL message severities to application log levels as follows:
| OpenGL Severity | OpenGL Type | Application Log Level | Description |
|---|---|---|---|
HIGH |
Any | ERROR | Critical errors that likely caused undefined behavior or crashes. |
| Any | ERROR |
ERROR | Any message explicitly flagged as an error type. |
MEDIUM |
Any | WARNING | Major performance warnings, deprecated behavior, or undefined behavior usage. |
LOW |
Any | WARNING | Minor performance warnings or redundancy. |
NOTIFICATION |
Any | INFO | Informational messages, resource creation details, or specific driver implementation details. |
Interpretation¶
- [ERROR]: Needs immediate attention.
- [WARNING]: Should be investigated. Often points to non-optimal usage (e.g., "Buffer object usage hint is STATIC_DRAW but is being updated frequently").
- [INFO]: Generally safe to ignore unless you are debugging a specific resource issue (e.g., "Texture object 4 created").
Performance Debugging with ApiTrace¶
The engine is integrated with ApiTrace to detect GPU-side performance bottlenecks and driver-level stalls.
Automated Checks¶
Performance verification is automated and integrated into the build system:
just test-apitrace: Runs the unit test suite under ApiTrace and fails if any "performance issue" or "stall" warnings are detected in the command stream.just test-integration-apitrace: Launches the main application, executes a full user scenario (Page Up/Down, F-keys, camera move), and analyzes the resulting trace for regressions.
Interpreting Stalls¶
The automation looks for specific driver warnings, such as:
api performance issue 1: memory mapping a busy "buffer" BO stalled and took 1.379 ms.
If such an error occurs, it means the CPU is waiting for the GPU before it can continue, which kills the framerate. Fixes usually involve double-buffering resources or using GLsync fences (see GPU Synchronization Guide).
Manual Investigation¶
If the automated tests fail, you can investigate the trace manually:
make qapitrace: Launches the ApiTrace GUI to inspect the offending frame and command.make replay: Replays the trace to verify visual consistency.