xref: /third_party/openGLES/extensions/ARB/ARB_debug_output.txt (revision 5bd8dead)

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 <target> parameters of Enable, Disable,
    and IsEnabled:
    
        DEBUG_OUTPUT_SYNCHRONOUS_ARB                      0x8242

    Tokens accepted by the <value> 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 <pname> parameter of GetPointerv:
        
        DEBUG_CALLBACK_FUNCTION_ARB                       0x8244
        DEBUG_CALLBACK_USER_PARAM_ARB                     0x8245

    Tokens accepted or provided by the <source> parameters of
    DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB,
    and the <sources> 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 <type> parameters of
    DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB,
    and the <types> 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 <severity> parameters of
    DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB
    callback functions, and the <severities> 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 <callback> 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
    <callback> clears the current callback and disables message output
    through callbacks.  Applications can provide user-specified data
    through the pointer <userParam>.  The context will store this
    pointer and will include it as one of the parameters in each call to
    the callback function.
    
    If the application has specified a callback function for receiving
    debug output, the implementation will call that function whenever
    any enabled message is generated.  The source, type, ID, and
    severity of the message are specified by the DEBUGPROCARB parameters
    <source>, <type>, <id>, and <severity>, respectively.  The string
    representation of the message is stored in <message> and its length
    (excluding the null-terminator) is stored in <length>.  The
    parameter <userParam> is the user-specified parameter that was given
    when calling DebugMessageCallbackARB.
    
    Applications can query the current callback function and
    the current user-specified parameter by obtaining the values of
    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 <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.
        
    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 <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> is not DONT_CARE, then all messages whose source
          does not match <source> will not be referenced.
          
        - If <type> is not DONT_CARE, then all messages whose type does
          not match <type> will not be referenced.
          
        - If <severity> is not DONT_CARE, then all messages whose
          severity level does not match <severity> will not 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.  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.
    
    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 <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_ARB or
    DEBUG_SOURCE_THIRD_PARTY_ARB, 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
    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 <userParam> 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 <pname> in the array <params>.
    The possible values for <pname> 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 <pname> 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 <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, the error INVALID_VALUE
    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
    <messageLog> is NULL, the value of <bufSize> 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 <pname>,
          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 <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 DebugMessageControlARB
    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 DebugMessageControlARB
    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 DebugMessageControlARB
    if <count> is less than zero.

    The error INVALID_OPERATION will be generated by
    DebugMessageControlARB when <count> is greater than zero and
    <source> is DONT_CARE.

    The error INVALID_OPERATION will be generated by
    DebugMessageControlARB when <count> is greater than zero and
    <type> is DONT_CARE.

    The error INVALID_OPERATION will be generated by
    DebugMessageControlARB when <count> is greater than zero and
    and <severity> is not DONT_CARE.
 
    The error INVALID_VALUE will be generated by GetDebugMessageLogARB
    if the value of <count> is less than zero.

    The error INVALID_VALUE will be generated by GetDebugMessageLogARB
    if <bufSize> is less than zero.
    
    The error INVALID_ENUM will be generated by DebugMessageInsertARB if
    the value of <source> 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 <type> is not one of the values from Table 5.4.

    The error INVALID_ENUM will be generated by DebugMessageInsertARB if
    <severity> 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 <buf>, excluding the null terminator
    when <length> 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 <ids> 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 <type> 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 <length> 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.