The debugCallback callback function has several parameters, the most important of which is the debug message itself (the sixth parameter, message). For this example, we simply print the message to the standard output, but we could send it to a log file or some other destination.
The first four parameters to debugCallback describe the source, type, ID number, and severity of the message. The ID number is an unsigned integer specific to the message. The possible values for the source, type, and severity parameters are described in the following tables.
The source parameter can have any of the following values:
Source | Generated by |
GL_DEBUG_SOURCE_API | Calls to the OpenGL API |
GL_DEBUG_SOURCE_WINDOW_SYSTEM | Calls to a Windows system API |
GL_DEBUG_SOURCE_THIRD_PARTY | An application associated with OpenGL |
GL_DEBUG_SOURCE_APPLICATION | The application itself |
GL_DEBUG_SOURCE_OTHER | Some other source |
The type parameter can have any of the following values:
Type | Description |
GL_DEBUG_TYPE_ERROR | An error from the OpenGL API |
GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR | Behavior that has been deprecated |
GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR | Undefined behavior |
GL_DEBUG_TYPE_PORTABILITY | Some functionality is not portable |
GL_DEBUG_TYPE_PERFORMANCE | Possible performance issues |
GL_DEBUG_TYPE_MARKER | An annotation |
GL_DEBUG_TYPE_PUSH_GROUP | Messages related to debug group push |
GL_DEBUG_TYPE_POP_GROUP | Messages related to debug group pop |
GL_DEBUG_TYPE_OTHER | Other messages |
The severity parameter can have the following values:
Severity | Meaning |
GL_DEBUG_SEVERITY_HIGH | Errors or dangerous behavior |
GL_DEBUG_SEVERITY_MEDIUM | Major performance warnings, other warnings, or use of deprecated functionality |
GL_DEBUG_SEVERITY_LOW | Redundant state changes, unimportant undefined behavior |
GL_DEBUG_SEVERITY_NOTIFICATION | A notification, not an error, or performance issue |
The length parameter is the length of the message string, excluding the null terminator. The last parameter, param, is a user-defined pointer. We can use this to point to some custom objects that might be helpful to the callback function. This parameter can be set using the second parameter to glDebugMessageCallback.
Within debugCallback, we convert each GLenum parameter into a string. Due to space constraints, I don't show all of that code here, but it can be found in the example code for this book. We then print all of the information to the standard output.
The call to glDebugMessageCallback registers our callback function with the OpenGL debug system. The first parameter is a pointer to our callback function, and the second parameter (nullptr, in this example) can be a pointer to any object that we would like to pass into the callback. This pointer is passed as the last parameter with every call to debugCallback.
Finally, the call to glDebugMessageControl determines our message filters. This function can be used to selectively turn on or off any combination of message source, type, ID, or severity. In this example, we turn everything on.