Package org.lwjgl.opengl

Class AMDDebugOutput

java.lang.Object

org.lwjgl.opengl.AMDDebugOutput

public class AMDDebugOutput
extends java.lang.Object

Native bindings to the AMD_debug_output extension.

This extension allows the GL to notify applications when various debug events occur in contexts that have been created with the debug flag, as provided by WGL_ARB_create_context and GLX_ARB_create_context.

These events are represented in the form of enumerable messages with an included human-readable translation. Examples of debug events include incorrect use of the GL, warnings of undefined behavior, and performance warnings.

A message is uniquely identified by a category and an implementation-dependent ID within that category. Message categories are general and are used to organize large groups of similar messages together. Examples of categories include GL errors, performance warnings, and deprecated functionality warnings. Each message is also assigned a severity level that denotes roughly how "important" that message is in comparison to other messages across all categories. For example, notification of a GL error would have a higher severity than a performance warning due to redundant state changes.

Messages are communicated to the application through an application-defined callback function that is called by the GL implementation on each debug message. The motivation for the callback routine is to free application developers from actively having to query whether any GL error or other debuggable event has happened after each call to a GL function. With a callback, developers can keep their code free of debug checks, and only have to react to messages as they occur. In order to support indirect rendering, a message log is also provided that stores copies of recent messages until they are actively queried.

To control the volume of debug output, messages can be disabled either individually by ID, or entire groups of messages can be turned off based on category or severity.

The only requirement on the minimum quantity and type of messages that implementations of this extension must support is that a message must be sent notifying the application whenever any GL error occurs. Any further messages are left to the implementation. Implementations do not have to output messages from all categories listed by this extension in order to support this extension, and new categories can be added by other extensions.

This extension places no restrictions or requirements on any additional functionality provided by the debug context flag through other extensions.

Requires WGL_ARB_create_context or GLX_ARB_create_context.

Field Summary

Fields

Modifier and Type	Field and Description
static int	GL_DEBUG_CATEGORY_API_ERROR_AMD GL_DEBUG_CATEGORY_APPLICATION_AMD GL_DEBUG_CATEGORY_DEPRECATION_AMD GL_DEBUG_CATEGORY_OTHER_AMD GL_DEBUG_CATEGORY_PERFORMANCE_AMD GL_DEBUG_CATEGORY_SHADER_COMPILER_AMD GL_DEBUG_CATEGORY_UNDEFINED_BEHAVIOR_AMD GL_DEBUG_CATEGORY_WINDOW_SYSTEM_AMD Tokens accepted by DebugMessageEnableAMD, GetDebugMessageLogAMD, and DEBUGPROCAMD callback function for category.
static int	GL_DEBUG_LOGGED_MESSAGES_AMD Tokens accepted by GetIntegerv.
static int	GL_DEBUG_SEVERITY_HIGH_AMD GL_DEBUG_SEVERITY_LOW_AMD GL_DEBUG_SEVERITY_MEDIUM_AMD Tokens accepted by DebugMessageEnableAMD, GetDebugMessageLogAMD, DebugMessageInsertAMD, and DEBUGPROCAMD callback function for severity.
static int	GL_MAX_DEBUG_LOGGED_MESSAGES_AMD GL_MAX_DEBUG_MESSAGE_LENGTH_AMD Tokens accepted by GetIntegerv.

Method Summary

Modifier and Type	Method and Description
static void	glDebugMessageCallbackAMD(GLDebugMessageAMDCallbackI callback, long userParam) Specifies a callback to receive debugging messages from the GL.
static void	glDebugMessageEnableAMD(int category, int severity, int[] ids, boolean enabled) Array version of: DebugMessageEnableAMD
static void	glDebugMessageEnableAMD(int category, int severity, int id, boolean enabled) Allows disabling or enabling generation of subsets of messages.
static void	glDebugMessageEnableAMD(int category, int severity, java.nio.IntBuffer ids, boolean enabled) Allows disabling or enabling generation of subsets of messages.
static void	glDebugMessageInsertAMD(int category, int severity, int id, java.nio.ByteBuffer buf) Injects an application-supplied message into the debug message stream.
static void	glDebugMessageInsertAMD(int category, int severity, int id, java.lang.CharSequence buf) Injects an application-supplied message into the debug message stream.
static int	glGetDebugMessageLogAMD(int count, int[] categories, int[] severities, int[] ids, int[] lengths, java.nio.ByteBuffer messageLog) Array version of: GetDebugMessageLogAMD
static int	glGetDebugMessageLogAMD(int count, java.nio.IntBuffer categories, java.nio.IntBuffer severities, java.nio.IntBuffer ids, java.nio.IntBuffer lengths, java.nio.ByteBuffer messageLog) Retrieves messages from the debug message log.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GL_MAX_DEBUG_MESSAGE_LENGTH_AMD, GL_MAX_DEBUG_LOGGED_MESSAGES_AMD, GL_DEBUG_LOGGED_MESSAGES_AMD

Tokens accepted by GetIntegerv.

GL_DEBUG_SEVERITY_HIGH_AMD, GL_DEBUG_SEVERITY_MEDIUM_AMD, GL_DEBUG_SEVERITY_LOW_AMD

Tokens accepted by DebugMessageEnableAMD, GetDebugMessageLogAMD, DebugMessageInsertAMD, and DEBUGPROCAMD callback function for severity.

GL_DEBUG_CATEGORY_API_ERROR_AMD, GL_DEBUG_CATEGORY_WINDOW_SYSTEM_AMD, GL_DEBUG_CATEGORY_DEPRECATION_AMD, GL_DEBUG_CATEGORY_UNDEFINED_BEHAVIOR_AMD, GL_DEBUG_CATEGORY_PERFORMANCE_AMD, GL_DEBUG_CATEGORY_SHADER_COMPILER_AMD, GL_DEBUG_CATEGORY_APPLICATION_AMD, GL_DEBUG_CATEGORY_OTHER_AMD

Tokens accepted by DebugMessageEnableAMD, GetDebugMessageLogAMD, and DEBUGPROCAMD callback function for category.

Method Detail

glDebugMessageEnableAMD

public static void glDebugMessageEnableAMD(int category,
                                           int severity,
                                           java.nio.IntBuffer ids,
                                           boolean enabled)

Allows disabling or enabling generation of subsets of messages. If enabled is TRUE, the referenced subset of messages is enabled. If FALSE, then those messages are disabled. This command can reference different subsets of messages by varying its parameter values in the following ways:

1. To reference all messages, let category, severity, and count all be zero. The value of ids is ignored in this case.
2. To reference all messages across all categories with a specific severity level, let category and count be zero and let severity identify the severity level. The value of ids is ignored in this case.
3. To reference all messages within a single category, let category identify the referenced category and let severity and count be zero. The value of ids is ignored in this case.
4. To reference all messages within a single category and at a specific severity level, let category identify the category and severity identify the severity level, and let count be zero. The value of ids is ignored in this case.
5. To reference specific messages by ID within a single category, let category identify the category, let severity be zero, let count be greater than zero and let ids identify the IDs of count messages within the identified category. Operations on message IDs that are not valid within the category are silently ignored.

In all of the above cases, if category is non-zero and specifies an invalid category, the error INVALID_ENUM is generated. Similarly if severity is non-zero and is an invalid severity level, the error INVALID_ENUM is generated. If count is less than zero, the error INVALID_VALUE is generated. If the parameters do not fall into one of the cases defined above, the error INVALID_VALUE is generated. The error INVALID_OPERATION is generated if this command is called in a non-debug context.

Although messages are grouped into categories and severities, and entire groups of messages can be turned off with a single call, there is no explicit per-category or per-severity enabled state. Instead the enabled state is stored individually for each message. There is no difference between disabling a category of messages with a single call, and enumerating all messages of that category and individually disabling each of them by their ID.

All messages of severity level DEBUG_SEVERITY_MEDIUM_AMD and DEBUG_SEVERITY_HIGH_AMD in all categories are initially enabled, and all messages at DEBUG_SEVERITY_LOW_AMD are initially disabled.

Parameters:

category - the message category. One of:

DEBUG_CATEGORY_API_ERROR_AMD	DEBUG_CATEGORY_WINDOW_SYSTEM_AMD
DEBUG_CATEGORY_DEPRECATION_AMD	DEBUG_CATEGORY_UNDEFINED_BEHAVIOR_AMD
DEBUG_CATEGORY_PERFORMANCE_AMD	DEBUG_CATEGORY_SHADER_COMPILER_AMD
DEBUG_CATEGORY_APPLICATION_AMD	DEBUG_CATEGORY_OTHER_AMD

severity - the message severity. One of:

DEBUG_SEVERITY_HIGH_AMD

DEBUG_SEVERITY_MEDIUM_AMD

DEBUG_SEVERITY_LOW_AMD

ids - an array of message ids

enabled - whether to enable or disable the referenced subset of messages

glDebugMessageEnableAMD

public static void glDebugMessageEnableAMD(int category,
                                           int severity,
                                           int id,
                                           boolean enabled)

Allows disabling or enabling generation of subsets of messages. If enabled is TRUE, the referenced subset of messages is enabled. If FALSE, then those messages are disabled. This command can reference different subsets of messages by varying its parameter values in the following ways:

1. To reference all messages, let category, severity, and count all be zero. The value of ids is ignored in this case.
2. To reference all messages across all categories with a specific severity level, let category and count be zero and let severity identify the severity level. The value of ids is ignored in this case.
3. To reference all messages within a single category, let category identify the referenced category and let severity and count be zero. The value of ids is ignored in this case.
4. To reference all messages within a single category and at a specific severity level, let category identify the category and severity identify the severity level, and let count be zero. The value of ids is ignored in this case.
5. To reference specific messages by ID within a single category, let category identify the category, let severity be zero, let count be greater than zero and let ids identify the IDs of count messages within the identified category. Operations on message IDs that are not valid within the category are silently ignored.

In all of the above cases, if category is non-zero and specifies an invalid category, the error INVALID_ENUM is generated. Similarly if severity is non-zero and is an invalid severity level, the error INVALID_ENUM is generated. If count is less than zero, the error INVALID_VALUE is generated. If the parameters do not fall into one of the cases defined above, the error INVALID_VALUE is generated. The error INVALID_OPERATION is generated if this command is called in a non-debug context.

Although messages are grouped into categories and severities, and entire groups of messages can be turned off with a single call, there is no explicit per-category or per-severity enabled state. Instead the enabled state is stored individually for each message. There is no difference between disabling a category of messages with a single call, and enumerating all messages of that category and individually disabling each of them by their ID.

All messages of severity level DEBUG_SEVERITY_MEDIUM_AMD and DEBUG_SEVERITY_HIGH_AMD in all categories are initially enabled, and all messages at DEBUG_SEVERITY_LOW_AMD are initially disabled.

Parameters:

category - the message category. One of:

DEBUG_CATEGORY_API_ERROR_AMD	DEBUG_CATEGORY_WINDOW_SYSTEM_AMD
DEBUG_CATEGORY_DEPRECATION_AMD	DEBUG_CATEGORY_UNDEFINED_BEHAVIOR_AMD
DEBUG_CATEGORY_PERFORMANCE_AMD	DEBUG_CATEGORY_SHADER_COMPILER_AMD
DEBUG_CATEGORY_APPLICATION_AMD	DEBUG_CATEGORY_OTHER_AMD

severity - the message severity. One of:

DEBUG_SEVERITY_HIGH_AMD

DEBUG_SEVERITY_MEDIUM_AMD

DEBUG_SEVERITY_LOW_AMD

enabled - whether to enable or disable the referenced subset of messages

glDebugMessageInsertAMD

public static void glDebugMessageInsertAMD(int category,
                                           int severity,
                                           int id,
                                           java.nio.ByteBuffer buf)

public static void glDebugMessageInsertAMD(int category,
                                           int severity,
                                           int id,
                                           java.lang.CharSequence buf)

Injects an application-supplied message into the debug message stream.

The value of id specifies the ID for the message and severity indicates its severity level as defined by the application. If severity is not a valid severity level, the error INVALID_ENUM will be generated. The value of category must be DEBUG_CATEGORY_APPLICATION_AMD, or the error INVALID_ENUM will be generated. The string buf contains the string representation of the message. The parameter length contains the size of the message's string representation, excluding the null-terminator. If length is zero, then its value is derived from the string-length of buf and buf must contain a null-terminated string. The error INVALID_VALUE will be generated if length is less than zero or its derived value is larger than or equal to MAX_DEBUG_MESSAGE_LENGTH_AMD. The error INVALID_OPERATION will be generated if this function is called in a non-debug context.

Parameters:

category - the message category. Must be:

DEBUG_CATEGORY_APPLICATION_AMD

severity - the message severity. One of:

DEBUG_SEVERITY_HIGH_AMD

DEBUG_SEVERITY_MEDIUM_AMD

DEBUG_SEVERITY_LOW_AMD

id - the message id

buf - the message characters

glDebugMessageCallbackAMD

public static void glDebugMessageCallbackAMD(GLDebugMessageAMDCallbackI callback,
                                             long userParam)

Specifies a callback to receive debugging messages from the GL.

With callback storing the address of the callback function. This function's signature must follow the type definition of DEBUGPROCAMD, and its calling convention must be the same as the calling convention of GL functions. Anything else will result in undefined behavior. Only one debug callback can be specified for the current context, and further calls overwrite the previous callback. Specifying zero as the value of callback clears the current callback and disables message output through callbacks. Applications can specify user-specified data through the pointer userParam. The context will store this pointer and will include it as one of the parameters of each call to the callback function. The error INVALID_OPERATION will be generated if this function is called for contexts created without the debug flag.

If the application has specified a callback function in a debug context, the implementation will call that function whenever any unfiltered message is generated. The ID, category, and severity of the message are specified by the callback parameters id, category 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 value that was passed when calling DebugMessageCallbackAMD. The memory for message is allocated, owned and released by the implementation, and should only be considered valid for the duration of the callback function call. While it is allowed to concurrently use multiple debug contexts with the same debug callback function, note that it is the application's responsibility to ensure that any work that occurs inside the debug callback function is thread-safe. Furthermore, calling any GL or window layer function from within the callback function results in undefined behavior.

If no callback is set, then messages are instead stored in an internal message log up to some maximum number of strings as defined by the implementation-dependent constant MAX_DEBUG_LOGGED_MESSAGES_AMD. Each context stores its own message log and will only store messages generated by commands operating in that context. If the message log is full, then the oldest messages will be removed from the log to make room for newer ones. The application can query the number of messages currently in the log by obtaining the value of DEBUG_LOGGED_MESSAGES_AMD.

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

glGetDebugMessageLogAMD

public static int glGetDebugMessageLogAMD(int count,
                                          java.nio.IntBuffer categories,
                                          java.nio.IntBuffer severities,
                                          java.nio.IntBuffer ids,
                                          java.nio.IntBuffer lengths,
                                          java.nio.ByteBuffer messageLog)

Retrieves messages from the debug message log.

This function will fetch as many messages as possible from the message log up to count in order from oldest to newest, and will return the number of messages fetched. Those messages that were fetched will be removed from the log. The value of count must be greater than zero and less than MAX_DEBUG_LOGGED_MESSAGES_AMD or otherwise the error INVALID_VALUE will be generated. The value of count can be larger than the actual number of messages currently in the log. If messageLog is not a null pointer, then the string representations of all fetched messages will be stored in the buffer messageLog and will be separated by null-terminators. The maximum size of the buffer (including all null-terminators) is denoted by bufSize, and strings of messages within count that do not fit in the buffer will not be fetched. If bufSize is less than zero, the error INVALID_VALUE will be generated. If messageLog is a null pointer, then the value of bufSize is ignored. The categories, severity levels, IDs, and string representation lengths of all (up to count) removed messages will be stored in the arrays categories, severities, ids, and lengths, respectively. The counts stored in the array lengths include the null-terminator of each string. Any and all of the output arrays, including messageLog, are optional, and no data is returned for those arrays that are specified with a null pointer. To simply delete up to count messages from the message log and ignoring, the application can call the function with null pointers for all output arrays. The error INVALID_OPERATION will be generated by GetDebugMessageLogAMD if it is called in a non-debug context.

Parameters:

count - the number of debug messages to retrieve from the log

categories - an array of variables to receive the categories of the retrieved messages

severities - an array of variables to receive the severities of the retrieved messages

ids - an array of variables to receive the ids of the retrieved messages

lengths - an array of variables to receive the lengths of the retrieved messages

messageLog - an array of characters that will receive the messages

glDebugMessageEnableAMD

public static void glDebugMessageEnableAMD(int category,
                                           int severity,
                                           int[] ids,
                                           boolean enabled)

Array version of: DebugMessageEnableAMD

glGetDebugMessageLogAMD

public static int glGetDebugMessageLogAMD(int count,
                                          int[] categories,
                                          int[] severities,
                                          int[] ids,
                                          int[] lengths,
                                          java.nio.ByteBuffer messageLog)

Array version of: GetDebugMessageLogAMD