Class KHRDebug
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_KHR
state.
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.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Tokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.static final int
Returned by GetIntegerv whenpname
is CONTEXT_FLAGS.static final int
Tokens accepted by thepname
parameter of GetPointerv.static final int
Tokens accepted by thepname
parameter of GetPointerv.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted by thetarget
parameters of Enable, Disable, and IsEnabled.static final int
Tokens accepted by thetarget
parameters of Enable, Disable, and IsEnabled.static final int
Tokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.static final int
Tokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.static final int
Tokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.static final int
Tokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.static final int
Tokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.static final int
Tokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.static final int
Returned by GetError.static final int
Returned by GetError. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
glDebugMessageCallbackKHR
(GLDebugMessageKHRCallbackI callback, long userParam) Specifies a callback to receive debugging messages from the GL.static void
glDebugMessageControlKHR
(int source, int type, int severity, int[] ids, boolean enabled) Array version of:DebugMessageControlKHR
static void
glDebugMessageControlKHR
(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
glDebugMessageControlKHR
(int source, int type, int severity, IntBuffer ids, boolean enabled) Controls the volume of debug output in the active debug group, by disabling specific or groups of messages.static void
glDebugMessageInsertKHR
(int source, int type, int id, int severity, 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 void
glDebugMessageInsertKHR
(int source, int type, int id, int severity, 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 int
glGetDebugMessageLogKHR
(int count, int[] sources, int[] types, int[] ids, int[] severities, int[] lengths, ByteBuffer messageLog) Array version of:GetDebugMessageLogKHR
static int
glGetDebugMessageLogKHR
(int count, IntBuffer sources, IntBuffer types, IntBuffer ids, IntBuffer severities, IntBuffer lengths, ByteBuffer messageLog) Retrieves messages from the debug message log.static String
glGetObjectLabelKHR
(int identifier, int name) Retrieves the label of a named object identified within a namespace.static String
glGetObjectLabelKHR
(int identifier, int name, int bufSize) Retrieves the label of a named object identified within a namespace.static void
glGetObjectLabelKHR
(int identifier, int name, int[] length, ByteBuffer label) Array version of:GetObjectLabelKHR
static void
glGetObjectLabelKHR
(int identifier, int name, IntBuffer length, ByteBuffer label) Retrieves the label of a named object identified within a namespace.static String
glGetObjectPtrLabelKHR
(long ptr) Retrieves the label of a sync object identified by a pointer.static String
glGetObjectPtrLabelKHR
(long ptr, int bufSize) Retrieves the label of a sync object identified by a pointer.static void
glGetObjectPtrLabelKHR
(long ptr, int[] length, ByteBuffer label) Array version of:GetObjectPtrLabelKHR
static void
glGetObjectPtrLabelKHR
(long ptr, IntBuffer length, ByteBuffer label) Retrieves the label of a sync object identified by a pointer.static long
glGetPointerKHR
(int pname) static void
glGetPointervKHR
(int pname, PointerBuffer params) static void
glObjectLabelKHR
(int identifier, int name, CharSequence label) Labels a named object identified within a namespace.static void
glObjectLabelKHR
(int identifier, int name, ByteBuffer label) Labels a named object identified within a namespace.static void
glObjectPtrLabelKHR
(long ptr, CharSequence label) Labels a sync object identified by a pointer.static void
glObjectPtrLabelKHR
(long ptr, ByteBuffer label) Labels a sync object identified by a pointer.static void
Pops the active debug group.static void
glPushDebugGroupKHR
(int source, int id, CharSequence message) Pushes a debug group described by the stringmessage
into the command stream.static void
glPushDebugGroupKHR
(int source, int id, ByteBuffer message) Pushes a debug group described by the stringmessage
into the command stream.static void
nglDebugMessageCallbackKHR
(long callback, long userParam) Unsafe version of:DebugMessageCallbackKHR
static void
nglDebugMessageControlKHR
(int source, int type, int severity, int count, long ids, boolean enabled) Unsafe version of:DebugMessageControlKHR
static void
nglDebugMessageInsertKHR
(int source, int type, int id, int severity, int length, long message) Unsafe version of:DebugMessageInsertKHR
static int
nglGetDebugMessageLogKHR
(int count, int bufsize, long sources, long types, long ids, long severities, long lengths, long messageLog) Unsafe version of:GetDebugMessageLogKHR
static void
nglGetObjectLabelKHR
(int identifier, int name, int bufSize, long length, long label) Unsafe version of:GetObjectLabelKHR
static void
nglGetObjectPtrLabelKHR
(long ptr, int bufSize, long length, long label) Unsafe version of:GetObjectPtrLabelKHR
static void
nglGetPointervKHR
(int pname, long params) static void
nglObjectLabelKHR
(int identifier, int name, int length, long label) Unsafe version of:ObjectLabelKHR
static void
nglObjectPtrLabelKHR
(long ptr, int length, long label) Unsafe version of:ObjectPtrLabelKHR
static void
nglPushDebugGroupKHR
(int source, int id, int length, long message) Unsafe version of:PushDebugGroupKHR
-
Field Details
-
GL_DEBUG_OUTPUT_KHR
public static final int GL_DEBUG_OUTPUT_KHRTokens accepted by thetarget
parameters of Enable, Disable, and IsEnabled.- See Also:
-
GL_DEBUG_OUTPUT_SYNCHRONOUS_KHR
public static final int GL_DEBUG_OUTPUT_SYNCHRONOUS_KHRTokens accepted by thetarget
parameters of Enable, Disable, and IsEnabled.- See Also:
-
GL_CONTEXT_FLAG_DEBUG_BIT_KHR
public static final int GL_CONTEXT_FLAG_DEBUG_BIT_KHRReturned by GetIntegerv whenpname
is CONTEXT_FLAGS.- See Also:
-
GL_MAX_DEBUG_MESSAGE_LENGTH_KHR
public static final int GL_MAX_DEBUG_MESSAGE_LENGTH_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_MAX_DEBUG_LOGGED_MESSAGES_KHR
public static final int GL_MAX_DEBUG_LOGGED_MESSAGES_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_DEBUG_LOGGED_MESSAGES_KHR
public static final int GL_DEBUG_LOGGED_MESSAGES_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_KHR
public static final int GL_DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_MAX_DEBUG_GROUP_STACK_DEPTH_KHR
public static final int GL_MAX_DEBUG_GROUP_STACK_DEPTH_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_DEBUG_GROUP_STACK_DEPTH_KHR
public static final int GL_DEBUG_GROUP_STACK_DEPTH_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_MAX_LABEL_LENGTH_KHR
public static final int GL_MAX_LABEL_LENGTH_KHRTokens accepted by thevalue
parameters of GetBooleanv, GetIntegerv, GetFloatv, GetDoublev and GetInteger64v.- See Also:
-
GL_DEBUG_CALLBACK_FUNCTION_KHR
public static final int GL_DEBUG_CALLBACK_FUNCTION_KHRTokens accepted by thepname
parameter of GetPointerv.- See Also:
-
GL_DEBUG_CALLBACK_USER_PARAM_KHR
public static final int GL_DEBUG_CALLBACK_USER_PARAM_KHRTokens accepted by thepname
parameter of GetPointerv.- See Also:
-
GL_DEBUG_SOURCE_API_KHR
public static final int GL_DEBUG_SOURCE_API_KHRTokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SOURCE_WINDOW_SYSTEM_KHR
public static final int GL_DEBUG_SOURCE_WINDOW_SYSTEM_KHRTokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SOURCE_SHADER_COMPILER_KHR
public static final int GL_DEBUG_SOURCE_SHADER_COMPILER_KHRTokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SOURCE_THIRD_PARTY_KHR
public static final int GL_DEBUG_SOURCE_THIRD_PARTY_KHRTokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SOURCE_APPLICATION_KHR
public static final int GL_DEBUG_SOURCE_APPLICATION_KHRTokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SOURCE_OTHER_KHR
public static final int GL_DEBUG_SOURCE_OTHER_KHRTokens accepted or provided by thesource
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thesources
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_ERROR_KHR
public static final int GL_DEBUG_TYPE_ERROR_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHR
public static final int GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHR
public static final int GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_PORTABILITY_KHR
public static final int GL_DEBUG_TYPE_PORTABILITY_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_PERFORMANCE_KHR
public static final int GL_DEBUG_TYPE_PERFORMANCE_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_OTHER_KHR
public static final int GL_DEBUG_TYPE_OTHER_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_MARKER_KHR
public static final int GL_DEBUG_TYPE_MARKER_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_PUSH_GROUP_KHR
public static final int GL_DEBUG_TYPE_PUSH_GROUP_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_TYPE_POP_GROUP_KHR
public static final int GL_DEBUG_TYPE_POP_GROUP_KHRTokens accepted or provided by thetype
parameters of DebugMessageControl and DEBUGPROC, and thetypes
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SEVERITY_HIGH_KHR
public static final int GL_DEBUG_SEVERITY_HIGH_KHRTokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SEVERITY_MEDIUM_KHR
public static final int GL_DEBUG_SEVERITY_MEDIUM_KHRTokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SEVERITY_LOW_KHR
public static final int GL_DEBUG_SEVERITY_LOW_KHRTokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.- See Also:
-
GL_DEBUG_SEVERITY_NOTIFICATION_KHR
public static final int GL_DEBUG_SEVERITY_NOTIFICATION_KHRTokens accepted or provided by theseverity
parameters of DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, and theseverities
parameter of GetDebugMessageLog.- See Also:
-
GL_STACK_UNDERFLOW_KHR
public static final int GL_STACK_UNDERFLOW_KHRReturned by GetError.- See Also:
-
GL_STACK_OVERFLOW_KHR
public static final int GL_STACK_OVERFLOW_KHRReturned by GetError.- See Also:
-
GL_BUFFER_KHR
public static final int GL_BUFFER_KHRTokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.- See Also:
-
GL_SHADER_KHR
public static final int GL_SHADER_KHRTokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.- See Also:
-
GL_PROGRAM_KHR
public static final int GL_PROGRAM_KHRTokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.- See Also:
-
GL_QUERY_KHR
public static final int GL_QUERY_KHRTokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.- See Also:
-
GL_PROGRAM_PIPELINE_KHR
public static final int GL_PROGRAM_PIPELINE_KHRTokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.- See Also:
-
GL_SAMPLER_KHR
public static final int GL_SAMPLER_KHRTokens accepted or provided by theidentifier
parameters of ObjectLabel and GetObjectLabel.- See Also:
-
-
Method Details
-
nglDebugMessageControlKHR
public static void nglDebugMessageControlKHR(int source, int type, int severity, int count, long ids, boolean enabled) Unsafe version of:DebugMessageControlKHR
- Parameters:
count
- the length of the arrayids
-
glDebugMessageControlKHR
public static void glDebugMessageControlKHR(int source, int type, int severity, @Nullable IntBuffer ids, boolean enabled) Controls the volume of debug output in the active debug group, by disabling specific or groups of messages.If
enabled
isTRUE
, the referenced subset of messages will be enabled. IfFALSE
, 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
,type
, orseverity
isDONT_CARE
, the messages from all sources, of all types, or of all severities are referenced respectively. - When values other than
DONT_CARE
are specified, all messages whose source, type, or severity match the specifiedsource
,type
, orseverity
respectively will be referenced. - If
count
is greater than zero, thenids
is an array ofcount
message IDs for the specified combination ofsource
andtype
. In this case, ifsource
ortype
isDONT_CARE
, orseverity
is notDONT_CARE
, the errorINVALID_OPERATION
is generated.
Unrecognized message IDs in
ids
are ignored. Ifcount
is zero, the value ifids
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_KHR
state is disabled the GL operates the same as if messages of everysource
,type
orseverity
are disabled.- Parameters:
source
- the source of debug messages to enable or disable. One of:DEBUG_SOURCE_API_KHR
DEBUG_SOURCE_WINDOW_SYSTEM_KHR
DEBUG_SOURCE_SHADER_COMPILER_KHR
DEBUG_SOURCE_THIRD_PARTY_KHR
DEBUG_SOURCE_APPLICATION_KHR
DEBUG_SOURCE_OTHER_KHR
type
- the type of debug messages to enable or disable. One of:DEBUG_TYPE_ERROR_KHR
DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHR
DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHR
DEBUG_TYPE_PORTABILITY_KHR
DEBUG_TYPE_PERFORMANCE_KHR
DEBUG_TYPE_OTHER_KHR
DEBUG_TYPE_MARKER_KHR
severity
- the severity of debug messages to enable or disable. One of:DEBUG_SEVERITY_HIGH_KHR
DEBUG_SEVERITY_MEDIUM_KHR
DEBUG_SEVERITY_LOW_KHR
DEBUG_SEVERITY_NOTIFICATION_KHR
ids
- an array of unsigned integers containing the ids of the messages to enable or disableenabled
- whether the selected messages should be enabled or disabled
- If
-
glDebugMessageControlKHR
public static void glDebugMessageControlKHR(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.If
enabled
isTRUE
, the referenced subset of messages will be enabled. IfFALSE
, 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
,type
, orseverity
isDONT_CARE
, the messages from all sources, of all types, or of all severities are referenced respectively. - When values other than
DONT_CARE
are specified, all messages whose source, type, or severity match the specifiedsource
,type
, orseverity
respectively will be referenced. - If
count
is greater than zero, thenids
is an array ofcount
message IDs for the specified combination ofsource
andtype
. In this case, ifsource
ortype
isDONT_CARE
, orseverity
is notDONT_CARE
, the errorINVALID_OPERATION
is generated.
Unrecognized message IDs in
ids
are ignored. Ifcount
is zero, the value ifids
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_KHR
state is disabled the GL operates the same as if messages of everysource
,type
orseverity
are disabled.- Parameters:
source
- the source of debug messages to enable or disable. One of:DEBUG_SOURCE_API_KHR
DEBUG_SOURCE_WINDOW_SYSTEM_KHR
DEBUG_SOURCE_SHADER_COMPILER_KHR
DEBUG_SOURCE_THIRD_PARTY_KHR
DEBUG_SOURCE_APPLICATION_KHR
DEBUG_SOURCE_OTHER_KHR
type
- the type of debug messages to enable or disable. One of:DEBUG_TYPE_ERROR_KHR
DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHR
DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHR
DEBUG_TYPE_PORTABILITY_KHR
DEBUG_TYPE_PERFORMANCE_KHR
DEBUG_TYPE_OTHER_KHR
DEBUG_TYPE_MARKER_KHR
severity
- the severity of debug messages to enable or disable. One of:DEBUG_SEVERITY_HIGH_KHR
DEBUG_SEVERITY_MEDIUM_KHR
DEBUG_SEVERITY_LOW_KHR
DEBUG_SEVERITY_NOTIFICATION_KHR
enabled
- whether the selected messages should be enabled or disabled
- If
-
nglDebugMessageInsertKHR
public static void nglDebugMessageInsertKHR(int source, int type, int id, int severity, int length, long message) Unsafe version of:DebugMessageInsertKHR
- Parameters:
length
- the length of the string contained in the character array whose address is given bymessage
-
glDebugMessageInsertKHR
public static void glDebugMessageInsertKHR(int source, int type, int id, int severity, 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.The value of
id
specifies the ID for the message andseverity
indicates its severity level as defined by the caller. The stringbuf
contains the string representation of the message. The parameterlength
contains the number of characters inbuf
. Iflength
is negative, it is implied thatbuf
contains a null terminated string. The errorINVALID_VALUE
will be generated if the number of characters inbuf
, excluding the null terminator whenlength
is negative, is not less than the value ofMAX_DEBUG_MESSAGE_LENGTH_KHR
.If the
DEBUG_OUTPUT_KHR
state is disabled calls to DebugMessageInsert are discarded and do not generate an error.- Parameters:
source
- the source of the debug message to insert. One of:DEBUG_SOURCE_API_KHR
DEBUG_SOURCE_WINDOW_SYSTEM_KHR
DEBUG_SOURCE_SHADER_COMPILER_KHR
DEBUG_SOURCE_THIRD_PARTY_KHR
DEBUG_SOURCE_APPLICATION_KHR
DEBUG_SOURCE_OTHER_KHR
type
- the type of the debug message insert. One of:DEBUG_TYPE_ERROR_KHR
DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHR
DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHR
DEBUG_TYPE_PORTABILITY_KHR
DEBUG_TYPE_PERFORMANCE_KHR
DEBUG_TYPE_OTHER_KHR
DEBUG_TYPE_MARKER_KHR
id
- the user-supplied identifier of the message to insert. One of:DEBUG_SEVERITY_HIGH_KHR
DEBUG_SEVERITY_MEDIUM_KHR
DEBUG_SEVERITY_LOW_KHR
DEBUG_SEVERITY_NOTIFICATION_KHR
severity
- the severity of the debug messages to insertmessage
- a character array containing the message to insert
-
glDebugMessageInsertKHR
public static void glDebugMessageInsertKHR(int source, int type, int id, int severity, 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.The value of
id
specifies the ID for the message andseverity
indicates its severity level as defined by the caller. The stringbuf
contains the string representation of the message. The parameterlength
contains the number of characters inbuf
. Iflength
is negative, it is implied thatbuf
contains a null terminated string. The errorINVALID_VALUE
will be generated if the number of characters inbuf
, excluding the null terminator whenlength
is negative, is not less than the value ofMAX_DEBUG_MESSAGE_LENGTH_KHR
.If the
DEBUG_OUTPUT_KHR
state is disabled calls to DebugMessageInsert are discarded and do not generate an error.- Parameters:
source
- the source of the debug message to insert. One of:DEBUG_SOURCE_API_KHR
DEBUG_SOURCE_WINDOW_SYSTEM_KHR
DEBUG_SOURCE_SHADER_COMPILER_KHR
DEBUG_SOURCE_THIRD_PARTY_KHR
DEBUG_SOURCE_APPLICATION_KHR
DEBUG_SOURCE_OTHER_KHR
type
- the type of the debug message insert. One of:DEBUG_TYPE_ERROR_KHR
DEBUG_TYPE_DEPRECATED_BEHAVIOR_KHR
DEBUG_TYPE_UNDEFINED_BEHAVIOR_KHR
DEBUG_TYPE_PORTABILITY_KHR
DEBUG_TYPE_PERFORMANCE_KHR
DEBUG_TYPE_OTHER_KHR
DEBUG_TYPE_MARKER_KHR
id
- the user-supplied identifier of the message to insert. One of:DEBUG_SEVERITY_HIGH_KHR
DEBUG_SEVERITY_MEDIUM_KHR
DEBUG_SEVERITY_LOW_KHR
DEBUG_SEVERITY_NOTIFICATION_KHR
severity
- the severity of the debug messages to insertmessage
- a character array containing the message to insert
-
nglDebugMessageCallbackKHR
public static void nglDebugMessageCallbackKHR(long callback, long userParam) Unsafe version of:DebugMessageCallbackKHR
-
glDebugMessageCallbackKHR
public static void glDebugMessageCallbackKHR(@Nullable GLDebugMessageKHRCallbackI callback, long userParam) Specifies a callback to receive debugging messages from the GL.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 ofcallback
clears the current callback and disables message output through callbacks. Applications can provide user-specified data through the pointeruserParam
. 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
, andseverity
, respectively. The string representation of the message is stored inmessage
and its length (excluding the null-terminator) is stored inlength
. The parameteruserParam
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_KHR
andDEBUG_CALLBACK_USER_PARAM_KHR
, 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_KHR
state is disabled then the GL will not call the callback function.- Parameters:
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 ofcallback
-
nglGetDebugMessageLogKHR
public static int nglGetDebugMessageLogKHR(int count, int bufsize, long sources, long types, long ids, long severities, long lengths, long messageLog) Unsafe version of:GetDebugMessageLogKHR
- Parameters:
bufsize
- the size of the buffer whose address is given bymessageLog
-
glGetDebugMessageLogKHR
public static int glGetDebugMessageLogKHR(int count, @Nullable IntBuffer sources, @Nullable IntBuffer types, @Nullable IntBuffer ids, @Nullable IntBuffer severities, @Nullable IntBuffer lengths, @Nullable ByteBuffer messageLog) Retrieves messages from the debug message log.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
, andlengths
, respectively. The application is responsible for allocating enough space for each array to hold up tocount
elements. The string representations of all fetched messages are stored in themessageLog
array. If multiple messages are fetched, their strings are concatenated into the samemessageLog
array and will be separated by single null terminators. The last string in the array will also be null-terminated. The maximum size ofmessageLog
, including the space used by all null terminators, is given bybufSize
. IfbufSize
is less than zero andmessageLog
is notNULL
, anINVALID_VALUE
error will be generated. If a message's string, including its null terminator, can not fully fit within themessageLog
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 arraylengths
include the space for the null terminator of each string.Any or all of the arrays
sources
,types
,ids
,severities
,lengths
andmessageLog
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 tocount
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_KHR
, then the GL can opt to never add messages to the message log so GetDebugMessageLog will always return zero.- Parameters:
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 messages
-
nglGetPointervKHR
public static void nglGetPointervKHR(int pname, long params) -
glGetPointervKHR
-
glGetPointerKHR
public static long glGetPointerKHR(int pname) -
nglPushDebugGroupKHR
public static void nglPushDebugGroupKHR(int source, int id, int length, long message) Unsafe version of:PushDebugGroupKHR
- Parameters:
length
- the length of the message to be sent to the debug output stream
-
glPushDebugGroupKHR
Pushes a debug group described by the stringmessage
into the command stream. The value ofid
specifies the ID of messages generated. The parameterlength
contains the number of characters inmessage
. Iflength
is negative, it is implied thatmessage
contains a null terminated string. The message has the specifiedsource
andid
,type
DEBUG_TYPE_PUSH_GROUP_KHR
, andseverity
DEBUG_SEVERITY_NOTIFICATION_KHR
. 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 ofsource
is neitherDEBUG_SOURCE_APPLICATION_KHR
norDEBUG_SOURCE_THIRD_PARTY_KHR
. AnINVALID_VALUE
error is generated iflength
is negative and the number of characters inmessage
, excluding the null-terminator, is not less than the value ofMAX_DEBUG_MESSAGE_LENGTH_KHR
.- Parameters:
source
- the source of the debug message. One of:DEBUG_SOURCE_APPLICATION_KHR
DEBUG_SOURCE_THIRD_PARTY_KHR
id
- the identifier of the messagemessage
- a string containing the message to be sent to the debug output stream
-
glPushDebugGroupKHR
Pushes a debug group described by the stringmessage
into the command stream. The value ofid
specifies the ID of messages generated. The parameterlength
contains the number of characters inmessage
. Iflength
is negative, it is implied thatmessage
contains a null terminated string. The message has the specifiedsource
andid
,type
DEBUG_TYPE_PUSH_GROUP_KHR
, andseverity
DEBUG_SEVERITY_NOTIFICATION_KHR
. 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 ofsource
is neitherDEBUG_SOURCE_APPLICATION_KHR
norDEBUG_SOURCE_THIRD_PARTY_KHR
. AnINVALID_VALUE
error is generated iflength
is negative and the number of characters inmessage
, excluding the null-terminator, is not less than the value ofMAX_DEBUG_MESSAGE_LENGTH_KHR
.- Parameters:
source
- the source of the debug message. One of:DEBUG_SOURCE_APPLICATION_KHR
DEBUG_SOURCE_THIRD_PARTY_KHR
id
- the identifier of the messagemessage
- a string containing the message to be sent to the debug output stream
-
glPopDebugGroupKHR
public static void glPopDebugGroupKHR()Pops the active debug group. When a debug group is popped, the GL will also generate a debug output message describing its cause based on themessage
string, the sourcesource
, and an IDid
submitted to the associatedPushDebugGroupKHR
command.DEBUG_TYPE_PUSH_GROUP_KHR
andDEBUG_TYPE_POP_GROUP_KHR
share a single namespace for messageid
.severity
has the valueDEBUG_SEVERITY_NOTIFICATION_KHR
. Thetype
has the valueDEBUG_TYPE_POP_GROUP_KHR
. 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_KHR
error; pushing a debug group onto a stack containingMAX_DEBUG_GROUP_STACK_DEPTH_KHR
minus one elements will generate aSTACK_OVERFLOW_KHR
error. -
nglObjectLabelKHR
public static void nglObjectLabelKHR(int identifier, int name, int length, long label) Unsafe version of:ObjectLabelKHR
- Parameters:
length
- the length of the label to be used for the object
-
glObjectLabelKHR
Labels a named object identified within a namespace.- Parameters:
identifier
- the namespace from which the name of the object is allocated. One of:BUFFER_KHR
SHADER_KHR
PROGRAM_KHR
QUERY_KHR
PROGRAM_PIPELINE_KHR
SAMPLER_KHR
TEXTURE
RENDERBUFFER
FRAMEBUFFER
TRANSFORM_FEEDBACK
name
- the name of the object to labellabel
- a string containing the label to assign to the object
-
glObjectLabelKHR
Labels a named object identified within a namespace.- Parameters:
identifier
- the namespace from which the name of the object is allocated. One of:BUFFER_KHR
SHADER_KHR
PROGRAM_KHR
QUERY_KHR
PROGRAM_PIPELINE_KHR
SAMPLER_KHR
TEXTURE
RENDERBUFFER
FRAMEBUFFER
TRANSFORM_FEEDBACK
name
- the name of the object to labellabel
- a string containing the label to assign to the object
-
nglGetObjectLabelKHR
public static void nglGetObjectLabelKHR(int identifier, int name, int bufSize, long length, long label) Unsafe version of:GetObjectLabelKHR
- Parameters:
bufSize
- the length of the buffer whose address is inlabel
-
glGetObjectLabelKHR
public static void glGetObjectLabelKHR(int identifier, int name, @Nullable IntBuffer length, ByteBuffer label) Retrieves the label of a named object identified within a namespace.- Parameters:
identifier
- the namespace from which the name of the object is allocated. One of:BUFFER_KHR
SHADER_KHR
PROGRAM_KHR
QUERY_KHR
PROGRAM_PIPELINE_KHR
SAMPLER_KHR
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 label
-
glGetObjectLabelKHR
Retrieves the label of a named object identified within a namespace.- Parameters:
identifier
- the namespace from which the name of the object is allocated. One of:BUFFER_KHR
SHADER_KHR
PROGRAM_KHR
QUERY_KHR
PROGRAM_PIPELINE_KHR
SAMPLER_KHR
TEXTURE
RENDERBUFFER
FRAMEBUFFER
TRANSFORM_FEEDBACK
name
- the name of the object whose label to retrievebufSize
- the length of the buffer whose address is inlabel
-
glGetObjectLabelKHR
Retrieves the label of a named object identified within a namespace.- Parameters:
identifier
- the namespace from which the name of the object is allocated. One of:BUFFER_KHR
SHADER_KHR
PROGRAM_KHR
QUERY_KHR
PROGRAM_PIPELINE_KHR
SAMPLER_KHR
TEXTURE
RENDERBUFFER
FRAMEBUFFER
TRANSFORM_FEEDBACK
name
- the name of the object whose label to retrieve
-
nglObjectPtrLabelKHR
public static void nglObjectPtrLabelKHR(long ptr, int length, long label) Unsafe version of:ObjectPtrLabelKHR
- Parameters:
length
- the length of the label to be used for the object
-
glObjectPtrLabelKHR
Labels a sync object identified by a pointer.- Parameters:
ptr
- a pointer identifying a sync objectlabel
- a string containing the label to assign to the object
-
glObjectPtrLabelKHR
Labels a sync object identified by a pointer.- Parameters:
ptr
- a pointer identifying a sync objectlabel
- a string containing the label to assign to the object
-
nglGetObjectPtrLabelKHR
public static void nglGetObjectPtrLabelKHR(long ptr, int bufSize, long length, long label) Unsafe version of:GetObjectPtrLabelKHR
- Parameters:
bufSize
- the length of the buffer whose address is inlabel
-
glGetObjectPtrLabelKHR
Retrieves the label of a sync object identified by a pointer.- Parameters:
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 label
-
glGetObjectPtrLabelKHR
Retrieves the label of a sync object identified by a pointer.- Parameters:
ptr
- the name of the sync object whose label to retrievebufSize
- the length of the buffer whose address is inlabel
-
glGetObjectPtrLabelKHR
Retrieves the label of a sync object identified by a pointer.- Parameters:
ptr
- the name of the sync object whose label to retrieve
-
glDebugMessageControlKHR
public static void glDebugMessageControlKHR(int source, int type, int severity, @Nullable int[] ids, boolean enabled) Array version of:DebugMessageControlKHR
-
glGetDebugMessageLogKHR
public static int glGetDebugMessageLogKHR(int count, @Nullable int[] sources, @Nullable int[] types, @Nullable int[] ids, @Nullable int[] severities, @Nullable int[] lengths, @Nullable ByteBuffer messageLog) Array version of:GetDebugMessageLogKHR
-
glGetObjectLabelKHR
public static void glGetObjectLabelKHR(int identifier, int name, @Nullable int[] length, ByteBuffer label) Array version of:GetObjectLabelKHR
-
glGetObjectPtrLabelKHR
Array version of:GetObjectPtrLabelKHR
-