Package org.lwjgl.opengl

Class ARBDebugOutput


  • public class ARBDebugOutput
extends java.lang.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 Detail

      • 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.

    • Method Detail

      • glDebugMessageCallbackARB

        public static void glDebugMessageCallbackARB(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

      • glGetDebugMessageLogARB

        public static int glGetDebugMessageLogARB(int count,
                                          java.nio.IntBuffer sources,
                                          java.nio.IntBuffer types,
                                          java.nio.IntBuffer ids,
                                          java.nio.IntBuffer severities,
                                          java.nio.IntBuffer lengths,
                                          java.nio.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,
                                            int[] ids,
                                            boolean enabled)
        Array version of: DebugMessageControlARB

      • glGetDebugMessageLogARB

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