Name ARB_debug_output Name Strings GL_ARB_debug_output Contact Jaakko Konttinen (jaakko.konttinen 'at' amd.com) Contributors Graham Sellers, AMD Mark Young, AMD Ahmet Oguz Akyuz, AMD Bruce Merry, ARM Daniel Koch, TransGaming Jon Leech, Independent Pat Brown, NVIDIA Greg Roth, NVIDIA Yaki Tebeka, Graphic Remedy Notice Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Complete. Approved by the ARB on June 9, 2010. Approved by the Khronos Board of Promoters on July 23, 2010. Version Last Modified Date: July 8, 2013 Author Revision: 17 Number ARB Extension #104 Dependencies OpenGL 1.1 is required. The extension is written against the OpenGL 4.0 Core specification (March 11, 2010). The extension interacts with OpenGL 4.0 Compatibility specification and other specifications that provide display list support. The extension interacts with OpenGL 4.0 Compatibility specification and other specifications that provide the GetPointerv entry point. Overview This extension allows the GL to notify applications when various events occur that may be useful during application development and debugging. These events are represented in the form of enumerable messages with a human-readable string representation. Examples of debug events include incorrect use of the GL, warnings of undefined behavior, and performance warnings. A message is uniquely identified by a source, a type and an implementation-dependent ID within the source and type pair. A message's source identifies the origin of the message and can either describe components of the GL, the window system, third-party external sources such as external debuggers, or even the application itself. The type of the message roughly identifies the nature of the event that caused the message. Examples include errors, performance warnings, or warnings about undefined behavior. A message's ID for a given source and type further distinguishes messages within those groups. For example, an error caused by a negative parameter value or an invalid internal texture format are both errors generated by the API, but would likely have different message IDs. Each message is also assigned to a severity level that denotes roughly how "important" that message is in comparison to other messages across all sources and types. For example, notification of a GL error would likely have a higher severity than a performance warning due to redundant state changes. Finally, every message contains an implementation-dependent string representation that provides a useful description of the event. Messages are communicated to the application through an application- defined callback function that is called by the GL implementation on each debug message. The motivation for the callback routine is to free application developers from actively having to query whether a GL error, or any other debuggable event has happened after each call to a GL function. With a callback, developers can keep their code free of debug checks, and only have to react to messages as they occur. In situations where using a callback is not possible, a message log is also provided that stores copies of recent messages until they are actively queried. To control the volume of debug output, messages can be disabled either individually by ID, or entire groups of messages can be turned off based on combination of source and type. The only requirement on the minimum quantity and type of messages that implementations of this extension must support is that some sort of message must be sent notifying the application whenever any GL error occurs. Any further messages are left to the implementation. Implementations do not have to output messages from all sources nor do they have to use all types of messages listed by this extension, and both new sources and types can be added by other extensions. For performance reasons it is recommended, but not required, that implementations restrict supporting this extension only to contexts created using the debug flag as provided by WGL_create_context or GLX_create_context. This extension places no limits on any other functionality provided by debug contexts through other extensions. IP Status No known IP claims. New Procedures and Functions void DebugMessageControlARB(enum source, enum type, enum severity, sizei count, const uint* ids, boolean enabled); void DebugMessageInsertARB(enum source, enum type, uint id, enum severity, sizei length, const char* buf); void DebugMessageCallbackARB(DEBUGPROCARB callback, const void* userParam); uint GetDebugMessageLogARB(uint count, sizei bufSize, enum* sources, enum* types, uint* ids, enum* severities, sizei* lengths, char* messageLog); void GetPointerv(enum pname, void** params); New Types The callback function that applications can define, and is accepted by DebugMessageCallbackARB, is defined as: typedef void (APIENTRY *DEBUGPROCARB)(enum source, enum type, uint id, enum severity, sizei length, const char* message, const void* userParam); Note that this function pointer is defined as having the same calling convention as the GL functions. New Tokens Tokens accepted by the parameters of Enable, Disable, and IsEnabled: DEBUG_OUTPUT_SYNCHRONOUS_ARB 0x8242 Tokens accepted by the parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: MAX_DEBUG_MESSAGE_LENGTH_ARB 0x9143 MAX_DEBUG_LOGGED_MESSAGES_ARB 0x9144 DEBUG_LOGGED_MESSAGES_ARB 0x9145 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB 0x8243 Tokens accepted by the parameter of GetPointerv: DEBUG_CALLBACK_FUNCTION_ARB 0x8244 DEBUG_CALLBACK_USER_PARAM_ARB 0x8245 Tokens accepted or provided by the parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the parameter of GetDebugMessageLogARB: DEBUG_SOURCE_API_ARB 0x8246 DEBUG_SOURCE_WINDOW_SYSTEM_ARB 0x8247 DEBUG_SOURCE_SHADER_COMPILER_ARB 0x8248 DEBUG_SOURCE_THIRD_PARTY_ARB 0x8249 DEBUG_SOURCE_APPLICATION_ARB 0x824A DEBUG_SOURCE_OTHER_ARB 0x824B Tokens accepted or provided by the parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the parameter of GetDebugMessageLogARB: DEBUG_TYPE_ERROR_ARB 0x824C DEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB 0x824D DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARB 0x824E DEBUG_TYPE_PORTABILITY_ARB 0x824F DEBUG_TYPE_PERFORMANCE_ARB 0x8250 DEBUG_TYPE_OTHER_ARB 0x8251 Tokens accepted or provided by the parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the parameter of GetDebugMessageLogARB: DEBUG_SEVERITY_HIGH_ARB 0x9146 DEBUG_SEVERITY_MEDIUM_ARB 0x9147 DEBUG_SEVERITY_LOW_ARB 0x9148 Additions to Chapter 2 of the OpenGL 4.0 Core Specification (OpenGL Operation) In section 2.5 - GL Errors: Add to the end of the section (pg 19): "When an error is generated, the GL will also generate a debug output message describing its cause (see section 5.5). The message has the source DEBUG_SOURCE_API_ARB and the type DEBUG_TYPE_ERROR_ARB, and an implementation-dependent ID." Additions to Chapter 3 of the OpenGL 4.0 Core Specification (Rasterization) None. Additions to Chapter 4 of the OpenGL 4.0 Core Specification (Per-Fragment Operations and the Frame Buffer) None. Additions to Chapter 5 of the OpenGL 4.0 Core Specification (Special Functions) After section 5.4 - Hints (pg. 300), add new section: "5.5 - Debug Output Application developers can obtain more information from the GL runtime in the form of debug output. This information can include details about GL errors, undefined behavior, implementation- dependent performance warnings, or other useful hints. This information is communicated through a stream of debug messages that are generated as GL commands are executed. The application can choose to receive these messages either through a callback routine, or by querying for them from a message log. Controls are provided for disabling messages that the application does not care about, and for inserting application- generated messages into the stream. 5.5.1 - Debug Messages A debug message is uniquely identified by the source that generated it, a type within that source, and an unsigned integer ID identifying the message within that type. The message source is one of the symbolic constants listed in Table 5.3. The message type is one of the symbolic constants listed in Table 5.4. Debug Output Message Source Messages Generated by --------------------------- --------------------- DEBUG_SOURCE_API_ARB The GL DEBUG_SOURCE_SHADER_COMPILER_ARB The GLSL shader compiler or compilers for other extension-provided languages DEBUG_SOURCE_WINDOW_SYSTEM_ARB The window system, such as WGL or GLX DEBUG_SOURCE_THIRD_PARTY_ARB External debuggers or third-party middleware libraries DEBUG_SOURCE_APPLICATION_ARB The application DEBUG_SOURCE_OTHER_ARB Sources that do not fit to any of the ones listed above ---------------------------------------------------------------------------- Table 5.3: Sources of debug output messages. Each message must originate from a source listed in this table. Debug Output Message Type Informs about ------------------------- ------------- DEBUG_TYPE_ERROR_ARB Events that generated an error DEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB Behavior that has been marked for deprecation DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARB Behavior that is undefined according to the specification DEBUG_TYPE_PERFORMANCE_ARB Implementation-dependent performance warnings DEBUG_TYPE_PORTABILITY_ARB Use of extensions or shaders in a way that is highly vendor-specific DEBUG_TYPE_OTHER_ARB Types of events that do not fit any of the ones listed above ---------------------------------------------------------------------------- Table 5.4: Types of debug output messages. Each message is associated with one of these types that describes the nature of the message. Each message source and type pair contains its own namespace of messages with every message being associated with an ID. The assignment of IDs to messages within a namespace is implementation- dependent. There can potentially be overlap between the namespaces of two different pairs of source and type, so messages can only be uniquely distinguished from each other by the full combination of source, type and ID. Each message is also assigned a severity level that roughly describes its importance across all sources and types along a single global axis. The severity of a message is one of the symbolic constants defined in Table 5.5. Because messages can be disabled by their severity, this allows for quick control the global volume of debug output. Severity Level Token Suggested examples of messages -------------------- ------------------------------ DEBUG_SEVERITY_HIGH_ARB Any GL error; dangerous undefined behavior; any GLSL or ARB shader compiler and linker errors; DEBUG_SEVERITY_MEDIUM_ARB Severe performance warnings; GLSL or other shader compiler and linker warnings; use of currently deprecated behavior DEBUG_SEVERITY_LOW_ARB Performance warnings from redundant state changes; trivial undefined behavior ---------------------------------------------------------------------------- Table 5.5: Severity levels of messages. Each debug output message is associated with one of these severity levels. Every message also has a null-terminated string representation that is used to describe the message. The contents of the string can change slightly between different instances of the same message (e.g. which parameter value caused a specific GL error to occur). The format of a message string is left as implementation-dependent, although it should at least represent a concise description of the event that caused the message to be generated. Messages with different IDs should also have sufficiently distinguishable string representations to warrant their separation. The lengths of all messages, including their null terminators, must be guaranteed to be less or equal to the implementation-dependent constant MAX_DEBUG_MESSAGE_LENGTH_ARB. Messages can be either enabled or disabled. Messages that are disabled will not be generated. All messages are initially enabled unless their assigned severity is DEBUG_SEVERITY_LOW_ARB. The enabled state of messages can be changed using the command DebugMessageControlARB. 5.5.2 - Debug Message Callback Applications can provide a callback function for receiving debug messages using the command void DebugMessageCallbackARB(DEBUGPROCARB callback, const void* userParam); with storing the address of the callback function. 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 clears the current callback and disables message output through callbacks. Applications can provide user-specified data through the pointer . 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 , , , and , respectively. The string representation of the message is stored in and its length (excluding the null-terminator) is stored in . The parameter 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 DEBUG_CALLBACK_FUNCTION_ARB and 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 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. Section 5.5.6 describes this in further detail. 5.5.3 - Debug Message Log If 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 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 DEBUG_LOGGED_MESSAGES_ARB, and the string length (including its null terminator) of the oldest message in the log through the value of DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB. To fetch message data stored in the log, the command GetDebugMessageLogARB can be used. If DEBUG_CALLBACK_FUNCTION_ARB is not NULL, no generated messages will be stored in the log but will instead be passed to the debug callback routine as described in section 5.5.2. 5.5.4 - Controlling Debug Messages Applications can control the volume of debug output by disabling specific or groups of messages with the command: void DebugMessageControlARB(enum source, enum type, enum severity, sizei count, const uint* ids, boolean enabled); If is TRUE, the referenced subset of messages will be enabled. If FALSE, then those messages will be disabled. This command can reference different subsets of messages by first considering the set of all messages, and filtering out messages based on the following ways: - If is not DONT_CARE, then all messages whose source does not match will not be referenced. - If is not DONT_CARE, then all messages whose type does not match will not be referenced. - If is not DONT_CARE, then all messages whose severity level does not match will not be referenced. - If is greater than zero, then is an array of message IDs for the specified combination of and . In this case, if or is DONT_CARE, or is not DONT_CARE, the error INVALID_OPERATION is generated. If is zero, the value if is ignored. In addition, if any of , , and is not DONT_CARE and is not one of the symbols from, respectively, Table 5.3, Table 5.4, and Table 5.5, the error INVALID_ENUM is generated. If is negative, the error INVALID_VALUE is generated. Although messages are grouped into an implicit hierarchy by their sources and types, there is no explicit per-source, per-type or per-severity enabled state. Instead, the enabled state is stored individually for each message. There is no difference between disabling all messages from one source in a single call, and individually disabling all messages from that source using their types and IDs. 5.5.5 - Externally Generated Messages To support applications and third-party libraries generating their own messages, such as ones containing timestamp information or signals about specific render system events, the following function can be called void DebugMessageInsertARB(enum source, enum type, uint id, enum severity, int length, const char* buf); The value of specifies the ID for the message and indicates its severity level as defined by the caller. If is not one of the severity levels listed in Table 5.5, the error INVALID_ENUM will be generated. The value of must be one of the values from Table 5.4 and the value of must be either DEBUG_SOURCE_APPLICATION_ARB or DEBUG_SOURCE_THIRD_PARTY_ARB, or the error INVALID_ENUM will be generated. The string contains the string representation of the message. The parameter contains the number of characters in . If is negative, it is implied that contains a null terminated string. The error INVALID_VALUE will be generated if the number of characters in , excluding the null terminator when is negative, is not less than MAX_DEBUG_MESSAGE_LENGTH_ARB. 5.5.6 - Asynchronous and Synchronous Debug Output The behavior of how and when the GL driver is allowed to generate debug messages, and subsequently either call back to the application or place the message in the debug message log, is affected by the state DEBUG_OUTPUT_SYNCHRONOUS_ARB. This state can be modified by the Enable and Disable commands. Its initial value is FALSE. When DEBUG_OUTPUT_SYNCHRONOUS_ARB is disabled, the driver is optionally allowed to concurrently call the debug callback routine from potentially multiple threads, including threads that the context that generated the message is not currently bound to. The implementation may also call the callback routine asynchronously after the GL command that generated the message has already returned. The application is fully responsible for ensuring thread safety due to debug callbacks under these circumstances. In this situation the value may be helpful in identifying which application thread's command originally generated the debug callback. When DEBUG_OUTPUT_SYNCHRONOUS_ARB is enabled, the driver guarantees synchronous calls to the callback routine by the context. When synchronous callbacks are enabled, all calls to the callback routine will be made by the thread that owns the current context; all such calls will be made serially by the current context; and each call will be made before the GL command that generated the debug message is allowed to return. When no callback is specified and DEBUG_OUTPUT_SYNCHRONOUS_ARB is disabled, the driver can still asynchronously place messages in the debug message log, even after the context thread has returned from the GL function that generated those messages. When DEBUG_OUTPUT_SYNCHRONOUS_ARB is enabled, the driver guarantees that all messages are added to the log before the GL function returns. Enabling synchronous debug output greatly simplifies the responsibilities of the application for making its callback functions thread-safe, but may potentially result in drastically reduced driver performance. The DEBUG_OUTPUT_SYNCHRONOUS_ARB only guarantees intra-context synchronization for the callbacks of messages generated by that context, and does not guarantee synchronization across multiple contexts. If multiple contexts are concurrently used by the application, it is allowed for those contexts to also concurrently call their designated callbacks, and the application is responsible for handling thread safety in that situation even if DEBUG_OUTPUT_SYNCHRONOUS_ARB is enabled in all contexts." Additions to Chapter 6 of the OpenGL 4.0 Core Specification (State and State Requests) Modify the title of Section 6.1.6 - String Queries to read "Section 6.1.6 - Pointer and String Queries", and insert to the beginning of the section: The command void GetPointerv(enum pname, void** params); obtains the pointer or pointers named in the array . The possible values for are DEBUG_CALLBACK_FUNCTION_ARB and DEBUG_CALLBACK_USER_PARAM_ARB, which respectively return the current debug output callback function pointer and its application-specified user parameter. Each returns a single pointer value. After Section 6.1.14 - Renderbuffer Object Queries (pg 324): Add new Section 6.1.15 - Debug Object Queries: 6.1.15 - Debug Output Queries When no debug callback is set, debug messages are stored in a debug message log as described in section 5.5.3. Messages can be queried from the log by calling uint GetDebugMessageLogARB(uint count, sizei bufSize, enum* sources, enum* types, uint* ids, enum* severities, sizei* lengths, char* messageLog); This function fetches a maximum of messages from the message log, and will return the number of messages successfully fetched. Messages will be fetched from the log in order of oldest to newest. Those messages that were fetched will be removed from the log. The sources, types, severities, IDs, and string lengths of fetched messages will be stored in the application-provided arrays , , , , and , respectively. The application is responsible for allocating enough space for each array to hold up to elements. The string representations of all fetched messages are stored in the array. If multiple messages are fetched, their strings are concatenated into the same array and will be separated by single null terminators. The last string in the array will also be null-terminated. The maximum size of , including the space used by all null terminators, is given by . If is less than zero, the error INVALID_VALUE will be generated. If a message's string, including its null terminator, can not fully fit within the array's remaining space, then that message and any subsequent messages will not be fetched and will remain in the log. The string lengths stored in the array include the space for the null terminator of each string. Any or all of the arrays , , , , and can also be null pointers, which causes the attributes for such arrays to be discarded when messages are fetched, however those messages will still be removed from the log. Thus to simply delete up to messages from the message log while ignoring their attributes, the application can call the function with null pointers for all attribute arrays. If is NULL, the value of is ignored. Additions to the OpenGL / GLX / GLX Protocol Specifications None. Additions to the WGL Specification None. Dependencies on GL and ES profiles, versions, and other extensions Dependencies on OpenGL 4.0 Compatibility specification and any other versions or extensions that already provide the GetPointerv entry point as provided by the OpenGL 4.0 Compatibility specification - Remove the modifications to Section 6.1.6 from this specification with the exception that GetPointerv will still accept DEBUG_CALLBACK_FUNCTION_ARB and DEBUG_CALLBACK_USER_PARAM_ARB as valid values for , and will return the same values as described in Chapter 6. Dependencies on OpenGL 4.0 Compatibility specification and any other versions that support display lists - DebugMessageControlARB, DebugMessageInsertARB, DebugMessageCallbackARB, and GetDebugMessageLogARB are not compiled into display lists. Add the following to section 5.5.1 of the OpenGL 4.0 Compatibility specification, after the paragraph beginning with "GL command stream management" (pg 414): "Debug output: DebugMessageControlARB, DebugMessageInsertARB, DebugMessageCallbackARB, and GetDebugMessageLogARB" Add the same language to corresponding sections of other specifications. Errors The error INVALID_ENUM will be generated by DebugMessageControlARB if is not DONT_CARE or one of the debug output sources listed in Table 5.3. The error INVALID_ENUM will be generated by DebugMessageControlARB if is not DONT_CARE or one of the debug output types listed in Table 5.4. The error INVALID_ENUM will be generated by DebugMessageControlARB if is not DONT_CARE or one of the severity levels listed in Table 5.5. The error INVALID_VALUE will be generated by DebugMessageControlARB if is less than zero. The error INVALID_OPERATION will be generated by DebugMessageControlARB when is greater than zero and is DONT_CARE. The error INVALID_OPERATION will be generated by DebugMessageControlARB when is greater than zero and is DONT_CARE. The error INVALID_OPERATION will be generated by DebugMessageControlARB when is greater than zero and and is not DONT_CARE. The error INVALID_VALUE will be generated by GetDebugMessageLogARB if the value of is less than zero. The error INVALID_VALUE will be generated by GetDebugMessageLogARB if is less than zero. The error INVALID_ENUM will be generated by DebugMessageInsertARB if the value of is not DEBUG_SOURCE_APPLICATION_ARB or DEBUG_SOURCE_THIRD_PARTY_ARB. The error INVALID_ENUM will be generated by DebugMessageInsertARB if the value of is not one of the values from Table 5.4. The error INVALID_ENUM will be generated by DebugMessageInsertARB if is not a valid debug severity level listed in Table 5.5. The error INVALID_VALUE will be generated by DebugMessageInsertARB if the number of characters in , excluding the null terminator when is negative, is not less than MAX_DEBUG_MESSAGE_LENGTH_ARB. New State Add new table 6.55 after p.376 (Debug Output): Initial Get Value Type Get Command Value Description Sec Attribute -------------------------- ---- ----------- ----- ------------------------- ------ --------- DEBUG_CALLBACK_FUNCTION_ARB Y GetPointerv NULL The current debug output 5.5.2 - callback function pointer DEBUG_CALLBACK_USER_PARAM_ARB Y GetPointerv NULL The current debug output 5.5.2 - callback user parameter DEBUG_LOGGED_MESSAGES_ARB Z+ GetIntegerv 0 The number of messages 5.5.3 - currently in the debug message log DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB Z+ GetIntegerv 0 The string length of the 5.5.3 - oldest debug message in the debug message log DEBUG_OUTPUT_SYNCHRONOUS_ARB B IsEnabled FALSE The enabled state for 5.5.6 synchronous debug message callbacks New Implementation Dependent State Add new table 6.56 after table 6.55 (Implementation Dependent Debug Output Values): Minimum Get Value Type Get Command Value Description Sec Attribute -------------------------------- -- ----------- ----- ------------------------- ------ --------- MAX_DEBUG_MESSAGE_LENGTH_ARB Z+ GetIntegerv 1 The maximum length of a 5.5.1 - debug message string, including its null terminator MAX_DEBUG_LOGGED_MESSAGES_ARB Z+ GetIntegerv 1 The maximum number of 5.5.3 - messages stored in the debug message log Issues 01) Should we reserve tokens for arbitrary vendor-specific categories (e.g. DEBUG_CATEGORY_VENDOR0)? RESOLVED: No. Since this is an ARB extension, there is no reason to do this now in the current version. 02) Should we allow explicit controls for printing to stderr or through OutputDebugString instead of the callback? RESOLVED: No. It is up to the application to setup this behavior itself using the provided functionality. 03) How do the different filtering rules interact? If a category is filtered, but a message in that same category is set to be unfiltered by ID or severity level, should that message still be filtered? If I specifically filter a category and then unfilter all messages globally with a later command, should that category still be filtered? RESOLVED: Message enable state is stored individually for each message. There is no explicit group-wise enable state or different ordered levels of "enabledness" in the implied hierarchy of messages. Operations on groups of messages affect all messages within that group individually, and overwrite the previous and individual state of those messages. 04) Should applications be allowed to insert their own messages through a custom category? How would this be done? RESOLVED: Yes. A new category will be provided for application-specific messages and an entry point will be provided to write messages in that category. 05) Should we provide a mechanism to ensure synchronized calls of the debug output callback by the implementation? RESOLVED: Yes. This is useful for the application to observe which GL function caused a specific message to be generated by observing the debugger call stack. It will also simplify the application's responsibility for creating a thread-safe callback routine at the understood price of potential reduced driver performance when the debug layer is active. A new state DEBUG_OUTPUT_SYNCHRONOUS_CALLBACK_ARB will be provided that can be enabled by the application to provide this functionality. 06) Is it possible that multi-threaded drivers that generate messages asynchronously into the message log can cause a race condition where a message is inserted between the time an application queries DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB and the attempted fetch of the oldest message? RESOLVED: Yes. When the message log is full, the oldest message would be bumped out by the new message which would make the queried value incorrect. A solution to this is to make the message log discard messages when it has filled up but otherwise preserve its contents. A similar race condition can still occur when querying DEBUG_LOGGED_MESSAGES_ARB when the message log is not full. However in this case the value at the time of the fetch can only either be equal or greater than at the time of the query, and neither case will result in lost information. The synchronous callback toggle has also been modified to also explicitly affect the placing of messages into the message log. Revision History (v17, 2013-07-08, Jon Leech) - Change type of userParam parameter to DebugMessageCallbackARB and GLDEBUGPROCARB from 'void *' to 'const void *' to match GL core and KHR_debug (Bug 10083). (v16, 2013-04-16, Jon Leech) - Fix type of parameter in GetDebugMessageLog body (Bug 10083) (v15, 2012-06-22, Piers Daniell) - Restored the ARB suffixes removed by mistake. (v14, 2012-06-19, Jon Leech) - Change logSize parameter to bufSize (v13, 2012-04-19, pdaniell) - Remove ARB suffixs to make the extension ready for OpenGL 4.3. (v12, 2010-06-01, jkontti) - Added DEBUG_TYPE_PORTABILITY_ARB - Renamed DEBUG_OUTPUT_SYNCHRONOUS_CALLBACK_ARB to DEBUG_OUTPUT_SYNCHRONOUS_ARB and made it explicitly affect not just callbacks but also messages in the message log. - Moved discussion abotu DEBUG_OUTPUT_SYNCHRONOUS_ARB to its own section 5.5.6 - When the message log fills up, new messages will be discarded instead of bumping off old messages (issue 6). - Removed restrictions from third-party sources for DebugMessageControlARB - Removed restrictions on for DebugMessageInsertARB (v11, 2010-05-28, jkontti) - Added DEBUG_OUTPUT_SYNCHRONOUS_CALLBACK_ARB enable state for applications to be guaranteed that the debug callback is not called asynchronously or concurrently by the implementation - Created tables 6.55 and 6.56 for new introduced state and implementation-dependent state - Moved sections 2.21.x to 5.5.x - Moved tables 2.15 to 5.3, 2.16 to 5.4, and 2.17 to 5.5 - Changed minimum value of MAX_DEBUG_MESSAGE_LENGTH_ARB to 1 - Renamed DebugMessageEnableARB to DebugMessageControlARB - For DebugMessageControlARB, DONT_CARE will now be used as the enum to ignore filtered message properties instead of NONE (v10, 2010-05-13, jkontti) - Split category attribute to orthogonal source and type. This requires all new tokens (currently missing). - Table 2.15 now refers to debug output source - Table 2.16 now refers to debug output type - New table 2.17 that now contains debug output severity (v9, 2010-05-11, jkontti) - Rewrote against OpenGL 4.0 Core specification: Section 2.20 renamed to 2.21 and tables 2.12 and 2.13 are now 2.15 and 2.16 - Added missing sections for changes to Chapters 3-6. - Removed explicit language about contexts created using the debug flag. Instead, implementations can choose, but are not required to, only support this extension in contexts created with the debug flag. - Added Dependencies section to discuss behavior of the debug output entry points when used inside display lists. - Added new entry point GetPointerv since it is missing in core profiles. - Added new state DEBUG_CALLBACK_FUNCTION_ARB, DEBUG_CALLBACK_USER_PARAM_ARB, DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB (token values still missing). - Rewrote sections of GetDebugMessageLog to be clearer and changed some of the error generation. - DebugMessageInsert parameter can now be negative which indicates that the passed-in string is null-terminated. - Updated contributors section (v8, 2010-05-07, jkontti) - Removed inconsistent language from New Tokens category for tokens that are no longer accepted by DebugMessageEnableARB since revision v5. - Cleaned up some language and formatting issues. (v7, 2010-01-21, jkontti) - Added user-specifiable parameter to debug message callback function. (v6, 2010-01-15, jkontti) - Updated contact section. - Updated contributor section. - Updated status section. - Updated enums. (v5, 2009-09-17, jkontti) - Message ID namespaces are now contained within categories instead of being in a single global namespace. - Reworked DebugMessageEnable to allow disabling/enabling more combinations of messages. - Resolved issue 01. - Resolved issue 03. (v4, 2009-09-16, jkontti) - Added category as a parameter to DebugMessageInsert for future-proofing purposes, - Added missing errors to DebugMessageInsert and GetDebugMessageLog. - Added missing tokens to New Tokens. - Renamed DebugMessageFilter to DebugMessageEnable. (v3, 2009-09-15, myoung) - Cleaned up some language - Added values using AMD reserved ranges. Values do not overlap so can be re-used. (v2, 2009-09-15, jkontti) - Application-generated messages. - More categories (window system, deprecation, profile, application). (v1, 2009-09-09, jkontti) - Initial revision.