public class KHRDebug
extends java.lang.Object
This extension allows the GL to notify applications when various events occur that may be useful during application development, debugging and profiling.
These events are represented in the form of enumerable messages with a human-readable string representation. Examples of debug events include incorrect use of the GL, warnings of undefined behavior, and performance warnings.
A message is uniquely identified by a source, a type and an implementation-dependent ID within the source and type pair.
A message's source identifies the origin of the message and can either describe components of the GL, the window system, third-party external sources such as external debuggers, or even the application itself.
The type of the message roughly identifies the nature of the event that caused the message. Examples include errors, performance warnings, warnings about undefined behavior or notifications identifying that the application is within a specific section of the application code.
A message's ID for a given source and type further distinguishes messages within namespaces. For example, an error caused by a negative parameter value or an invalid internal texture format are both errors generated by the API, but would likely have different message IDs.
Each message is also assigned to a severity level that denotes roughly how "important" that message is in comparison to other messages across all sources and types. For example, notification of a GL error would likely have a higher severity than a performance warning due to redundant state changes.
Furthermore, every message contains an implementation-dependent string representation that provides a useful description of the event.
Messages are communicated to the application through an application-defined callback function that is called by the GL implementation on each debug message. The motivation for the callback routine is to free application developers from actively having to query whether a GL error, or any other debuggable event has happened after each call to a GL function. With a callback, developers can keep their code free of debug checks, set breakpoints in the callback function, and only have to react to messages as they occur. In situations where using a callback is not possible, a message log is also provided that stores only copies of recent messages until they are actively queried.
To control the volume of debug output, messages can be disabled either individually by ID, or entire sets of messages can be turned off based on combination of source and type, through the entire application code or only section of the code encapsulated in debug groups. A debug group may also be used to annotate the command stream using descriptive texts.
This extension also defines debug markers, a mechanism for the OpenGL application to annotate the command stream with markers for discrete events.
When profiling or debugging an OpenGL application with a built-in or an external debugger or profiler, it is difficult to relate the commands within the command stream to the elements of the scene or parts of the program code to which they correspond. Debug markers and debug groups help obviate this by allowing applications to specify this link. For example, a debug marker can be used to identify the beginning of a frame in the command stream and a debug group can encapsulate a specific command stream to identify a rendering pass. Debug groups also allow control of the debug outputs volume per section of an application code providing an effective way to handle the massive amount of debug outputs that drivers can generate.
Some existing implementations of ARB_debug_output only expose the ARB_debug_output extension string if the context was created with the debug
flag {GLX|WGL}_CONTEXT_DEBUG_BIT_ARB as specified in {GLX|WGL}_ARB_create_context. The behavior is not obvious when the functionality is brought into
the OpenGL core specification because the extension string and function entry points must always exist.
This extension modifies the existing ARB_debug_output extension to allow implementations to always have an empty message log. The specific messages written to the message log or callback routines are already implementation defined, so this specification simply makes it explicit that it's fine for there to be zero messages generated, even when a GL error occurs, which is useful if the context is non-debug.
Debug output can be enabled and disabled by changing the DEBUG_OUTPUT state. It is implementation defined how much debug output is generated if the
context was created without the CONTEXT_FLAG_DEBUG_BIT set. This is a new query bit added to the existing CONTEXT_FLAGS state to specify whether the
context was created with debug enabled.
Finally, this extension defines a mechanism for OpenGL applications to label their objects (textures, buffers, shaders, etc.) with a descriptive string.
When profiling or debugging an OpenGL application within an external or built-in (debut output API) debugger or profiler it is difficult to identify objects from their object names (integers).
Even when the object itself is viewed it can be problematic to differentiate between similar objects. Attaching a descriptive string, a label, to an object obviates this difficulty.
The intended purpose of this extension is purely to improve the user experience within OpenGL development tools and application built-in profilers and debuggers. This extension typically improves OpenGL programmers efficiency by allowing them to instantly detect issues and the reason for these issues giving him more time to focus on adding new features to an OpenGL application.
Promoted to core in OpenGL 4.3.
| Modifier and Type | Field and Description |
|---|---|
static int |
GL_BUFFER
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
static int |
GL_CONTEXT_FLAG_DEBUG_BIT
Returned by GetIntegerv when
pname is CONTEXT_FLAGS. |
static int |
GL_DEBUG_CALLBACK_FUNCTION
Tokens accepted by the
pname parameter of GetPointerv. |
static int |
GL_DEBUG_CALLBACK_USER_PARAM
Tokens accepted by the
pname parameter of GetPointerv. |
static int |
GL_DEBUG_GROUP_STACK_DEPTH
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_DEBUG_LOGGED_MESSAGES
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_DEBUG_OUTPUT
Tokens accepted by the
target parameters of Enable, Disable, and IsEnabled. |
static int |
GL_DEBUG_OUTPUT_SYNCHRONOUS
Tokens accepted by the
target parameters of Enable, Disable, and IsEnabled. |
static int |
GL_DEBUG_SEVERITY_HIGH
Tokens accepted or provided by the
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog. |
static int |
GL_DEBUG_SEVERITY_LOW
Tokens accepted or provided by the
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog. |
static int |
GL_DEBUG_SEVERITY_MEDIUM
Tokens accepted or provided by the
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog. |
static int |
GL_DEBUG_SEVERITY_NOTIFICATION
Tokens accepted or provided by the
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog. |
static int |
GL_DEBUG_SOURCE_API
Tokens accepted or provided by the
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details). |
static int |
GL_DEBUG_SOURCE_APPLICATION
Tokens accepted or provided by the
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details). |
static int |
GL_DEBUG_SOURCE_OTHER
Tokens accepted or provided by the
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details). |
static int |
GL_DEBUG_SOURCE_SHADER_COMPILER
Tokens accepted or provided by the
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details). |
static int |
GL_DEBUG_SOURCE_THIRD_PARTY
Tokens accepted or provided by the
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details). |
static int |
GL_DEBUG_SOURCE_WINDOW_SYSTEM
Tokens accepted or provided by the
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details). |
static int |
GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_ERROR
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_MARKER
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_OTHER
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_PERFORMANCE
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_POP_GROUP
Tokens accepted or provided by the
type parameters of DebugMessageControl and DEBUGPROC, and the types parameter of GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_PORTABILITY
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_PUSH_GROUP
Tokens accepted or provided by the
type parameters of DebugMessageControl and DEBUGPROC, and the types parameter of GetDebugMessageLog. |
static int |
GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR
Tokens accepted or provided by the
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog. |
static int |
GL_DISPLAY_LIST
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
static int |
GL_MAX_DEBUG_GROUP_STACK_DEPTH
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_MAX_DEBUG_LOGGED_MESSAGES
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_MAX_DEBUG_MESSAGE_LENGTH
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_MAX_LABEL_LENGTH
Tokens accepted by the
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v. |
static int |
GL_PROGRAM
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
static int |
GL_PROGRAM_PIPELINE
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
static int |
GL_QUERY
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
static int |
GL_SAMPLER
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
static int |
GL_SHADER
Tokens accepted or provided by the
identifier parameters of ObjectLabel and GetObjectLabel. |
| Modifier and Type | Method and Description |
|---|---|
static void |
glDebugMessageCallback(GLDebugMessageCallbackI callback,
long userParam)
Specifies a callback to receive debugging messages from the GL.
|
static void |
glDebugMessageControl(int source,
int type,
int severity,
int[] ids,
boolean enabled)
Array version of:
DebugMessageControl |
static void |
glDebugMessageControl(int source,
int type,
int severity,
int id,
boolean enabled)
Controls the volume of debug output in the active debug group, by disabling specific or groups of messages.
|
static void |
glDebugMessageControl(int source,
int type,
int severity,
java.nio.IntBuffer ids,
boolean enabled)
Controls the volume of debug output in the active debug group, by disabling specific or groups of messages.
|
static void |
glDebugMessageInsert(int source,
int type,
int id,
int severity,
java.nio.ByteBuffer message)
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 |
glDebugMessageInsert(int source,
int type,
int id,
int severity,
java.lang.CharSequence message)
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 |
glGetDebugMessageLog(int count,
int[] sources,
int[] types,
int[] ids,
int[] severities,
int[] lengths,
java.nio.ByteBuffer messageLog)
Array version of:
GetDebugMessageLog |
static int |
glGetDebugMessageLog(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)
Retrieves messages from the debug message log.
|
static java.lang.String |
glGetObjectLabel(int identifier,
int name)
Retrieves the label of a named object identified within a namespace.
|
static java.lang.String |
glGetObjectLabel(int identifier,
int name,
int bufSize)
Retrieves the label of a named object identified within a namespace.
|
static void |
glGetObjectLabel(int identifier,
int name,
int[] length,
java.nio.ByteBuffer label)
Array version of:
GetObjectLabel |
static void |
glGetObjectLabel(int identifier,
int name,
java.nio.IntBuffer length,
java.nio.ByteBuffer label)
Retrieves the label of a named object identified within a namespace.
|
static java.lang.String |
glGetObjectPtrLabel(long ptr)
Retrieves the label of a sync object identified by a pointer.
|
static java.lang.String |
glGetObjectPtrLabel(long ptr,
int bufSize)
Retrieves the label of a sync object identified by a pointer.
|
static void |
glGetObjectPtrLabel(long ptr,
int[] length,
java.nio.ByteBuffer label)
Array version of:
GetObjectPtrLabel |
static void |
glGetObjectPtrLabel(long ptr,
java.nio.IntBuffer length,
java.nio.ByteBuffer label)
Retrieves the label of a sync object identified by a pointer.
|
static void |
glObjectLabel(int identifier,
int name,
java.nio.ByteBuffer label)
Labels a named object identified within a namespace.
|
static void |
glObjectLabel(int identifier,
int name,
java.lang.CharSequence label)
Labels a named object identified within a namespace.
|
static void |
glObjectPtrLabel(long ptr,
java.nio.ByteBuffer label)
Labels a sync object identified by a pointer.
|
static void |
glObjectPtrLabel(long ptr,
java.lang.CharSequence label)
Labels a sync object identified by a pointer.
|
static void |
glPopDebugGroup()
Pops the active debug group.
|
static void |
glPushDebugGroup(int source,
int id,
java.nio.ByteBuffer message)
Pushes a debug group described by the string
message into the command stream. |
static void |
glPushDebugGroup(int source,
int id,
java.lang.CharSequence message)
Pushes a debug group described by the string
message into the command stream. |
static void |
nglDebugMessageCallback(long callback,
long userParam)
Unsafe version of:
DebugMessageCallback |
static void |
nglDebugMessageControl(int source,
int type,
int severity,
int count,
long ids,
boolean enabled)
Unsafe version of:
DebugMessageControl |
static void |
nglDebugMessageInsert(int source,
int type,
int id,
int severity,
int length,
long message)
Unsafe version of:
DebugMessageInsert |
static int |
nglGetDebugMessageLog(int count,
int bufsize,
long sources,
long types,
long ids,
long severities,
long lengths,
long messageLog)
Unsafe version of:
GetDebugMessageLog |
static void |
nglGetObjectLabel(int identifier,
int name,
int bufSize,
long length,
long label)
Unsafe version of:
GetObjectLabel |
static void |
nglGetObjectPtrLabel(long ptr,
int bufSize,
long length,
long label)
Unsafe version of:
GetObjectPtrLabel |
static void |
nglObjectLabel(int identifier,
int name,
int length,
long label)
Unsafe version of:
ObjectLabel |
static void |
nglObjectPtrLabel(long ptr,
int length,
long label)
Unsafe version of:
ObjectPtrLabel |
static void |
nglPushDebugGroup(int source,
int id,
int length,
long message)
Unsafe version of:
PushDebugGroup |
public static final int GL_DEBUG_OUTPUT
target parameters of Enable, Disable, and IsEnabled.public static final int GL_DEBUG_OUTPUT_SYNCHRONOUS
target parameters of Enable, Disable, and IsEnabled.public static final int GL_CONTEXT_FLAG_DEBUG_BIT
pname is CONTEXT_FLAGS.public static final int GL_MAX_DEBUG_MESSAGE_LENGTH
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_MAX_DEBUG_LOGGED_MESSAGES
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_DEBUG_LOGGED_MESSAGES
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_MAX_DEBUG_GROUP_STACK_DEPTH
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_DEBUG_GROUP_STACK_DEPTH
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_MAX_LABEL_LENGTH
value parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.public static final int GL_DEBUG_CALLBACK_FUNCTION
pname parameter of GetPointerv.public static final int GL_DEBUG_CALLBACK_USER_PARAM
pname parameter of GetPointerv.public static final int GL_DEBUG_SOURCE_API
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details).public static final int GL_DEBUG_SOURCE_WINDOW_SYSTEM
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details).public static final int GL_DEBUG_SOURCE_SHADER_COMPILER
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details).public static final int GL_DEBUG_SOURCE_THIRD_PARTY
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details).public static final int GL_DEBUG_SOURCE_APPLICATION
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details).public static final int GL_DEBUG_SOURCE_OTHER
source parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the sources parameter
of GetDebugMessageLog (some commands restrict source to a subset of these parameters; see the specification body for details).public static final int GL_DEBUG_TYPE_ERROR
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_PORTABILITY
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_PERFORMANCE
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_OTHER
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_MARKER
type parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the types parameter of
GetDebugMessageLog.public static final int GL_DEBUG_TYPE_PUSH_GROUP
type parameters of DebugMessageControl and DEBUGPROC, and the types parameter of GetDebugMessageLog.public static final int GL_DEBUG_TYPE_POP_GROUP
type parameters of DebugMessageControl and DEBUGPROC, and the types parameter of GetDebugMessageLog.public static final int GL_DEBUG_SEVERITY_HIGH
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog.public static final int GL_DEBUG_SEVERITY_MEDIUM
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog.public static final int GL_DEBUG_SEVERITY_LOW
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog.public static final int GL_DEBUG_SEVERITY_NOTIFICATION
severity parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and the
severities parameter of GetDebugMessageLog.public static final int GL_BUFFER
identifier parameters of ObjectLabel and GetObjectLabel.public static final int GL_SHADER
identifier parameters of ObjectLabel and GetObjectLabel.public static final int GL_PROGRAM
identifier parameters of ObjectLabel and GetObjectLabel.public static final int GL_QUERY
identifier parameters of ObjectLabel and GetObjectLabel.public static final int GL_PROGRAM_PIPELINE
identifier parameters of ObjectLabel and GetObjectLabel.public static final int GL_SAMPLER
identifier parameters of ObjectLabel and GetObjectLabel.public static final int GL_DISPLAY_LIST
identifier parameters of ObjectLabel and GetObjectLabel.public static void nglDebugMessageControl(int source,
int type,
int severity,
int count,
long ids,
boolean enabled)
DebugMessageControlcount - the length of the array idspublic static void glDebugMessageControl(int source,
int type,
int severity,
@Nullable
java.nio.IntBuffer 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:
source, type, or severity is DONT_CARE, the messages from all sources, of all types, or of all severities are
referenced respectively.DONT_CARE are specified, all messages whose source, type, or severity match the specified source, type,
or severity respectively will be referenced.count is greater than zero, then ids is an array of count message IDs for the specified combination of source and
type. In this case, if source or type is DONT_CARE, or severity is not DONT_CARE, the error
INVALID_OPERATION is generated.Unrecognized message IDs in ids are ignored. If count is zero, the value if ids is ignored.
Although messages are grouped into an implicit hierarchy by their sources and types, there is no explicit per-source, per-type or per-severity enabled state. Instead, the enabled state is stored individually for each message. There is no difference between disabling all messages from one source in a single call, and individually disabling all messages from that source using their types and IDs.
If the DEBUG_OUTPUT state is disabled the GL operates the same as if messages of every source, type or severity are disabled.
source - the source of debug messages to enable or disable. One of:DEBUG_SOURCE_API | DEBUG_SOURCE_WINDOW_SYSTEM | DEBUG_SOURCE_SHADER_COMPILER |
DEBUG_SOURCE_THIRD_PARTY | DEBUG_SOURCE_APPLICATION | DEBUG_SOURCE_OTHER |
type - the type of debug messages to enable or disable. One of:DEBUG_TYPE_ERROR | DEBUG_TYPE_DEPRECATED_BEHAVIOR | DEBUG_TYPE_UNDEFINED_BEHAVIOR |
DEBUG_TYPE_PORTABILITY | DEBUG_TYPE_PERFORMANCE | DEBUG_TYPE_OTHER |
DEBUG_TYPE_MARKER |
severity - the severity of debug messages to enable or disable. One of:DEBUG_SEVERITY_HIGH | DEBUG_SEVERITY_MEDIUM | DEBUG_SEVERITY_LOW |
DEBUG_SEVERITY_NOTIFICATION |
ids - an array of unsigned integers containing the ids of the messages to enable or disableenabled - whether the selected messages should be enabled or disabledpublic static void glDebugMessageControl(int source,
int type,
int severity,
int id,
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:
source, type, or severity is DONT_CARE, the messages from all sources, of all types, or of all severities are
referenced respectively.DONT_CARE are specified, all messages whose source, type, or severity match the specified source, type,
or severity respectively will be referenced.count is greater than zero, then ids is an array of count message IDs for the specified combination of source and
type. In this case, if source or type is DONT_CARE, or severity is not DONT_CARE, the error
INVALID_OPERATION is generated.Unrecognized message IDs in ids are ignored. If count is zero, the value if ids is ignored.
Although messages are grouped into an implicit hierarchy by their sources and types, there is no explicit per-source, per-type or per-severity enabled state. Instead, the enabled state is stored individually for each message. There is no difference between disabling all messages from one source in a single call, and individually disabling all messages from that source using their types and IDs.
If the DEBUG_OUTPUT state is disabled the GL operates the same as if messages of every source, type or severity are disabled.
source - the source of debug messages to enable or disable. One of:DEBUG_SOURCE_API | DEBUG_SOURCE_WINDOW_SYSTEM | DEBUG_SOURCE_SHADER_COMPILER |
DEBUG_SOURCE_THIRD_PARTY | DEBUG_SOURCE_APPLICATION | DEBUG_SOURCE_OTHER |
type - the type of debug messages to enable or disable. One of:DEBUG_TYPE_ERROR | DEBUG_TYPE_DEPRECATED_BEHAVIOR | DEBUG_TYPE_UNDEFINED_BEHAVIOR |
DEBUG_TYPE_PORTABILITY | DEBUG_TYPE_PERFORMANCE | DEBUG_TYPE_OTHER |
DEBUG_TYPE_MARKER |
severity - the severity of debug messages to enable or disable. One of:DEBUG_SEVERITY_HIGH | DEBUG_SEVERITY_MEDIUM | DEBUG_SEVERITY_LOW |
DEBUG_SEVERITY_NOTIFICATION |
enabled - whether the selected messages should be enabled or disabledpublic static void nglDebugMessageInsert(int source,
int type,
int id,
int severity,
int length,
long message)
DebugMessageInsertlength - the length of the string contained in the character array whose address is given by messagepublic static void glDebugMessageInsert(int source,
int type,
int id,
int severity,
java.nio.ByteBuffer message)
The value of id specifies the ID for the message and severity indicates its severity level as defined by the caller. The string
buf contains the string representation of the message. The parameter length contains the number of characters in buf. If
length is negative, it is implied that buf contains a null terminated string. The error INVALID_VALUE will be generated if the
number of characters in buf, excluding the null terminator when length is negative, is not less than the value of
MAX_DEBUG_MESSAGE_LENGTH.
If the DEBUG_OUTPUT state is disabled calls to DebugMessageInsert are discarded and do not generate an error.
source - the source of the debug message to insert. One of:DEBUG_SOURCE_API | DEBUG_SOURCE_WINDOW_SYSTEM | DEBUG_SOURCE_SHADER_COMPILER |
DEBUG_SOURCE_THIRD_PARTY | DEBUG_SOURCE_APPLICATION | DEBUG_SOURCE_OTHER |
type - the type of the debug message insert. One of:DEBUG_TYPE_ERROR | DEBUG_TYPE_DEPRECATED_BEHAVIOR | DEBUG_TYPE_UNDEFINED_BEHAVIOR |
DEBUG_TYPE_PORTABILITY | DEBUG_TYPE_PERFORMANCE | DEBUG_TYPE_OTHER |
DEBUG_TYPE_MARKER |
id - the user-supplied identifier of the message to insert. One of:DEBUG_SEVERITY_HIGH | DEBUG_SEVERITY_MEDIUM | DEBUG_SEVERITY_LOW |
DEBUG_SEVERITY_NOTIFICATION |
severity - the severity of the debug messages to insertmessage - a character array containing the message to insertpublic static void glDebugMessageInsert(int source,
int type,
int id,
int severity,
java.lang.CharSequence message)
The value of id specifies the ID for the message and severity indicates its severity level as defined by the caller. The string
buf contains the string representation of the message. The parameter length contains the number of characters in buf. If
length is negative, it is implied that buf contains a null terminated string. The error INVALID_VALUE will be generated if the
number of characters in buf, excluding the null terminator when length is negative, is not less than the value of
MAX_DEBUG_MESSAGE_LENGTH.
If the DEBUG_OUTPUT state is disabled calls to DebugMessageInsert are discarded and do not generate an error.
source - the source of the debug message to insert. One of:DEBUG_SOURCE_API | DEBUG_SOURCE_WINDOW_SYSTEM | DEBUG_SOURCE_SHADER_COMPILER |
DEBUG_SOURCE_THIRD_PARTY | DEBUG_SOURCE_APPLICATION | DEBUG_SOURCE_OTHER |
type - the type of the debug message insert. One of:DEBUG_TYPE_ERROR | DEBUG_TYPE_DEPRECATED_BEHAVIOR | DEBUG_TYPE_UNDEFINED_BEHAVIOR |
DEBUG_TYPE_PORTABILITY | DEBUG_TYPE_PERFORMANCE | DEBUG_TYPE_OTHER |
DEBUG_TYPE_MARKER |
id - the user-supplied identifier of the message to insert. One of:DEBUG_SEVERITY_HIGH | DEBUG_SEVERITY_MEDIUM | DEBUG_SEVERITY_LOW |
DEBUG_SEVERITY_NOTIFICATION |
severity - the severity of the debug messages to insertmessage - a character array containing the message to insertpublic static void nglDebugMessageCallback(long callback,
long userParam)
DebugMessageCallbackpublic static void glDebugMessageCallback(@Nullable
GLDebugMessageCallbackI callback,
long userParam)
The function's prototype must follow the type definition of DEBUGPROC including its platform-dependent calling convention. Anything else will result in
undefined behavior. Only one debug callback can be specified for the current context, and further calls overwrite the previous callback. Specifying
NULL as the value of callback clears the current callback and disables message output through callbacks. Applications can provide
user-specified data through the pointer userParam. The context will store this pointer and will include it as one of the parameters in each call
to the callback function.
If the application has specified a callback function for receiving debug output, the implementation will call that function whenever any enabled message
is generated. The source, type, ID, and severity of the message are specified by the DEBUGPROC parameters source, type, id, and
severity, respectively. The string representation of the message is stored in message and its length (excluding the null-terminator) is
stored in length. The parameter userParam is the user-specified parameter that was given when calling DebugMessageCallback.
Applications can query the current callback function and the current user-specified parameter by obtaining the values of DEBUG_CALLBACK_FUNCTION and
DEBUG_CALLBACK_USER_PARAM, respectively.
Applications that specify a callback function must be aware of certain special conditions when executing code inside a callback when it is called by the GL, regardless of the debug source.
The memory for message is owned and managed by the GL, and should only be considered valid for the duration of the function call.
The behavior of calling any GL or window system function from within the callback function is undefined and may lead to program termination.
Care must also be taken in securing debug callbacks for use with asynchronous debug output by multi-threaded GL implementations.
If the DEBUG_OUTPUT state is disabled then the GL will not call the callback function.
callback - a callback function that will be called when a debug message is generateduserParam - a user supplied pointer that will be passed on each invocation of callbackpublic static int nglGetDebugMessageLog(int count,
int bufsize,
long sources,
long types,
long ids,
long severities,
long lengths,
long messageLog)
GetDebugMessageLogbufsize - the size of the buffer whose address is given by messageLogpublic static int glGetDebugMessageLog(int count,
@Nullable
java.nio.IntBuffer sources,
@Nullable
java.nio.IntBuffer types,
@Nullable
java.nio.IntBuffer ids,
@Nullable
java.nio.IntBuffer severities,
@Nullable
java.nio.IntBuffer lengths,
@Nullable
java.nio.ByteBuffer messageLog)
This function fetches a maximum of count messages from the message log, and will return the number of messages successfully fetched.
Messages will be fetched from the log in order of oldest to newest. Those messages that were fetched will be removed from the log.
The sources, types, severities, IDs, and string lengths of fetched messages will be stored in the application-provided arrays sources,
types, severities, ids, and lengths, respectively. The application is responsible for allocating enough space for each
array to hold up to count elements. The string representations of all fetched messages are stored in the messageLog array. If multiple
messages are fetched, their strings are concatenated into the same messageLog array and will be separated by single null terminators. The last
string in the array will also be null-terminated. The maximum size of messageLog, including the space used by all null terminators, is given by
bufSize. If bufSize is less than zero and messageLog is not NULL, an INVALID_VALUE error will be generated. If a message's
string, including its null terminator, can not fully fit within the messageLog array's remaining space, then that message and any subsequent
messages will not be fetched and will remain in the log. The string lengths stored in the array lengths include the space for the null
terminator of each string.
Any or all of the arrays sources, types, ids, severities, lengths and messageLog can also be null
pointers, which causes the attributes for such arrays to be discarded when messages are fetched, however those messages will still be removed from the
log. Thus to simply delete up to count messages from the message log while ignoring their attributes, the application can call the function
with null pointers for all attribute arrays.
If the context was created without the CONTEXT_FLAG_DEBUG_BIT in the CONTEXT_FLAGS state, then the GL can opt to never add messages to the
message log so GetDebugMessageLog will always return zero.
count - the number of debug messages to retrieve from the logsources - an array of variables to receive the sources of the retrieved messagestypes - an array of variables to receive the types of the retrieved messagesids - an array of unsigned integers to receive the ids of the retrieved messagesseverities - an array of variables to receive the severites of the retrieved messageslengths - an array of variables to receive the lengths of the received messagesmessageLog - an array of characters that will receive the messagespublic static void nglPushDebugGroup(int source,
int id,
int length,
long message)
PushDebugGrouplength - the length of the message to be sent to the debug output streampublic static void glPushDebugGroup(int source,
int id,
java.nio.ByteBuffer message)
message into the command stream. The value of id specifies the ID of messages generated.
The parameter length contains the number of characters in message. If length is negative, it is implied that message
contains a null terminated string. The message has the specified source and id, type DEBUG_TYPE_PUSH_GROUP, and
severity DEBUG_SEVERITY_NOTIFICATION. The GL will put a new debug group on top of the debug group stack which inherits the control of the
volume of debug output of the debug group previously residing on the top of the debug group stack. Because debug groups are strictly hierarchical, any
additional control of the debug output volume will only apply within the active debug group and the debug groups pushed on top of the active debug group.
An INVALID_ENUM error is generated if the value of source is neither DEBUG_SOURCE_APPLICATION nor DEBUG_SOURCE_THIRD_PARTY. An
INVALID_VALUE error is generated if length is negative and the number of characters in message, excluding the null-terminator, is
not less than the value of MAX_DEBUG_MESSAGE_LENGTH.
source - the source of the debug message. One of:DEBUG_SOURCE_APPLICATION | DEBUG_SOURCE_THIRD_PARTY |
id - the identifier of the messagemessage - a string containing the message to be sent to the debug output streampublic static void glPushDebugGroup(int source,
int id,
java.lang.CharSequence message)
message into the command stream. The value of id specifies the ID of messages generated.
The parameter length contains the number of characters in message. If length is negative, it is implied that message
contains a null terminated string. The message has the specified source and id, type DEBUG_TYPE_PUSH_GROUP, and
severity DEBUG_SEVERITY_NOTIFICATION. The GL will put a new debug group on top of the debug group stack which inherits the control of the
volume of debug output of the debug group previously residing on the top of the debug group stack. Because debug groups are strictly hierarchical, any
additional control of the debug output volume will only apply within the active debug group and the debug groups pushed on top of the active debug group.
An INVALID_ENUM error is generated if the value of source is neither DEBUG_SOURCE_APPLICATION nor DEBUG_SOURCE_THIRD_PARTY. An
INVALID_VALUE error is generated if length is negative and the number of characters in message, excluding the null-terminator, is
not less than the value of MAX_DEBUG_MESSAGE_LENGTH.
source - the source of the debug message. One of:DEBUG_SOURCE_APPLICATION | DEBUG_SOURCE_THIRD_PARTY |
id - the identifier of the messagemessage - a string containing the message to be sent to the debug output streampublic static void glPopDebugGroup()
message string, the source source, and an ID id submitted to the associated PushDebugGroup command. DEBUG_TYPE_PUSH_GROUP
and DEBUG_TYPE_POP_GROUP share a single namespace for message id. severity has the value DEBUG_SEVERITY_NOTIFICATION. The type
has the value DEBUG_TYPE_POP_GROUP. Popping a debug group restores the debug output volume control of the parent debug group.
Attempting to pop the default debug group off the stack generates a STACK_UNDERFLOW error; pushing a debug group onto a stack containing
MAX_DEBUG_GROUP_STACK_DEPTH minus one elements will generate a STACK_OVERFLOW error.
public static void nglObjectLabel(int identifier,
int name,
int length,
long label)
ObjectLabellength - the length of the label to be used for the objectpublic static void glObjectLabel(int identifier,
int name,
java.nio.ByteBuffer label)
identifier - the namespace from which the name of the object is allocated. One of:BUFFER | SHADER | PROGRAM | QUERY | PROGRAM_PIPELINE | SAMPLER | VERTEX_ARRAY | TEXTURE |
RENDERBUFFER | FRAMEBUFFER | TRANSFORM_FEEDBACK |
name - the name of the object to labellabel - a string containing the label to assign to the objectpublic static void glObjectLabel(int identifier,
int name,
java.lang.CharSequence label)
identifier - the namespace from which the name of the object is allocated. One of:BUFFER | SHADER | PROGRAM | QUERY | PROGRAM_PIPELINE | SAMPLER | VERTEX_ARRAY | TEXTURE |
RENDERBUFFER | FRAMEBUFFER | TRANSFORM_FEEDBACK |
name - the name of the object to labellabel - a string containing the label to assign to the objectpublic static void nglGetObjectLabel(int identifier,
int name,
int bufSize,
long length,
long label)
GetObjectLabelbufSize - the length of the buffer whose address is in labelpublic static void glGetObjectLabel(int identifier,
int name,
@Nullable
java.nio.IntBuffer length,
java.nio.ByteBuffer label)
identifier - the namespace from which the name of the object is allocated. One of:BUFFER | SHADER | PROGRAM | QUERY | PROGRAM_PIPELINE | SAMPLER | VERTEX_ARRAY | TEXTURE |
RENDERBUFFER | FRAMEBUFFER | TRANSFORM_FEEDBACK |
name - the name of the object whose label to retrievelength - the address of a variable to receive the length of the object labellabel - a string that will receive the object labelpublic static java.lang.String glGetObjectLabel(int identifier,
int name,
int bufSize)
identifier - the namespace from which the name of the object is allocated. One of:BUFFER | SHADER | PROGRAM | QUERY | PROGRAM_PIPELINE | SAMPLER | VERTEX_ARRAY | TEXTURE |
RENDERBUFFER | FRAMEBUFFER | TRANSFORM_FEEDBACK |
name - the name of the object whose label to retrievebufSize - the length of the buffer whose address is in labelpublic static java.lang.String glGetObjectLabel(int identifier,
int name)
identifier - the namespace from which the name of the object is allocated. One of:BUFFER | SHADER | PROGRAM | QUERY | PROGRAM_PIPELINE | SAMPLER | VERTEX_ARRAY | TEXTURE |
RENDERBUFFER | FRAMEBUFFER | TRANSFORM_FEEDBACK |
name - the name of the object whose label to retrievepublic static void nglObjectPtrLabel(long ptr,
int length,
long label)
ObjectPtrLabellength - the length of the label to be used for the objectpublic static void glObjectPtrLabel(long ptr,
java.nio.ByteBuffer label)
ptr - a pointer identifying a sync objectlabel - a string containing the label to assign to the objectpublic static void glObjectPtrLabel(long ptr,
java.lang.CharSequence label)
ptr - a pointer identifying a sync objectlabel - a string containing the label to assign to the objectpublic static void nglGetObjectPtrLabel(long ptr,
int bufSize,
long length,
long label)
GetObjectPtrLabelbufSize - the length of the buffer whose address is in labelpublic static void glGetObjectPtrLabel(long ptr,
@Nullable
java.nio.IntBuffer length,
java.nio.ByteBuffer label)
ptr - the name of the sync object whose label to retrievelength - a variable to receive the length of the object labellabel - a string that will receive the object labelpublic static java.lang.String glGetObjectPtrLabel(long ptr,
int bufSize)
ptr - the name of the sync object whose label to retrievebufSize - the length of the buffer whose address is in labelpublic static java.lang.String glGetObjectPtrLabel(long ptr)
ptr - the name of the sync object whose label to retrievepublic static void glDebugMessageControl(int source,
int type,
int severity,
@Nullable
int[] ids,
boolean enabled)
DebugMessageControlpublic static int glGetDebugMessageLog(int count,
@Nullable
int[] sources,
@Nullable
int[] types,
@Nullable
int[] ids,
@Nullable
int[] severities,
@Nullable
int[] lengths,
@Nullable
java.nio.ByteBuffer messageLog)
GetDebugMessageLogpublic static void glGetObjectLabel(int identifier,
int name,
@Nullable
int[] length,
java.nio.ByteBuffer label)
GetObjectLabelpublic static void glGetObjectPtrLabel(long ptr,
@Nullable
int[] length,
java.nio.ByteBuffer label)
GetObjectPtrLabelCopyright LWJGL. All Rights Reserved. License terms.