| Name |
| |
| KHR_debug |
| |
| Name Strings |
| |
| GL_KHR_debug |
| |
| Contact |
| |
| Christophe Riccio (christophe.riccio 'at' amd.com) |
| |
| Contributors |
| |
| Jaakko Konttinen, AMD |
| 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 |
| Piers Daniell, NVIDIA |
| Seth Sowerby, Apple |
| Benj Lipchak, Apple |
| Jean-François Roy, Apple |
| Daniel Rakos, AMD |
| Mark Callow, HI |
| |
| Notice |
| |
| Copyright (c) 2012-2014 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 and OpenGL ES Working Groups. 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 2012/06/18. |
| Approved by the OpenGL ES WG on 2012/06/15. |
| Ratified by the Khronos Board of Promoters on 2012/07/27. |
| |
| Version |
| |
| Last Modified Date: July 2, 2015 |
| Author Revision: 17 |
| |
| Number |
| |
| ARB Extension #119 |
| OpenGL ES Extension #118 |
| |
| Dependencies |
| |
| OpenGL 1.1 is required. |
| |
| The extension is written against the OpenGL 4.2 Compatibility Profile |
| specification (April 27, 2012). |
| |
| Overview |
| |
| This extension allows the GL to notify applications when various events |
| occur that may be useful during application development, debugging and |
| profiling. |
| |
| 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, |
| warnings about undefined behavior or notifications identifying that the |
| application is within a specific section of the application code. |
| |
| A message's ID for a given source and type further distinguishes messages |
| within namespaces. 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. |
| |
| Furthermore, 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, set breakpoints in the callback function, 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 only 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 sets of messages can be turned off based on |
| combination of source and type, through the entire application code or |
| only section of the code encapsulated in debug groups. A debug group may |
| also be used to annotate the command stream using descriptive texts. |
| |
| This extension also defines debug markers, a mechanism for the OpenGL |
| application to annotate the command stream with markers for discrete |
| events. |
| |
| When profiling or debugging an OpenGL application with a built-in or an |
| external debugger or profiler, it is difficult to relate the commands |
| within the command stream to the elements of the scene or parts of the |
| program code to which they correspond. Debug markers and debug groups help |
| obviate this by allowing applications to specify this link. For example, a |
| debug marker can be used to identify the beginning of a frame in the |
| command stream and a debug group can encapsulate a specific command stream |
| to identify a rendering pass. Debug groups also allow control of the debug |
| outputs volume per section of an application code providing an effective |
| way to handle the massive amount of debug outputs that drivers can |
| generate. |
| |
| Some existing implementations of ARB_debug_output only expose the |
| ARB_debug_output extension string if the context was created with the |
| debug flag {GLX|WGL}_CONTEXT_DEBUG_BIT_ARB as specified in |
| {GLX|WGL}_ARB_create_context. The behavior is not obvious when the |
| functionality is brought into the OpenGL core specification because the |
| extension string and function entry points must always exist. |
| |
| This extension modifies the existing ARB_debug_output extension to allow |
| implementations to always have an empty message log. The specific messages |
| written to the message log or callback routines are already implementation |
| defined, so this specification simply makes it explicit that it's fine for |
| there to be zero messages generated, even when a GL error occurs, which is |
| useful if the context is non-debug. |
| |
| Debug output can be enabled and disabled by changing the DEBUG_OUTPUT |
| state. It is implementation defined how much debug output is generated if |
| the context was created without the CONTEXT_DEBUG_BIT set. This is a new |
| query bit added to the existing GL_CONTEXT_FLAGS state to specify whether |
| the context was created with debug enabled. |
| |
| Finally, this extension defines a mechanism for OpenGL applications to |
| label their objects (textures, buffers, shaders, etc.) with a descriptive |
| string. |
| |
| When profiling or debugging an OpenGL application within an external or |
| built-in (debut output API) debugger or profiler it is difficult to |
| identify objects from their object names (integers). |
| |
| Even when the object itself is viewed it can be problematic to |
| differentiate between similar objects. Attaching a descriptive string, a |
| label, to an object obviates this difficulty. |
| |
| The intended purpose of this extension is purely to improve the user |
| experience within OpenGL development tools and application built-in |
| profilers and debuggers. This extension typically improves OpenGL |
| programmers efficiency by allowing them to instantly detect issues and the |
| reason for these issues giving him more time to focus on adding new |
| features to an OpenGL application. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Procedures and Functions |
| |
| NOTE: when implemented in an OpenGL ES context, all entry points defined |
| by this extension must have a "KHR" suffix. When implemented in an |
| OpenGL context, all entry points must have NO suffix, as shown below. |
| |
| void DebugMessageControl(enum source, |
| enum type, |
| enum severity, |
| sizei count, |
| const uint* ids, |
| boolean enabled); |
| |
| void DebugMessageInsert(enum source, |
| enum type, |
| uint id, |
| enum severity, |
| sizei length, |
| const char* buf); |
| |
| void DebugMessageCallback(DEBUGPROC callback, |
| const void* userParam); |
| |
| uint GetDebugMessageLog(uint count, |
| sizei bufSize, |
| enum* sources, |
| enum* types, |
| uint* ids, |
| enum* severities, |
| sizei* lengths, |
| char* messageLog); |
| |
| void GetPointerv(enum pname, |
| void** params); |
| |
| void PushDebugGroup(enum source, uint id, sizei length, |
| const char * message); |
| |
| void PopDebugGroup(void); |
| |
| void ObjectLabel(enum identifier, uint name, sizei length, |
| const char *label); |
| |
| void GetObjectLabel(enum identifier, uint name, sizei bufSize, |
| sizei *length, char *label); |
| |
| void ObjectPtrLabel(void* ptr, sizei length, |
| const char *label); |
| |
| void GetObjectPtrLabel(void* ptr, sizei bufSize, |
| sizei *length, char *label); |
| |
| |
| New Types |
| |
| NOTE: when implemented in an OpenGL ES context, this typedef must have a |
| "KHR" suffix (GLDEBUGPROCKHR). When implemented in an OpenGL context, |
| thie typedef must have NO suffix, as shown below. |
| |
| The callback function that applications can define, and |
| is accepted by DebugMessageCallback, is defined as: |
| |
| typedef void (APIENTRY *GLDEBUGPROC)(GLenum source, |
| GLenum type, |
| GLuint id, |
| GLenum severity, |
| GLsizei length, |
| const GLchar* message, |
| const void* userParam); |
| |
| Note that this function pointer is defined as having the same calling |
| convention as the GL functions. |
| |
| New Tokens |
| |
| NOTE: when implemented in an OpenGL ES context, all tokens defined by |
| this extension must have a "_KHR" suffix. When implemented in an OpenGL |
| context, all tokens must have NO suffix, as described below. |
| |
| Tokens accepted by the <target> parameters of Enable, Disable, and |
| IsEnabled: |
| |
| DEBUG_OUTPUT 0x92E0 |
| DEBUG_OUTPUT_SYNCHRONOUS 0x8242 |
| |
| Returned by GetIntegerv when <pname> is CONTEXT_FLAGS: |
| |
| CONTEXT_FLAG_DEBUG_BIT 0x00000002 |
| |
| Tokens accepted by the <value> parameters of GetBooleanv, GetIntegerv, |
| GetFloatv, GetDoublev and GetInteger64v: |
| |
| MAX_DEBUG_MESSAGE_LENGTH 0x9143 |
| MAX_DEBUG_LOGGED_MESSAGES 0x9144 |
| DEBUG_LOGGED_MESSAGES 0x9145 |
| DEBUG_NEXT_LOGGED_MESSAGE_LENGTH 0x8243 |
| MAX_DEBUG_GROUP_STACK_DEPTH 0x826C |
| DEBUG_GROUP_STACK_DEPTH 0x826D |
| MAX_LABEL_LENGTH 0x82E8 |
| |
| Tokens accepted by the <pname> parameter of GetPointerv: |
| |
| DEBUG_CALLBACK_FUNCTION 0x8244 |
| DEBUG_CALLBACK_USER_PARAM 0x8245 |
| |
| Tokens accepted or provided by the <source> parameters of |
| DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the <sources> |
| parameter of GetDebugMessageLog (some commands restrict <source> to a |
| subset of these parameters; see the specification body for details): |
| |
| DEBUG_SOURCE_API 0x8246 |
| DEBUG_SOURCE_WINDOW_SYSTEM 0x8247 |
| DEBUG_SOURCE_SHADER_COMPILER 0x8248 |
| DEBUG_SOURCE_THIRD_PARTY 0x8249 |
| DEBUG_SOURCE_APPLICATION 0x824A |
| DEBUG_SOURCE_OTHER 0x824B |
| |
| Tokens accepted or provided by the <type> parameters of |
| DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the <types> |
| parameter of GetDebugMessageLog: |
| |
| DEBUG_TYPE_ERROR 0x824C |
| DEBUG_TYPE_DEPRECATED_BEHAVIOR 0x824D |
| DEBUG_TYPE_UNDEFINED_BEHAVIOR 0x824E |
| DEBUG_TYPE_PORTABILITY 0x824F |
| DEBUG_TYPE_PERFORMANCE 0x8250 |
| DEBUG_TYPE_OTHER 0x8251 |
| DEBUG_TYPE_MARKER 0x8268 |
| |
| Tokens accepted or provided by the <type> parameters of |
| DebugMessageControl and DEBUGPROC, and the <types> parameter of |
| GetDebugMessageLog: |
| |
| DEBUG_TYPE_PUSH_GROUP 0x8269 |
| DEBUG_TYPE_POP_GROUP 0x826A |
| |
| Tokens accepted or provided by the <severity> parameters of |
| DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, |
| and the <severities> parameter of GetDebugMessageLog: |
| |
| DEBUG_SEVERITY_HIGH 0x9146 |
| DEBUG_SEVERITY_MEDIUM 0x9147 |
| DEBUG_SEVERITY_LOW 0x9148 |
| DEBUG_SEVERITY_NOTIFICATION 0x826B |
| |
| Returned by GetError: |
| |
| STACK_UNDERFLOW 0x0504 |
| STACK_OVERFLOW 0x0503 |
| |
| Tokens accepted or provided by the <identifier> parameters of |
| ObjectLabel and GetObjectLabel: |
| |
| BUFFER 0x82E0 |
| SHADER 0x82E1 |
| PROGRAM 0x82E2 |
| VERTEX_ARRAY |
| QUERY 0x82E3 |
| PROGRAM_PIPELINE 0x82E4 |
| TRANSFORM_FEEDBACK |
| SAMPLER 0x82E6 |
| TEXTURE |
| RENDERBUFFER |
| FRAMEBUFFER |
| [[ Compatibility Profile ]] |
| DISPLAY_LIST 0x82E7 |
| [[ End Profile-Specific Language ]] |
| |
| Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, |
| GetFloatv, GetDoublev, and GetInteger64v: |
| |
| MAX_LABEL_LENGTH |
| |
| Additions to Chapter 2 of the OpenGL 4.2 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 and the type DEBUG_TYPE_ERROR, and an |
| implementation-dependent ID." |
| |
| Additions to Chapter 3 of the OpenGL 4.2 Specification |
| (Rasterization) |
| |
| None. |
| |
| Additions to Chapter 4 of the OpenGL 4.2 Specification |
| (Per-Fragment Operations and the Frame Buffer) |
| |
| None. |
| |
| Additions to Chapter 5 of the OpenGL 4.2 Specification |
| (Special Functions) |
| |
| After section 5.4 - Hints (pg. 300) (section 5.3, p 217 in OpenGL ES 3.0), |
| 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. |
| |
| The GL may provide different levels of debug output depending on how the |
| context was created. If the context was created without the |
| CONTEXT_FLAG_DEBUG_BIT in the CONTEXT_FLAGS state, as described in Section |
| 6.1.12, then the GL may optionally not generate any debug messages, but |
| the functions described below will otherwise operate without error. |
| |
| Debug output functionality is controlled with the DEBUG_OUTPUT enable |
| state. If the context is created with the CONTEXT_FLAG_DEBUG_BIT set then |
| the initial state of DEBUG_OUTPUT is TRUE, otherwise the initial state of |
| DEBUG_OUTPUT is FALSE. In a debug context, if DEBUG_OUTPUT is disabled the |
| GL will not generate any debug output logs or callbacks. Enabling |
| DEBUG_OUTPUT again will enable full debug output functionality. If the |
| context was created without the CONTEXT_FLAG_DEBUG_BIT and the |
| DEBUG_OUTPUT is later enabled, the level of debug output logging is |
| defined by the GL implementation, which may have zero debug output. To |
| guarantee the full debug output support of the GL implementation the |
| context should be created with CONTEXT_FLAG_DEBUG_BIT context flag bit |
| set. |
| |
| 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 The GL |
| |
| DEBUG_SOURCE_SHADER_COMPILER The GLSL shader compiler or compilers for |
| other extension-provided languages |
| |
| DEBUG_SOURCE_WINDOW_SYSTEM The window system, such as WGL or GLX |
| |
| DEBUG_SOURCE_THIRD_PARTY External debuggers or third-party middleware |
| libraries |
| |
| DEBUG_SOURCE_APPLICATION The application |
| |
| DEBUG_SOURCE_OTHER 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 Events that generated an error |
| |
| DEBUG_TYPE_DEPRECATED_BEHAVIOR Behavior that has been marked for |
| deprecation |
| |
| DEBUG_TYPE_UNDEFINED_BEHAVIOR Behavior that is undefined according to |
| the specification |
| |
| DEBUG_TYPE_PERFORMANCE Implementation-dependent performance |
| warnings |
| |
| DEBUG_TYPE_PORTABILITY Use of extensions or shaders in a way that |
| is highly vendor-specific |
| |
| DEBUG_TYPE_OTHER Types of events that do not fit any of |
| the ones listed above |
| |
| DEBUG_TYPE_MARKER Annotation of the command stream |
| |
| DEBUG_TYPE_PUSH_GROUP Entering a debug group |
| |
| DEBUG_TYPE_POP_GROUP Leaving a debug group |
| |
| ---------------------------------------------------------------------------- |
| 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 Any GL error; dangerous undefined behavior; |
| any GLSL or ARB shader compiler and |
| linker errors; |
| |
| DEBUG_SEVERITY_MEDIUM Severe performance warnings; GLSL |
| or other shader compiler and linker |
| warnings; use of currently deprecated |
| behavior |
| |
| DEBUG_SEVERITY_LOW Performance warnings from redundant |
| state changes; trivial undefined behavior |
| |
| DEBUG_SEVERITY_NOTIFICATION Any message which is not an |
| error or performance concern |
| |
| ---------------------------------------------------------------------------- |
| 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 value of the |
| implementation-dependent constant MAX_DEBUG_MESSAGE_LENGTH. |
| |
| 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. The enabled state of messages can |
| be changed using the command DebugMessageControl. |
| |
| 5.5.2 - Debug Message Callback |
| |
| Applications can provide a callback function for receiving debug messages |
| using the command |
| |
| void DebugMessageCallback(DEBUGPROC callback, |
| const void* userParam); |
| |
| with <callback> storing the address of the callback function. This |
| function's prototype must follow the type definition of DEBUGPROC |
| 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 DEBUGPROC 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 DebugMessageCallback. |
| |
| Applications can query the current callback function and the current |
| user-specified parameter by obtaining the values of |
| DEBUG_CALLBACK_FUNCTION and DEBUG_CALLBACK_USER_PARAM, 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. |
| Section 5.5.6 describes this in further detail. |
| |
| If the DEBUG_OUTPUT state is disabled then the GL will not call the |
| callback function. |
| |
| 5.5.3 - Debug Message Log |
| |
| If DEBUG_CALLBACK_FUNCTION 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. |
| |
| 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, and the string length |
| (including its null terminator) of the oldest message in the log through |
| the value of DEBUG_NEXT_LOGGED_MESSAGE_LENGTH. |
| |
| To fetch message data stored in the log, the command GetDebugMessageLog |
| can be used as described in section 6.1.15. |
| |
| If DEBUG_CALLBACK_FUNCTION 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. |
| |
| If the DEBUG_OUTPUT state is disabled then no messages are added to the |
| message log. |
| |
| 5.5.4 - Controlling Debug Messages |
| |
| Applications can control the volume of debug output in the active debug |
| group, by disabling specific or groups of messages with the command: |
| |
| void DebugMessageControl(enum source, |
| enum type, |
| enum severity, |
| sizei count, |
| const uint* ids, |
| boolean enabled); |
| |
| If <enabled> 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 <source>, <type>, or <severity> is DONT_CARE, the messages from |
| all sources, of all types, or of all severities are referenced |
| respectively. |
| |
| - When values other than DONT_CARE are specified, all messages whose |
| source, type, or severity match the specified <source>, <type>, or |
| <severity> respectively will be referenced. |
| |
| - If <count> is greater than zero, then <ids> is an array of <count> |
| message IDs for the specified combination of <source> and <type>. In |
| this case, if <source> or <type> is DONT_CARE, or <severity> is not |
| DONT_CARE, the error INVALID_OPERATION is generated. |
| |
| Unrecognized message IDs in <ids> are ignored. If <count> is zero, |
| the value if <ids> is ignored. |
| |
| In addition, if any of <source>, <type>, and <severity> 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 <count> 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. |
| |
| If the DEBUG_OUTPUT state is disabled the GL operates the same as |
| if messages of every <source>, <type> or <severity> are disabled. |
| |
| 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 DebugMessageInsert(enum source, |
| enum type, |
| uint id, |
| enum severity, |
| int length, |
| const char* buf); |
| |
| The value of <id> specifies the ID for the message and <severity> |
| indicates its severity level as defined by the caller. If <severity> is |
| not one of the severity levels listed in Table 5.5, the error |
| INVALID_ENUM will be generated. The value of <type> must be one of the |
| values from Table 5.4 and the value of <source> must be either |
| DEBUG_SOURCE_APPLICATION or DEBUG_SOURCE_THIRD_PARTY, or the error |
| INVALID_ENUM will be generated. The string <buf> contains the string |
| representation of the message. The parameter <length> contains the number |
| of characters in <buf>. If <length> is negative, it is implied that <buf> |
| contains a null terminated string. The error INVALID_VALUE will be |
| generated if the number of characters in <buf>, excluding the null |
| terminator when <length> is negative, is not less than the value of |
| MAX_DEBUG_MESSAGE_LENGTH. |
| |
| If the DEBUG_OUTPUT state is disabled calls to DebugMessageInsert are |
| discarded and do not generate an error. |
| |
| 5.5.6 - Debug Groups |
| |
| Debug groups provide a method for annotating a command stream with |
| discrete groups of commands using a descriptive text. Debug output |
| messages, either generated by the implementation or inserted by the |
| application with DebugMessageInsert are written to the active debug group, |
| the top of the debug group stack. Debug groups are strictly hierarchical. |
| Their sequences may be nested within other debug groups but can not |
| overlap. If no debug group has been pushed by the application then the |
| active debug group is the default debug group. |
| |
| The command |
| |
| void PushDebugGroup(enum source, uint id, sizei length, |
| const char *message); |
| |
| pushes a debug group described by the string <message> into the command |
| stream. The value of <id> specifies the ID of messages generated. The |
| parameter <length> contains the number of characters in <message>. If |
| <length> is negative, it is implied that <message> contains a null |
| terminated string. The message has the specified <source> and <id>, <type> |
| DEBUG_TYPE_PUSH_GROUP, and <severity> DEBUG_SEVERITY_NOTIFICATION. The GL |
| will put a new debug group on top of the debug group stack which inherits |
| the control of the volume of debug output of the debug group previously |
| residing on the top of the debug group stack. Because debug groups are |
| strictly hierarchical, any additional control of the debug output volume |
| will only apply within the active debug group and the debug groups pushed |
| on top of the active debug group. |
| |
| An INVALID_ENUM error is generated if the value of <source> is neither |
| DEBUG_SOURCE_APPLICATION nor DEBUG_SOURCE_THIRD_PARTY. An INVALID_VALUE |
| error is generated if <length> is negative and the number of characters in |
| <message>, excluding the null-terminator, is not less than the value of |
| MAX_DEBUG_MESSAGE_LENGTH. |
| |
| The command |
| |
| void PopDebugGroup(); |
| |
| pops the active debug group. When a debug group is popped, the GL |
| will also generate a debug output message describing its cause based |
| on the <message> string, the source <source>, and an ID <id> submitted |
| to the associated PushDebugGroup command. DEBUG_TYPE_PUSH_GROUP |
| and DEBUG_TYPE_POP_GROUP share a single namespace for message <id>. |
| <severity> has the value DEBUG_SEVERITY_NOTIFICATION. The <type> |
| has the value DEBUG_TYPE_POP_GROUP. Popping a debug group restores |
| the debug output volume control of the parent debug group. |
| |
| Attempting to pop the default debug group off the stack generates a |
| STACK_UNDERFLOW error; pushing a debug group onto a stack containing |
| MAX_DEBUG_GROUP_STACK_DEPTH minus one elements will generate a |
| STACK_OVERFLOW error. |
| |
| 5.5.7 - 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. This state can be modified by the Enable and |
| Disable commands. Its initial value is FALSE. |
| |
| When DEBUG_OUTPUT_SYNCHRONOUS 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 <userParam> value may be |
| helpful in identifying which application thread's command originally |
| generated the debug callback. |
| |
| When DEBUG_OUTPUT_SYNCHRONOUS 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 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 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. |
| |
| DEBUG_OUTPUT_SYNCHRONOUS 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 is enabled in all contexts." |
| |
| 5.5.8 Debug Labels: |
| |
| Debug labels provide a method for annotating any object (texture, buffer, |
| shader, etc.) with a descriptive text label. These labels may then be used |
| by the debug output (see section 5.5) or an external tool such as a |
| debugger or profiler to describe labelled objects. |
| |
| The command |
| |
| void ObjectLabel(enum identifier, uint name, sizei length, const char *label); |
| |
| labels the object identified by <name> and its namespace <identifier>. |
| <identifier> must be one of the tokens in table 5.1, indicating the type |
| of the object corresponding to <name>. |
| |
| |
| Identifier Object Type |
| --------------------------------------- |
| BUFFER | buffer |
| SHADER | shader |
| PROGRAM | program |
| VERTEX_ARRAY | vertex array |
| QUERY | query |
| PROGRAM_PIPELINE | program pipeline |
| TRANSFORM_FEEDBACK| transform feedback |
| SAMPLER | sampler |
| TEXTURE | texture |
| RENDERBUFFER | render buffer |
| FRAMEBUFFER | frame buffer |
| [[ Compatibility Profile Only]] |
| DISPLAY_LIST | display list |
| [[ End Profile-Specific Language ]] |
| --------------------------------------- |
| Table 5.1. Valid object namespace identifiers and the corresponding |
| object type. |
| |
| The command |
| |
| void ObjectPtrLabel(void* ptr, sizei length, const char *label); |
| |
| labels a sync object identified by <ptr>. |
| |
| <label> contains a string used to label an object. <length> contains the |
| number of characters in <label>. If <length> is negative, it is implied that |
| <label> contains a null-terminated string. If <label> is NULL, any debug |
| label is effectively removed from the object. |
| |
| An INVALID_ENUM error is generated by ObjectLabel if <identifier> is not |
| one of the object types listed in table 5.1. |
| |
| An INVALID_VALUE error is generated by ObjectLabel if <name> is not |
| the name of a valid object of the type specified by <identifier>. |
| |
| An INVALID_VALUE is generated if the <ptr> parameter of ObjectPtrLabel |
| is not the name of a sync object. |
| |
| An INVALID_VALUE error is generated if the number of characters in |
| <label>, excluding the null terminator when <length> is negative, is not |
| less than the value of MAX_LABEL_LENGTH. |
| |
| A label is part of the state of the object to which it is associated. |
| The initial state of an object's label is the empty string. Labels need |
| not be unique. |
| |
| |
| Additions to Chapter 6 of the OpenGL 4.2 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 <pname> in the array <params>. |
| The possible values for <pname> are DEBUG_CALLBACK_FUNCTION and |
| DEBUG_CALLBACK_USER_PARAM, which respectively return the current |
| debug output callback function pointer and its application-specified |
| user parameter. Each <pname> returns a single pointer value. |
| |
| Modify Section 6.1.12 "Pointer and String Queries" |
| |
| Add to the paragraph describing the context profile mask and flags |
| (preceding the description of GetStringi) on page 485: |
| |
| "If CONTEXT_FLAG_DEBUG_BIT is set in CONTEXT_FLAGS, then the DEBUG_OUTPUT |
| state, as described in section 5.5, will be enabled by default." |
| |
| 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 GetDebugMessageLog(uint count, |
| sizei bufSize, |
| enum* sources, |
| enum* types, |
| uint* ids, |
| enum* severities, |
| sizei* lengths, |
| char* messageLog); |
| |
| This function fetches a maximum of <count> 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 |
| <sources>, <types>, <severities>, <ids>, and <lengths>, |
| respectively. The application is responsible for allocating enough |
| space for each array to hold up to <count> elements. The string |
| representations of all fetched messages are stored in the |
| <messageLog> array. If multiple messages are fetched, their strings |
| are concatenated into the same <messageLog> array and will be |
| separated by single null terminators. The last string in the array |
| will also be null-terminated. The maximum size of <messageLog>, |
| including the space used by all null terminators, is given by |
| <bufSize>. If <bufSize> is less than zero and <messageLog> is not |
| NULL, an INVALID_VALUE error will be generated. If a message's |
| string, including its null terminator, can not fully fit within the |
| <messageLog> 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 <lengths> include the space |
| for the null terminator of each string. |
| |
| Any or all of the arrays <sources>, <types>, <ids>, <severities>, |
| <lengths> and <messageLog> 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 <count> messages from the message |
| log while ignoring their attributes, the application can call the |
| function with null pointers for all attribute arrays. |
| |
| If the context was created without the CONTEXT_FLAG_DEBUG_BIT in the |
| CONTEXT_FLAGS state, as described in Section 6.1.12, then the GL can opt |
| to never add messages to the message log so GetDebugMessageLog will |
| always return zero. |
| |
| Add new Section 6.1.16 - Debug Label Queries: |
| |
| 6.1.16 - Debug Label Queries |
| |
| The command |
| |
| void GetObjectLabel(enum identifier, uint name, sizei bufSize, |
| sizei *length, char *label); |
| void GetObjectPtrLabel(void* ptr, sizei bufSize, |
| sizei *length, char *label); |
| |
| returns in <label> the string labelling an object. <label> will be |
| null-terminated. The actual number of characters written into <label>, |
| excluding the null terminator, is returned in <length>. If <length> is |
| NULL, no length is returned. The maximum number of characters that may |
| be written into <label>, including the null terminator, is specified by |
| <bufSize>. If no debug label was specified for the object then <label> |
| will contain a null-terminated empty string, and zero will be returned |
| in <length>. If <label> is NULL and <length> is non-NULL then no string |
| will be returned and the length of the label will be returned in |
| <length>. |
| |
| An INVALID_ENUM error is generated by GetObjectLabel if identifier is not |
| one of the object types listed in table 5.1 except SYNC. |
| |
| An INVALID_VALUE error is generated by GetObjectLabel if <name> is not |
| the name of a valid object of the type specified by <identifier>. |
| |
| Additions to the OpenGL / GLX / GLX Protocol Specifications |
| |
| None. |
| |
| Additions to the WGL Specification |
| |
| None. |
| |
| |
| Interactions with OpenGL ES |
| |
| This extension specification uses non-suffixed names for new entry |
| points, types, and tokens. This is correct for implementations against |
| OpenGL. However, when implemented in an OpenGL ES context, all new entry |
| points, types, and tokens are given KHR suffixes. |
| |
| In OpenGL ES versions prior to and including ES 3.1 there is no |
| CONTEXT_FLAGS state and therefore the CONTEXT_FLAG_DEBUG_BIT cannot be |
| queried. GLES contexts must act as if this state existed as described |
| in this specification even if the state itself is not visible to |
| applications. For example, DEBUG_OUTPUT must still be enabled by default |
| if the context was created with debug enabled. |
| |
| Interactions with GLX_ARB_create_context_robustness |
| |
| If the GLX window-system binding API is used to create a context, |
| the GLX_ARB_create_context extension is supported, and the bit |
| GLX_CONTEXT_DEBUG_BIT_ARB is set in GLX_CONTEXT_FLAGS when |
| glXCreateContextAttribsARB is called, the resulting context will |
| have debug enabled, and the CONTEXT_FLAG_DEBUG_BIT bit will be set |
| in CONTEXT_FLAGS as described above in section 6.1.12. |
| |
| Interactions with WGL_ARB_create_context_robustness |
| |
| If the WGL window-system binding API is used to create a context, |
| the WGL_ARB_create_context extension is supported, and the bit |
| WGL_CONTEXT_DEBUG_BIT_ARB is set in WGL_CONTEXT_FLAGS when |
| wglCreateContextAttribsARB is called, the resulting context will |
| have debug enabled, and the CONTEXT_FLAG_DEBUG_BIT bit will be set |
| in CONTEXT_FLAGS as described above in section 6.1.12. |
| |
| Dependencies on GL and ES profiles, versions, and other extensions |
| |
| Dependencies on OpenGL 4.2 Compatibility specification and any other |
| versions or extensions that already provide the GetPointerv entry |
| point as provided by the OpenGL 4.2 Compatibility specification |
| |
| - Remove the modifications to Section 6.1.6 from this |
| specification with the exception that GetPointerv will still |
| accept DEBUG_CALLBACK_FUNCTION and |
| DEBUG_CALLBACK_USER_PARAM as valid values for <pname>, |
| and will return the same values as described in Chapter 6. |
| |
| Dependencies on OpenGL 4.2 Compatibility specification and any other |
| versions that support display lists |
| |
| - DebugMessageControl, DebugMessageInsert, |
| DebugMessageCallback, and GetDebugMessageLog 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: DebugMessageControl, |
| DebugMessageInsert, DebugMessageCallback, and |
| GetDebugMessageLog" |
| |
| Add the same language to corresponding sections of other |
| specifications. |
| |
| Dependencies on program pipeline objects |
| |
| If program pipeline objects are not supported, remove PROGRAM_PIPELINE |
| from table 5.1. |
| |
| Program pipeline objects are supported starting with OpenGL 4.2 and |
| OpenGL ES 3.1. They are also supported if the OpenGL |
| GL_ARB_separate_shader_objects or OpenGL ES |
| GL_EXT_separate_shader_objects extensions are supported. |
| |
| Errors |
| |
| The error INVALID_ENUM will be generated by DebugMessageControl |
| if <source> is not DONT_CARE or one of the debug output sources |
| listed in Table 5.3. |
| |
| The error INVALID_ENUM will be generated by DebugMessageControl |
| if <type> is not DONT_CARE or one of the debug output types listed |
| in Table 5.4. |
| |
| The error INVALID_ENUM will be generated by DebugMessageControl |
| if <severity> is not DONT_CARE or one of the severity levels listed |
| in Table 5.5. |
| |
| The error INVALID_VALUE will be generated by DebugMessageControl |
| if <count> is less than zero. |
| |
| The error INVALID_OPERATION will be generated by |
| DebugMessageControl when <count> is greater than zero and |
| <source> is DONT_CARE. |
| |
| The error INVALID_OPERATION will be generated by |
| DebugMessageControl when <count> is greater than zero and |
| <type> is DONT_CARE. |
| |
| The error INVALID_OPERATION will be generated by |
| DebugMessageControl when <count> is greater than zero and |
| and <severity> is not DONT_CARE. |
| |
| The error INVALID_VALUE will be generated by GetDebugMessageLog |
| if the value of <count> is less than zero. |
| |
| The error INVALID_VALUE will be generated by GetDebugMessageLog |
| if <bufSize> is less than zero. |
| |
| The error INVALID_ENUM will be generated by DebugMessageInsert if |
| the value of <source> is not DEBUG_SOURCE_APPLICATION or |
| DEBUG_SOURCE_THIRD_PARTY. |
| |
| The error INVALID_ENUM will be generated by DebugMessageInsert if |
| the value of <type> is not one of the values from Table 5.4. |
| |
| The error INVALID_ENUM will be generated by DebugMessageInsert if |
| <severity> is not a valid debug severity level listed in Table 5.5. |
| |
| The error INVALID_VALUE will be generated by DebugMessageInsert |
| if the number of characters in <buf>, excluding the null terminator |
| when <length> is negative, is not less than |
| MAX_DEBUG_MESSAGE_LENGTH. |
| |
| The error INVALID_ENUM will be generated by PushDebugGroup |
| if <source> is not DEBUG_SOURCE_APPLICATION or |
| DEBUG_SOURCE_THIRD_PARTY. |
| |
| The error INVALID_VALUE will be generated by PushDebugGroup |
| if <length> is negative and the number of characters in <message>, |
| excluding the null-terminator, is not less than the value of |
| MAX_DEBUG_MESSAGE_LENGTH. |
| |
| The <source> value of PushDebugGroup must be either |
| DEBUG_SOURCE_APPLICATION or DEBUG_SOURCE_THIRD_PARTY, or the |
| error INVALID_ENUM will be generated. |
| |
| Popping a group off the stack with no entry generates the error |
| STACK_UNDERFLOW; pushing a debug group onto a full stack generates |
| the error STACK_OVERFLOW. |
| |
| An INVALID_VALUE error is generated by ObjectLabel and |
| GetObjectLabel if <name> is not the name of a valid object of the type |
| specified by <identifier>. |
| |
| An INVALID_VALUE error is generated by ObjectPtrLabel and |
| GetObjectPtrLabel if <ptr> is not the name of a sync object. |
| |
| An INVALID_VALUE error is generated by ObjectLabel if the number of |
| characters in <label>, excluding the null terminator when <length> is |
| negative, is not less than MAX_LABEL_LENGTH. |
| |
| An INVALID_ENUM error is generated by ObjectLabel and GetObjectLabel if |
| <identifier> is not one of the object namespace tokens in table 5.1. |
| |
| |
| 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 Y GetPointerv NULL The current debug output 5.5.2 - |
| callback function pointer |
| |
| DEBUG_CALLBACK_USER_PARAM Y GetPointerv NULL The current debug output 5.5.2 - |
| callback user parameter |
| |
| DEBUG_LOGGED_MESSAGES Z+ GetIntegerv 0 The number of messages 5.5.3 - |
| currently in the debug |
| message log |
| |
| DEBUG_NEXT_LOGGED_MESSAGE_LENGTH Z+ GetIntegerv 0 The string length of the 5.5.3 - |
| oldest debug message in |
| the debug message log |
| |
| DEBUG_GROUP_STACK_DEPTH Z+ GetIntegerv 1 Debug group stack 5.5.6 - |
| pointer |
| |
| DEBUG_OUTPUT_SYNCHRONOUS B IsEnabled FALSE The enabled state for 5.5.7 - |
| synchronous debug message |
| callbacks |
| |
| DEBUG_OUTPUT B IsEnabled Depends on The enabled state for 5.5 - |
| the context* debug output |
| functionality |
| |
| * Contexts created with the CONTEXT_DEBUG_BIT bit set, as defined in |
| GLX_ARB_create_context and WGL_ARB_create_context control the initial |
| value of this state. If CONTEXT_DEBUG_BIT is set then the initial |
| value of DEBUG_OUTPUT is TRUE otherwise its FALSE. |
| |
| |
| Add the following to Table 6.14 Buffer Object State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.24 Textures (state per texture object): |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.44 Shader Object State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.46 Program Object State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.36 Renderbuffer (state per renderbuffer object): |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.33 Framebuffer (state per framebuffer object): |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.9 Vertex Array Object State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.54 Query Object State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.45 Program Pipeline Object State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.26 Textures (state per sampler object): |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.56 Transform Feedback State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- -------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| |
| Add the following to Table 6.57 Sync (state per sync object): |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- ----------------- ------- ----------- --- |
| - S GetObjectPtrLabel empty Debug label 6.2 |
| |
| [[ Compatibility Profile ]] |
| Add Table 6.60 Display List State: |
| |
| Initial |
| Get Value Type Get Command Value Description Sec |
| --------- ---- ----------------- ------- ----------- --- |
| - S GetObjectLabel empty Debug label 6.2 |
| [[ End Profile-Specific Language ]] |
| |
| |
| 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 Z+ GetIntegerv 1 The maximum length of a 5.5.1 - |
| debug message string, |
| including its null |
| terminator |
| |
| MAX_DEBUG_LOGGED_MESSAGES Z+ GetIntegerv 1 The maximum number of 5.5.3 - |
| messages stored in the |
| debug message log |
| |
| MAX_DEBUG_GROUP_STACK_DEPTH Z+ GetIntegerv 64 Maximum group 5.5.6 - |
| stack depth |
| |
| MAX_LABEL_LENGTH Z+ GetIntegerv 256 Max length of a label 5.5.8 - |
| string |
| |
| |
| Usage Examples |
| |
| Scenario 1: skip a section of the code |
| // Setup of the default active debug group: Filter everything in |
| glDebugMessageControl(GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_TRUE); |
| |
| // Generate a debug marker debug output message |
| glDebugMessageInsert( |
| GL_DEBUG_SOURCE_APPLICATION, |
| GL_DEBUG_TYPE_MARKER, 100, |
| GL_DEBUG_SEVERITY_NOTIFICATION, |
| -1, "Message 1"); |
| |
| // Push debug group 1 |
| glPushDebugGroup( |
| GL_DEBUG_SOURCE_APPLICATION, |
| 1, |
| -1, "Message 2"); |
| |
| // Setup of the debug group 1: Filter everything out |
| glDebugMessageControl(GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_FALSE); |
| |
| // This message won't appear in the debug output log of |
| glDebugMessageInsert( |
| GL_DEBUG_SOURCE_APPLICATION, |
| GL_DEBUG_TYPE_MARKER, 100, |
| GL_DEBUG_SEVERITY_NOTIFICATION, |
| -1, "Message 3"); |
| |
| // Pop debug group 1, restore the volume control of the default debug group. |
| glPopDebugGroup(); |
| |
| // Generate a debug marker debug output message |
| glDebugMessageInsert( |
| GL_DEBUG_SOURCE_APPLICATION, |
| GL_DEBUG_TYPE_MARKER, 100, |
| GL_DEBUG_SEVERITY_NOTIFICATION, |
| -1, "Message 5"); |
| |
| // Expected debug output from the GL implementation |
| // Message 1 |
| // Message 2 |
| // Message 2 |
| // Message 5 |
| |
| Scenario 2: Only output a subsection of the code |
| and disable some messages for the entire application |
| |
| // Setup the control of de debug output for the default debug group |
| glDebugMessageControl( |
| GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_FALSE); |
| glDebugMessageControl( |
| GL_DEBUG_SOURCE_THIRD_PARTY, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_FALSE); |
| std::vector<GLuint> Messages = {1234, 2345, 3456, 4567}; |
| glDebugMessageControl( |
| GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_OTHER, GL_DONT_CARE, |
| GLuint(Messages,size()), &Messages[0], GL_FALSE); |
| glDebugMessageControl( |
| GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_PORTABILITY, GL_DONT_CARE, |
| GLuint(Messages,size()), &Messages[0], GL_FALSE); |
| |
| // Push debug group 1 |
| // Inheritate of the default debug group debug output volume control |
| // Filtered out by glDebugMessageControl |
| glPushDebugGroup( |
| GL_DEBUG_SOURCE_APPLICATION, |
| 1, |
| -1, "Message 1"); |
| |
| // In this section of the code, we are interested in performances. |
| glDebugMessageControl( |
| GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_PERFORMANCE, GL_DONT_CARE, 0, NULL, GL_TRUE); |
| // But we already identify that some messages are not really useful for us. |
| std::vector<GLuint> Messages = {5678, 6789}; |
| glDebugMessageControl( |
| GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_OTHER, GL_DONT_CARE, |
| GLuint(Messages,size()), &Messages[0], GL_FALSE); |
| |
| glDebugMessageInsert( |
| GL_DEBUG_SOURCE_APPLICATION, |
| GL_DEBUG_TYPE_PERFORMANCE, 1357, |
| GL_DEBUG_SEVERITY_MEDIUM, |
| -1, "Message 2"); |
| glDebugMessageInsert( |
| GL_DEBUG_SOURCE_THIRD_PARTY, // We still filter out these messages. |
| GL_DEBUG_TYPE_OTHER, 3579, |
| GL_DEBUG_SEVERITY_MEDIUM, |
| -1, "Message 3"); |
| |
| glPopDebugGroup(); |
| |
| // Expected debug output from the GL implementation |
| // Message 2 |
| |
| |
| Issues |
| |
| (1) Should the extension provides a method for querying markers? |
| |
| RESOLVED: No. |
| |
| |
| (2) Is the concept of <severity> meaningful for most profiling use cases? |
| |
| DISCUSSION: The debug output API was originally designed for debugging |
| but its design has led implementation and application to use |
| it for profiling. Furthermore, markers are not strictly |
| speaking low, medium or high severity messages. |
| |
| RESOLVED: Added DEBUG_SEVERITY_NOTIFICATION |
| |
| |
| (3) How should an implementation behave when the application doesn't push |
| and pop group markers evenly? |
| |
| DISCUSSION: Extra "pop" may be ignored as it is done in OpenGL ES |
| EXT_debug_marker but what to do if the user push too many |
| time? In any case, if a software doesn't push and pop evenly, |
| its design is pretty ill. Hence it is better to notify the |
| application as soon as possible by generating an error. |
| |
| OpenGL legacy handles this problem by limiting the size of the |
| stacks and generating STACK_UNDERFLOW and STACK_OVERFLOW |
| errors. |
| |
| The size of the marker group stack need to be big enough so |
| that the application won't be limited but small enough so that |
| an error is generated soon when pushes and pops are not even. |
| |
| Another option is to let the drivers workaround this issue by |
| ignoring push commands for a full stack and pop commands for |
| an empty stack. In such case, an application doesn't have an |
| immediate feedback for this behavior. |
| |
| RESOLVED: Generates STACK_UNDERFLOW or STACK_UNDERFLOW errors |
| |
| |
| (4) Do we need a maximum length for a marker string? |
| |
| RESOLVED: No, reuse MAX_DEBUG_MESSAGE_LENGTH |
| |
| |
| (5) Can we use this new extension to allow applications to request the |
| info logs from compiling, linking and validating to be automatically |
| submitted to the debug output log and debug output call-back function? |
| |
| DISCUSSION: The API may need a new <type> value DEBUG_TYPE_INFO_LOG |
| for every kind of info logs. glLinkProgram, glCompileShader, |
| glCreateShaderProgram, glValidateProgram and |
| glValidateProgramPipeline, which execution generate the info |
| logs, could also automatically submit this logs the the debug |
| output API. |
| |
| Such strategy can already be apply by querying the info log |
| manually and submitting it to the debug output API with |
| DebugMessageInsert but on some implementations querying the |
| log immediately after the operation may significantly slow |
| down the general compilation of shaders process. |
| |
| The mechanism could be enable with glEnable with a dedicated |
| value (DEBUG_OUTPUT_INFO_LOG). When enable, an option is |
| that shader, program and program pipeline would not have to |
| maintain this log. |
| |
| This perspective emphasis the centralised nature of OpenGL |
| debugging to the debug output API. |
| |
| RESOLVED: Nothing prevent an implementation implementing ARB_debug_output |
| to do it already. |
| |
| |
| (6) Should we use dedicated functions for pushing and popping the group |
| marker stack or use DebugMessageInsert with a dedicated types? |
| |
| DISCUSSION: These functions have side effects (causing underflow errors, |
| causing other messages to become disabled) rather than purely |
| injecting messages into the debug log. |
| |
| RESOLVED: Use separated functions. |
| |
| |
| (7) Should we generate an error when we pop the last entry or when the |
| stack is empty? |
| |
| DISCUSSION: For the deprecated stacks, at the beginning of the program the |
| stack depth was 1 which implies a default debug group (id 0?) |
| in the present case. |
| |
| RESOLVED: Let's follow the deprecated stacks precedent. |
| |
| |
| (8) Should we be able to query the current debug group? |
| |
| DISCUSSION: ARB_debug_output doesn't provide a query API for debug output |
| control states, should we follow this precedent or are there |
| use cases where is could be especially useful? |
| |
| RESOLVED: No, it doesn't seem very useful. |
| |
| |
| (9) Should we provide within which debug group a message is generated? |
| |
| DISCUSSION: Such information might be useful but we would need to add a |
| parameter to the callback function. Also, the application can |
| take the responsibility of saving the current active debug |
| group. Such option avoid API disruption. |
| |
| RESOLVED: (8) could resolve this issue as well if this is actually at |
| desired feature. Also nothing prevents an implementation to use |
| a debug group id to form the debug output message. Finally an |
| application can always store the current debug group each time |
| a DEBUG_TYPE_PUSH_GROUP is generated. |
| |
| |
| (10) Do we need a dedicated mechanism to enable and disable debug outputs? |
| |
| DISCUSSION: It could seem that using glDebugMessageControl could allow |
| to disable debug output. However with the introduction of |
| debug groups, glDebugMessageControl only disable the active |
| debug group and it could be pretty complex for an application |
| to ensure that each debug group is disable. A easier idea |
| would be to be global switch glEnable(GL_DEBUG_OUTPUT) |
| allowing the application to completely switch on and off the |
| entire debug output mechanism. |
| |
| RESOLVED: Issue covered by ARB_debug_output2 |
| |
| |
| (11) Should there be a way to enable and disable the debug output |
| functionality via glEnable(GL_DEBUG_OUTPUT) in addition to the way |
| the context is created? This may be useful for third-party or |
| pre-existing code that doesn't have control over how the context is |
| created. This could be exposed in addition to the context creation |
| flag, and the context creation flag just sets the default state of |
| the enable. |
| |
| RESOLVED: Yes, based on various feedback this would be useful. Added |
| to revision 3 of this extension spec. |
| |
| |
| (12) Should we use a single function to set the label for all objects? |
| |
| DISCUSSION: This is the approach chosen in OpenGL ES extension |
| EXT_debug_label. It builds up a new strong precedent |
| for an important functionality but not exactly one |
| which purpose is to build a strong design precedent. |
| |
| On one hand using a unique function for all objects |
| reduce the number of new entry point from 24 to 2. |
| |
| RESOLVED: For the purpose of convergence with ES, the groups have |
| voted for only 2 functions. |
| |
| |
| (13) Do we need a maximum length (MAX_LABEL_LENGTH) for the label? |
| |
| DISCUSSION: Following the precedents given by others strings in |
| OpenGL, this seems useful. On one hand ARB_debug_output |
| has a maximum size of the debug message |
| (MAX_DEBUG_MESSAGE_LENGTH), shader variable names have |
| a maximum length but on other hand the shader source |
| and the program info log doesn't have such limitation. |
| However, it seems hard to imagine that implementations |
| doesn't have limitation somehow. |
| |
| RESOLVED: Yes |
| |
| |
| (14) Should we provide a function to label a display list? |
| |
| RESOLVED: Yes for compatibility profile only. |
| |
| |
| (15) Should the ES version of this extension supports the message log |
| or only the callback function? |
| |
| DISCUSSION: When promoting AMD_debug_output to ARB_debug_output, the ARB |
| has added a message log that can be query by the application |
| if no callback function has been specified by the application. |
| The purpose of this addition was to support remote rendering. |
| Is remote rendering supported by OpenGL ES? The ES group |
| typically wants to have only one way to do things, should we |
| only support the callback function for ES debug output? |
| |
| RESOLVED: The ES group has chosen to keep it by vote |
| |
| |
| (16) Why do OpenGL implementations use KHR suffixes, while OpenGL |
| implementations use no suffix? |
| |
| DISCUSSION: this functionality was initially defined by OpenGL 4.3, and |
| set of "backwards compatibility" extensions were defined to allow |
| implementing it against earlier GL versions. OpenGL ARB policy in the |
| case of backwards compatibility extensions is that extension suffixes |
| should not be added. The OpenGL ES Working Group then decided to support |
| the same functionality as an OpenGL ES extension, and both groups agreed |
| to share a single KHR specification for the extension. However, OpenGL |
| ES policy requires extension suffixes on Khronos-approved OES and KHR |
| extensions. |
| |
| We are aware of this inconsistency, but both working groups have chosen |
| to stand by their own naming policies and the inconsistency is unlikely |
| to be resolved. |
| |
| Revision History |
| |
| Revision 17, 2015/07/02 (Jan-Harald Fredriksen) |
| - Clarify CONTEXT_FLAGS state for ES3.1 and earlier in the Interactions |
| section (Bug 13104). |
| |
| Revision 16, 2015/03/11 (Jon Leech) |
| - Clarify dependencies required to support PROGRAM_PIPELINE (Bug |
| 13545). |
| |
| Revision 15, 2014/03/04 (Jon Leech) |
| - Minor changes to clean up expected message output format in example |
| code and refer to the value of state named by tokens, rather than |
| the token values themselves (Bug 10083). |
| |
| Revision 14, 2013/11/05 (Jon Leech) |
| - Edit state tables to replace the "Get Value" of LABEL with "-", |
| indicating unnamed state. There is no token LABEL in the extension, |
| and the GetObject*Label commands do not take <pname> parameters (Bug |
| 11131). |
| |
| Revision 13, 2013/06/24 (Jon Leech) |
| - Add 'const' attribute to <userParam> for DebugMessageCallback and |
| the corresponding GLDEBUGPROC type. Specify that unrecognized |
| message IDs are ignored in the DebugMessageControl <ids> array. |
| Specify that GetDebugMessageLog <messageLog> parameter must be |
| NULL when <bufSize> is less than zero, to allow an early out. |
| Replace spurious GLvoid with void. (Bug 10083). |
| |
| Revision 12, 2013/06/15 (Jon Leech) |
| - Clarify in the New Tokens section that the <source> parameter of |
| some commands may not allow all possible values shown in this |
| section (public Bug 889). |
| |
| Revision 11, 2013/04/26 (Jon Leech) |
| - Implement OpenGL ES policy of adding KHR suffixes to all KHR |
| extensions. Add notes, OpenGL ES Interaction section, and issue 16 |
| explaining the situation (Bug 9716). |
| |
| Revision 10, 2013/04/16 (Jon Leech) |
| - Fix type of <ids> parameter in GetDebugMessageLog body (Bug 10083) |
| |
| Revision 9, 2012/09/18 (pbrown) |
| - Add a "void" function argument list for PopDebugGroup(). The GLEW |
| library needs this to properly parse the extension spec file. |
| |
| Revision 8, 2012/09/16 (Jon Leech) |
| - Add existing tokens allowed for ObjectLabel identifiers to "New |
| Tokens" section, without enum values since they aren't actually new |
| (Bug 9506). |
| |
| Revision 7, 2012/09/12 (Jon Leech) |
| - Clarify description of DebugMessageControl parameters to avoid |
| triple negatives (Bug 9392). |
| |
| Revision 6, 2012/07/31 (criccio) |
| - ObjectLabel generates an INVALID_VALUE error if <name> |
| doesn't identify a valid object. |
| |
| Revision 5, 2012/06/22 (criccio) |
| - Resolved issue 15 |
| |
| Revision 4, 2012/06/19 (Jon Leech) |
| - Change logSize parameter to bufSize |
| |
| Revision 3, 2012/06/12 (criccio) |
| - Added ObjectPtrLabel and GetObjectPtrLabel (bug 9140) |
| |
| Revision 2, 2012/06/07 (criccio) |
| - Updated overview for higher consistence of the language. |
| - Clarified when the message is generated by the GL when popping |
| a debug group. |
| |
| Revision 1, 2012/06/04 (criccio) |
| - First draft, merged GL_ARB_debug_output, GL_ARB_debug_output2, |
| GL_ARB_debug_group and GL_ARB_debug_label. |
| |