Name AMD_debug_output Name Strings GL_AMD_debug_output Contact Jaakko Konttinen (jaakko.konttinen 'at' amd.com) Contributors Graham Sellers, AMD Mark Young, AMD Ahmet Oguz Akyuz, AMD Status Experimental Version Last Modified Date: May 7, 2010 Author Revision: 9 Number 395 Dependencies OpenGL 1.1 is required. WGL_ARB_create_context or GLX_ARB_create_context is required. The extension is written against the OpenGL 3.0 specification. This extension trivially interacts with ARB_vertex_program and ARB_fragment_program. Overview This extension allows the GL to notify applications when various debug events occur in contexts that have been created with the debug flag, as provided by WGL_ARB_create_context and GLX_ARB_create_context. These events are represented in the form of enumerable messages with an included human-readable translation. Examples of debug events include incorrect use of the GL, warnings of undefined behavior, and performance warnings. A message is uniquely identified by a category and an implementation- dependent ID within that category. Message categories are general and are used to organize large groups of similar messages together. Examples of categories include GL errors, performance warnings, and deprecated functionality warnings. Each message is also assigned a severity level that denotes roughly how "important" that message is in comparison to other messages across all categories. For example, notification of a GL error would have a higher severity than a performance warning due to redundant state changes. 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 any GL error or 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 order to support indirect rendering, 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 category or severity. The only requirement on the minimum quantity and type of messages that implementations of this extension must support is that a 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 categories listed by this extension in order to support this extension, and new categories can be added by other extensions. This extension places no restrictions or requirements on any additional functionality provided by the debug context flag through other extensions. IP Status No known IP claims. New Procedures and Functions void DebugMessageEnableAMD(enum category, enum severity, sizei count, const uint* ids, boolean enabled); void DebugMessageInsertAMD(enum category, enum severity, uint id, sizei length, const char* buf); void DebugMessageCallbackAMD(DEBUGPROCAMD callback, void* userParam); uint GetDebugMessageLogAMD(uint count, sizei bufsize, enum* categories, uint* severities, uint* ids, sizei* lengths, char* message); New Types The callback function that applications can define, and is accepted by DebugMessageCallbackAMD, is defined as: typedef void (APIENTRY *GLDEBUGPROCAMD)(GLuint id, GLenum category, GLenum severity, GLsizei length, const GLchar* message, GLvoid* userParam); Note that this function pointer is defined as having the same calling convention as the GL functions. New Tokens Tokens accepted by GetIntegerv: MAX_DEBUG_MESSAGE_LENGTH_AMD 0x9143 MAX_DEBUG_LOGGED_MESSAGES_AMD 0x9144 DEBUG_LOGGED_MESSAGES_AMD 0x9145 Tokens accepted by DebugMessageEnableAMD, GetDebugMessageLogAMD, DebugMessageInsertAMD, and DEBUGPROCAMD callback function for : DEBUG_SEVERITY_HIGH_AMD 0x9146 DEBUG_SEVERITY_MEDIUM_AMD 0x9147 DEBUG_SEVERITY_LOW_AMD 0x9148 Tokens accepted by DebugMessageEnableAMD, GetDebugMessageLogAMD, and DEBUGPROCAMD callback function for : DEBUG_CATEGORY_API_ERROR_AMD 0x9149 DEBUG_CATEGORY_WINDOW_SYSTEM_AMD 0x914A DEBUG_CATEGORY_DEPRECATION_AMD 0x914B DEBUG_CATEGORY_UNDEFINED_BEHAVIOR_AMD 0x914C DEBUG_CATEGORY_PERFORMANCE_AMD 0x914D DEBUG_CATEGORY_SHADER_COMPILER_AMD 0x914E DEBUG_CATEGORY_APPLICATION_AMD 0x914F DEBUG_CATEGORY_OTHER_AMD 0x9150 Additions to Chapter 2 of the OpenGL 3.0 Specification (OpenGL Operation) In section 2.5 - GL Errors: Add to the end of the section (pg 19): "If an error is generated by a debug GL context (Section 2.20), the context will send a message to the application that a GL error has occurred. This message may contain more information about the nature of the error." After section 2.19 - Primitive Clipping: Add new section: 2.20 - Debug Contexts Application developers can obtain more information from the GL runtime using a debug-enabled context. This information can include details about GL errors, undefined behavior, implementation-dependent performance warnings, or other useful hints. This information is communicated through the generation of debug messages when GL commands are executed. The application can choose to either actively query for these messages, or allow the GL to call back to the application on each message via a function pointer. 2.20.1 - Debug Messages A debug message is uniquely identified by its category and an unsigned integer message ID within that category. The category must be one of the symbolic constants listed in Table 2.12. Although every distinct message must have a unique number within a category, there is no enforcement by this extension for how GL implementations assign numbers to specific messages. Each message also has a severity level that roughly describes its significance across all categories. The severity level of a message is one of the symbolic constants defined in Table 2.13. Because messages can be disabled across all categories by severity level, this feature can be used to quickly control the volume of debug output by the application. Category Token Informs about -------------- ------------- DEBUG_CATEGORY_API_ERROR_AMD GL errors caused by invalid API use DEBUG_CATEGORY_WINDOW_SYSTEM_AMD Errors and notices from the windowing layer DEBUG_CATEGORY_DEPRECATION_AMD Use of functionality that is either deprecated or marked for future deprecation DEBUG_CATEGORY_UNDEFINED_BEHAVIOR_AMD Behavior undefined according to specification DEBUG_CATEGORY_PERFORMANCE_AMD Implementation-dependent performance warnings DEBUG_CATEGORY_SHADER_COMPILER_AMD Information from the GLSL or ARB shader compiler and linker DEBUG_CATEGORY_APPLICATION_AMD Application-generated messages DEBUG_CATEGORY_OTHER_AMD Messages that do not fit in any of the other categories ---------------------------------------------------------------------------- Table 2.12: Categories of debug messages. Each message is associated with one of these categories. Severity Level Token Suggested examples of messages -------------------- ------------------------------ DEBUG_SEVERITY_HIGH_AMD Any GL error; any undefined behavior; any GLSL or ARB shader compiler and linker errors; DEBUG_SEVERITY_MEDIUM_AMD Severe performance warnings; GLSL or ARB shader compiler and linker warnings; use of currently deprecated behavior DEBUG_SEVERITY_LOW_AMD Performance warnings from redundant state changes ---------------------------------------------------------------------------- Table 2.13: Severity levels of messagse. Each debug 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 formatting of a message string is left as implementation-dependent, although it should give a concise and legible description of the message's purpose. Messages with different IDs should also have sufficiently distinguishable string representations to warrant their separation. 2.20.2 - Receiving Messages Applications can listen for messages by providing the GL with a callback function pointer by calling: void DebugMessageCallbackAMD(DEBUGPROCAMD callback, void* userParam); With storing the address of the callback function. This function's signature must follow the type definition of DEBUGPROCAMD, and its calling convention must be the same as the calling convention of GL functions. 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 zero as the value of clears the current callback and disables message output through callbacks. Applications can specify user-specified data through the pointer . The context will store this pointer and will include it as one of the parameters of each call to the callback function. The error INVALID_OPERATION will be generated if this function is called for contexts created without the debug flag. If the application has specified a callback function in a debug context, the implementation will call that function whenever any unfiltered message is generated. The ID, category, and severity of the message are specified by the callback 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 value that was passed when calling DebugMessageCallbackAMD. The memory for is allocated, owned and released by the implementation, and should only be considered valid for the duration of the callback function call. While it is allowed to concurrently use multiple debug contexts with the same debug callback function, note that it is the application's responsibility to ensure that any work that occurs inside the debug callback function is thread-safe. Furthermore, calling any GL or window layer function from within the callback function results in undefined behavior. If no callback is set, then messages are instead stored in an internal message log up to some maximum number of strings as defined by the implementation-dependent constant MAX_DEBUG_LOGGED_MESSAGES_AMD. Each context stores its own message log and will only store messages generated by commands operating in that context. If the message log is full, then the oldest messages will be removed from the log to make room for newer ones. The application can query the number of messages currently in the log by obtaining the value of DEBUG_LOGGED_MESSAGES_AMD, and can get the contents of those messages using the command: uint GetDebugMessageLogAMD(uint count, sizei logSize, enum* categories, enum* severities, uint* ids, sizei* lengths, char* messageLog); This function will fetch as many messages as possible from the message log up to in order from oldest to newest, and will return the number of messages fetched. Those messages that were fetched will be removed from the log. The value of must be greater than zero and less than MAX_DEBUG_LOGGED_MESSAGES_AMD or otherwise the error INVALID_VALUE will be generated. The value of can be larger than the actual number of messages currently in the log. If is not a null pointer, then the string representations of all fetched messages will be stored in the buffer and will be separated by null- terminators. The maximum size of the buffer (including all null- terminators) is denoted by , and strings of messages within that do not fit in the buffer will not be fetched. If is less than zero, the error INVALID_VALUE will be generated. If is a null pointer, then the value of is ignored. The categories, severity levels, IDs, and string representation lengths of all (up to ) removed messages will be stored in the arrays , , , and , respectively. The counts stored in the array include the null-terminator of each string. Any and all of the output arrays, including , are optional, and no data is returned for those arrays that are specified with a null pointer. To simply delete up to messages from the message log and ignoring, the application can call the function with null pointers for all output arrays. The error INVALID_OPERATION will be generated by GetDebugMessageLogAMD if it is called in a non-debug context. 2.20.3 - Controlling Debug Messages Applications can control which messages are generated by calling void DebugMessageEnableAMD(enum category, enum severity, sizei count, const uint* ids, boolean enabled); This command allows disabling or enabling generation of subsets of messages. If is TRUE, the referenced subset of messages is enabled. If FALSE, then those messages are disabled. This command can reference different subsets of messages by varying its parameter values in the following ways: 1. To reference all messages, let , , and all be zero. The value of is ignored in this case. 2. To reference all messages across all categories with a specific severity level, let and be zero and let identify the severity level. The value of is ignored in this case. 3. To reference all messages within a single category, let identify the referenced category and let and be zero. The value of is ignored in this case. 4. To reference all messages within a single category and at a specific severity level, let identify the category and identify the severity level, and let be zero. The value of is ignored in this case. 5. To reference specific messages by ID within a single category, let identify the category, let be zero, let be greater than zero and let identify the IDs of messages within the identified category. Operations on message IDs that are not valid within the category are silently ignored. In all of the above cases, if is non-zero and specifies an invalid category, the error INVALID_ENUM is generated. Similarly if is non-zero and is an invalid severity level, the error INVALID_ENUM is generated. If is less than zero, the error INVALID_VALUE is generated. If the parameters do not fall into one of the cases defined above, the error INVALID_VALUE is generated. The error INVALID_OPERATION is generated if this command is called in a non-debug context. Although messages are grouped into categories and severities, and entire groups of messages can be turned off with a single call, there is no explicit per-category or per-severity enabled state. Instead the enabled state is stored individually for each message. There is no difference between disabling a category of messages with a single call, and enumerating all messages of that category and individually disabling each of them by their ID. All messages of severity level DEBUG_SEVERITY_MEDIUM_AMD and DEBUG_SEVERITY_HIGH_AMD in all categories are initially enabled, and all messages at DEBUG_SEVERITY_LOW_AMD are initially disabled. 2.20.4 - Application Messages To easily support custom application timestamps, applications can inject their own messages to the debug message stream through the command void DebugMessageInsertAMD(enum category, enum severity, uint id, sizei length, const char* buf); The value of specifies the ID for the message and indicates its severity level as defined by the application. If is not a valid severity level, the error INVALID_ENUM will be generated. The value of must be DEBUG_CATEGORY_APPLICATION_AMD, or the error INVALID_ENUM will be generated. The string contains the string representation of the message. The parameter contains the size of the message's string representation, excluding the null-terminator. If is zero, then its value is derived from the string-length of and must contain a null-terminated string. The error INVALID_VALUE will be generated if is less than zero or its derived value is larger than or equal to MAX_DEBUG_MESSAGE_LENGTH_AMD. The error INVALID_OPERATION will be generated if this function is called in a non-debug context. Additions to the OpenGL / GLX / GLX Protocol Specifications None. Additions to the WGL Specification None. Errors The error INVALID_OPERATION will be generated by DebugMessageCallbackAMD if the function is called in a non-debug context. The error INVALID_ENUM will be generated by DebugMessageEnableAMD if is non-zero and specifies an invalid category. The error INVALID_ENUM will be generated by DebugMessageEnableAMD if is non-zero and an invalid severity level. The error INVALID_VALUE will be generated by DebugMessageEnableAMD if if is less than zero. The error INVALID_VALUE will be generated by DebugMessageEnableAMD if if the combination of values for , and do not fall within one of the accepted combinations for referencing a subset of messages. The error INVALID_OPERATION will be generated by GetDebugMessageLogAMD if it is called in a non-debug context. The error INVALID_VALUE will be generated by GetDebugMessageLogAMD if the value of is zero or greater than the value of MAX_DEBUG_LOGGED_MESSAGES_AMD. The error INVALID_VALUE will be generated by GetDebugMessageLogAMD if is less than zero. The error INVALID_ENUM will be generated by DebugMessageInsertAMD if is not a valid debug severity level. The error INVALID_ENUM will be generated by DebugMessageInsertAMD if the value of is not DEBUG_CATEGORY_APPLICATION_AMD. The error INVALID_VALUE will be generated by DebugMessageInsertAMD if is less than zero. The error INVALID_VALUE will be generated by DebugMessageInsertAMD if or its derived value is larger than MAX_DEBUG_MESSAGE_LENGTH_AMD. The error INVALID_OPERATION will be generated by DebugMessageInsertAMD if this function is called in a non-debug context. New State Initial Get Value Type Get Command Value Description Sec Attribute -------------------------- ---- ----------- ----- ------------------------- ------ --------- DEBUG_LOGGED_MESSAGES_AMD Z+ GetIntegerv 0 The number of messages 2.20.2 - currently in the debug message log New Implementation Dependent State Minimum Get Value Type Get Command Value Description Sec Attribute -------------------------------- -- ----------- ----- ------------------------- ------ ---------- MAX_DEBUG_MESSAGE_LENGTH_AMD Z+ GetIntegerv 80 The maximum length of a 2.20.2 - debug message string MAX_DEBUG_LOGGED_MESSAGES_AMD Z+ GetIntegerv 1 The maximum number of 2.20.2 - 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 AMD 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. Revision History (v9, 2010-05-07, jkontti) - Removed inconsistent language from New Tokens category for tokens that are no longer accepted by DebugMessageEnableAMD since revision v5. - Cleaned up some language and formatting issues. (v8, 2010-04-09, jkontti) - Renamed extension string from AMDX to AMD. - Renamed new function, type and token suffixes from AMDX to AMD. - No changes in functionality between AMDX and AMD versions. (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