Specifies a callback function for receiving debug messages.
This function's prototype must follow the type definition of DEBUGPROCARB including its platform-dependent calling convention. Anything else will result
in undefined behavior. Only one debug callback can be specified for the current context, and further calls overwrite the previous callback. Specifying
NULL as the value of
callback clears the current callback and disables message output through callbacks. Applications can provide
user-specified data through the pointer
userParam. The context will store this pointer and will include it as one of the parameters in each call
to the callback function.
If the application has specified a callback function for receiving debug output, the implementation will call that function whenever any enabled message
is generated. The source, type, ID, and severity of the message are specified by the DEBUGPROCARB parameters
source,
type,
id,
and
severity, respectively. The string representation of the message is stored in
message and its length (excluding the null-terminator)
is stored in
length. The parameter
userParam is the user-specified parameter that was given when calling DebugMessageCallbackARB.
Applications can query the current callback function and the current user-specified parameter by obtaining the values of
#GL_DEBUG_CALLBACK_FUNCTION_ARBand
#GL_DEBUG_CALLBACK_USER_PARAM_ARB, respectively.
Applications that specify a callback function must be aware of certain special conditions when executing code inside a callback when it is called by the
GL, regardless of the debug source.
The memory for
message is owned and managed by the GL, and should only be considered valid for the duration of the function call.
The behavior of calling any GL or window system function from within the callback function is undefined and may lead to program termination.
Care must also be taken in securing debug callbacks for use with asynchronous debug output by multi-threaded GL implementations.
If
#GL_DEBUG_CALLBACK_FUNCTION_ARB is
NULL, then debug messages are instead stored in an internal message log up to some maximum number of messages as
defined by the value of
#GL_MAX_DEBUG_LOGGED_MESSAGES_ARB.
Each context stores its own message log and will only store messages generated by commands operating in that context. If the message log fills up, then
any subsequently generated messages will not be placed in the log until the message log is cleared, and will instead be discarded.
Applications can query the number of messages currently in the log by obtaining the value of
#GL_DEBUG_LOGGED_MESSAGES_ARB, and the string length
(including its null terminator) of the oldest message in the log through the value of
#GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB.