Class ARBDebugOutput

java.lang.Object
org.lwjgl.opengl.ARBDebugOutput

public class ARBDebugOutput extends Object
Native bindings to the ARB_debug_output extension.

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_ARB_create_context or GLX_ARB_create_context. This extension places no limits on any other functionality provided by debug contexts through other extensions.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Tokens accepted by the pname parameter of GetPointerv.
    static final int
    Tokens accepted by the pname parameter of GetPointerv.
    static final int
    Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
    static final int
    Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
    static final int
    Tokens accepted by the target parameters of Enable, Disable, and IsEnabled.
    static final int
    Tokens accepted or provided by the severity parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the severities parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the severity parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the severities parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the severity parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the severities parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
    static final int
    Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
    static final int
    Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    Specifies a callback function for receiving debug messages.
    static void
    glDebugMessageControlARB(int source, int type, int severity, int[] ids, boolean enabled)
    Array version of: DebugMessageControlARB
    static void
    glDebugMessageControlARB(int source, int type, int severity, int id, boolean enabled)
    Controls the volume of debug output by disabling specific or groups of messages.
    static void
    glDebugMessageControlARB(int source, int type, int severity, IntBuffer ids, boolean enabled)
    Controls the volume of debug output by disabling specific or groups of messages.
    static void
    glDebugMessageInsertARB(int source, int type, int id, int severity, CharSequence buf)
    This function can be called by applications and third-party libraries to generate their own messages, such as ones containing timestamp information or signals about specific render system events.
    static void
    glDebugMessageInsertARB(int source, int type, int id, int severity, ByteBuffer buf)
    This function can be called by applications and third-party libraries to generate their own messages, such as ones containing timestamp information or signals about specific render system events.
    static int
    glGetDebugMessageLogARB(int count, int[] sources, int[] types, int[] ids, int[] severities, int[] lengths, ByteBuffer messageLog)
    Array version of: GetDebugMessageLogARB
    static int
    glGetDebugMessageLogARB(int count, IntBuffer sources, IntBuffer types, IntBuffer ids, IntBuffer severities, IntBuffer lengths, ByteBuffer messageLog)
    When no debug callback is set, debug messages are stored in a debug message log.
    static void
    nglDebugMessageCallbackARB(long callback, long userParam)
    Unsafe version of: DebugMessageCallbackARB
    static void
    nglDebugMessageControlARB(int source, int type, int severity, int count, long ids, boolean enabled)
    Unsafe version of: DebugMessageControlARB
    static void
    nglDebugMessageInsertARB(int source, int type, int id, int severity, int length, long buf)
    Unsafe version of: DebugMessageInsertARB
    static int
    nglGetDebugMessageLogARB(int count, int bufSize, long sources, long types, long ids, long severities, long lengths, long messageLog)
    Unsafe version of: GetDebugMessageLogARB

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB

      public static final int GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB
      Tokens accepted by the target parameters of Enable, Disable, and IsEnabled.

      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.

      See Also:
    • GL_MAX_DEBUG_MESSAGE_LENGTH_ARB

      public static final int GL_MAX_DEBUG_MESSAGE_LENGTH_ARB
      Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_DEBUG_LOGGED_MESSAGES_ARB

      public static final int GL_MAX_DEBUG_LOGGED_MESSAGES_ARB
      Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_DEBUG_LOGGED_MESSAGES_ARB

      public static final int GL_DEBUG_LOGGED_MESSAGES_ARB
      Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB

      public static final int GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB
      Tokens accepted by the value parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_DEBUG_CALLBACK_FUNCTION_ARB

      public static final int GL_DEBUG_CALLBACK_FUNCTION_ARB
      Tokens accepted by the pname parameter of GetPointerv.
      See Also:
    • GL_DEBUG_CALLBACK_USER_PARAM_ARB

      public static final int GL_DEBUG_CALLBACK_USER_PARAM_ARB
      Tokens accepted by the pname parameter of GetPointerv.
      See Also:
    • GL_DEBUG_SOURCE_API_ARB

      public static final int GL_DEBUG_SOURCE_API_ARB
      Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SOURCE_WINDOW_SYSTEM_ARB

      public static final int GL_DEBUG_SOURCE_WINDOW_SYSTEM_ARB
      Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SOURCE_SHADER_COMPILER_ARB

      public static final int GL_DEBUG_SOURCE_SHADER_COMPILER_ARB
      Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SOURCE_THIRD_PARTY_ARB

      public static final int GL_DEBUG_SOURCE_THIRD_PARTY_ARB
      Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SOURCE_APPLICATION_ARB

      public static final int GL_DEBUG_SOURCE_APPLICATION_ARB
      Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SOURCE_OTHER_ARB

      public static final int GL_DEBUG_SOURCE_OTHER_ARB
      Tokens accepted or provided by the source parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the sources parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_TYPE_ERROR_ARB

      public static final int GL_DEBUG_TYPE_ERROR_ARB
      Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB

      public static final int GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB
      Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARB

      public static final int GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARB
      Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_TYPE_PORTABILITY_ARB

      public static final int GL_DEBUG_TYPE_PORTABILITY_ARB
      Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_TYPE_PERFORMANCE_ARB

      public static final int GL_DEBUG_TYPE_PERFORMANCE_ARB
      Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_TYPE_OTHER_ARB

      public static final int GL_DEBUG_TYPE_OTHER_ARB
      Tokens accepted or provided by the type parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, and the types parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SEVERITY_HIGH_ARB

      public static final int GL_DEBUG_SEVERITY_HIGH_ARB
      Tokens accepted or provided by the severity parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the severities parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SEVERITY_MEDIUM_ARB

      public static final int GL_DEBUG_SEVERITY_MEDIUM_ARB
      Tokens accepted or provided by the severity parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the severities parameter of GetDebugMessageLogARB.
      See Also:
    • GL_DEBUG_SEVERITY_LOW_ARB

      public static final int GL_DEBUG_SEVERITY_LOW_ARB
      Tokens accepted or provided by the severity parameters of DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB callback functions, and the severities parameter of GetDebugMessageLogARB.
      See Also:
  • Method Details

    • nglDebugMessageControlARB

      public static void nglDebugMessageControlARB(int source, int type, int severity, int count, long ids, boolean enabled)
      Unsafe version of: DebugMessageControlARB
      Parameters:
      count - the number of message IDs in ids
    • glDebugMessageControlARB

      public static void glDebugMessageControlARB(int source, int type, int severity, @Nullable IntBuffer ids, boolean enabled)
      Controls the volume of debug output by disabling specific or groups of messages.

      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.

      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.

      Parameters:
      source - the message source. One of:
      DEBUG_SOURCE_API_ARBDEBUG_SOURCE_WINDOW_SYSTEM_ARB
      DEBUG_SOURCE_SHADER_COMPILER_ARBDEBUG_SOURCE_THIRD_PARTY_ARB
      DEBUG_SOURCE_APPLICATION_ARBDEBUG_SOURCE_OTHER_ARB
      type - the message type. One of:
      DEBUG_TYPE_ERROR_ARBDEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB
      DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARBDEBUG_TYPE_PORTABILITY_ARB
      DEBUG_TYPE_PERFORMANCE_ARBDEBUG_TYPE_OTHER_ARB
      severity - the message severity level. One of:
      DEBUG_SEVERITY_HIGH_ARBDEBUG_SEVERITY_MEDIUM_ARBDEBUG_SEVERITY_LOW_ARB
      ids - the message IDs to enable or disable
      enabled - whether to enable or disable the references subset of messages
    • glDebugMessageControlARB

      public static void glDebugMessageControlARB(int source, int type, int severity, int id, boolean enabled)
      Controls the volume of debug output by disabling specific or groups of messages.

      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.

      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.

      Parameters:
      source - the message source. One of:
      DEBUG_SOURCE_API_ARBDEBUG_SOURCE_WINDOW_SYSTEM_ARB
      DEBUG_SOURCE_SHADER_COMPILER_ARBDEBUG_SOURCE_THIRD_PARTY_ARB
      DEBUG_SOURCE_APPLICATION_ARBDEBUG_SOURCE_OTHER_ARB
      type - the message type. One of:
      DEBUG_TYPE_ERROR_ARBDEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB
      DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARBDEBUG_TYPE_PORTABILITY_ARB
      DEBUG_TYPE_PERFORMANCE_ARBDEBUG_TYPE_OTHER_ARB
      severity - the message severity level. One of:
      DEBUG_SEVERITY_HIGH_ARBDEBUG_SEVERITY_MEDIUM_ARBDEBUG_SEVERITY_LOW_ARB
      enabled - whether to enable or disable the references subset of messages
    • nglDebugMessageInsertARB

      public static void nglDebugMessageInsertARB(int source, int type, int id, int severity, int length, long buf)
      Unsafe version of: DebugMessageInsertARB
      Parameters:
      length - the number of characters in buf. If negative, it is implied that buf contains a null terminated string.
    • glDebugMessageInsertARB

      public static void glDebugMessageInsertARB(int source, int type, int id, int severity, ByteBuffer buf)
      This function can be called by applications and third-party libraries to generate their own messages, such as ones containing timestamp information or signals about specific render system events.

      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.

      Parameters:
      source - the message source. One of:
      DEBUG_SOURCE_THIRD_PARTY_ARBDEBUG_SOURCE_APPLICATION_ARB
      type - the message type. One of:
      DEBUG_TYPE_ERROR_ARBDEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB
      DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARBDEBUG_TYPE_PORTABILITY_ARB
      DEBUG_TYPE_PERFORMANCE_ARBDEBUG_TYPE_OTHER_ARB
      id - the message ID
      severity - the message severity level. One of:
      DEBUG_SEVERITY_HIGH_ARBDEBUG_SEVERITY_MEDIUM_ARBDEBUG_SEVERITY_LOW_ARB
      buf - the string representation of the message
    • glDebugMessageInsertARB

      public static void glDebugMessageInsertARB(int source, int type, int id, int severity, CharSequence buf)
      This function can be called by applications and third-party libraries to generate their own messages, such as ones containing timestamp information or signals about specific render system events.

      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.

      Parameters:
      source - the message source. One of:
      DEBUG_SOURCE_THIRD_PARTY_ARBDEBUG_SOURCE_APPLICATION_ARB
      type - the message type. One of:
      DEBUG_TYPE_ERROR_ARBDEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB
      DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARBDEBUG_TYPE_PORTABILITY_ARB
      DEBUG_TYPE_PERFORMANCE_ARBDEBUG_TYPE_OTHER_ARB
      id - the message ID
      severity - the message severity level. One of:
      DEBUG_SEVERITY_HIGH_ARBDEBUG_SEVERITY_MEDIUM_ARBDEBUG_SEVERITY_LOW_ARB
      buf - the string representation of the message
    • nglDebugMessageCallbackARB

      public static void nglDebugMessageCallbackARB(long callback, long userParam)
      Unsafe version of: DebugMessageCallbackARB
    • glDebugMessageCallbackARB

      public static void glDebugMessageCallbackARB(@Nullable GLDebugMessageARBCallbackI callback, long userParam)
      Specifies a callback function for receiving debug messages.

      This function's prototype must follow the type definition of DEBUGPROCARB including its platform-dependent calling convention. Anything else will result in undefined behavior. Only one debug callback can be specified for the current context, and further calls overwrite the previous callback. Specifying NULL as the value of callback clears the current callback and disables message output through callbacks. Applications can provide user-specified data through the pointer userParam. The context will store this pointer and will include it as one of the parameters in each call to the callback function.

      If the application has specified a callback function for receiving debug output, the implementation will call that function whenever any enabled message is generated. The source, type, ID, and severity of the message are specified by the DEBUGPROCARB parameters source, type, id, and severity, respectively. The string representation of the message is stored in message and its length (excluding the null-terminator) is stored in length. The parameter userParam is the user-specified parameter that was given when calling DebugMessageCallbackARB.

      Applications can query the current callback function and the current user-specified parameter by obtaining the values of 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.

      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.

      Parameters:
      callback - a callback function that will be called when a debug message is generated
      userParam - a user supplied pointer that will be passed on each invocation of callback
    • nglGetDebugMessageLogARB

      public static int nglGetDebugMessageLogARB(int count, int bufSize, long sources, long types, long ids, long severities, long lengths, long messageLog)
      Unsafe version of: GetDebugMessageLogARB
      Parameters:
      bufSize - the maximum number of characters that can be written in the messageLog array
    • glGetDebugMessageLogARB

      public static int glGetDebugMessageLogARB(int count, @Nullable IntBuffer sources, @Nullable IntBuffer types, @Nullable IntBuffer ids, @Nullable IntBuffer severities, @Nullable IntBuffer lengths, @Nullable ByteBuffer messageLog)
      When no debug callback is set, debug messages are stored in a debug message log. Messages can be queried from the log by calling this function.

      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.

      Parameters:
      count - the number of debug messages to retrieve from the log
      sources - a buffer in which to place the returned message sources
      types - a buffer in which to place the returned message typesd
      ids - a buffer in which to place the returned message IDs
      severities - a buffer in which to place the returned message severity levels
      lengths - a buffer in which to place the returned message lengths
      messageLog - a buffer in which to place the returned messages
    • glDebugMessageControlARB

      public static void glDebugMessageControlARB(int source, int type, int severity, @Nullable int[] ids, boolean enabled)
      Array version of: DebugMessageControlARB
    • glGetDebugMessageLogARB

      public static int glGetDebugMessageLogARB(int count, @Nullable int[] sources, @Nullable int[] types, @Nullable int[] ids, @Nullable int[] severities, @Nullable int[] lengths, @Nullable ByteBuffer messageLog)
      Array version of: GetDebugMessageLogARB