KHR_debug
Name
KHR_debug
Name Strings
EGL_KHR_debug
Contributors
Jeff Vigil, Qualcomm
Brian Ellis, Qualcomm
(Original contributors of Gl_KHR_debug extension for OpenGL/GL_ES)
Mark Callow, HI
John Leech, Khronos
Ray Smith, ARM
Prabindh Sundareson, Texas Instruments
James Jones, NVIDIA
Jesse Hall, Google
Contact
Jeff Vigil (jvigil 'at' qualcomm.com)
Notice
Copyright (c) 2012-2015 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Approved by the EGL Working Group on 2015/04/24.
Approved by the Khronos Board of Promoters on 2015/06/26.
Version
Version 18, Modified Date: September 28, 2016
Number
EGL Extension #92
Extension Type
EGL client extension
Dependencies
Applicable to any version of EGL 1.x, but written in relationship
to EGL 1.5.
Overview
This extension allows EGL to notify applications when various events
occur that may be useful during application development and debugging.
These events are represented in the form of debug messages with a
human-readable string representation. Examples of debug events include
errors due to incorrect use of the EGL API, warnings of undefined behavior,
and performance warnings.
The "type" of the message roughly identifies the nature of the event that
caused the message. Examples include input errors, performance
information, or warnings about undefined behavior.
Messages are communicated to the application through an application-
defined callback function that is called by the EGL implementation on
each debug message. The motivation for the callback routine is to free
application developers from actively having to query whether an EGL error,
or any other debuggable event has happened after each call to a EGL
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. The callback also offers much more information
than just an error code.
To control the volume of debug output, types of messages can be enabled or
disabled. The mechanism is controlled by attributes passed to EGL. The
state of the message type control can be queried.
Debug output can be enabled and disabled by changing the callback function.
NULL will disable the feature while a valid function pointer will enable
it.
Finally, this extension defines a mechanism for EGL applications to
label their objects (contexts, surfaces, syncs, etc.) with a pointer
to an application provided structure. This pointer can be a descriptive
string, identifier or pointer to a structure. This enables the application
to associate the EGL object with application information. EGL will not
interpret this pointer as a string or any other meaning - just attach to
the object and pass back in the callback when that object is the primary
object of an event.
IP Status
No known IP claims.
New Procedures and Functions
EGLint eglDebugMessageControlKHR(
EGLDEBUGPROCKHR callback,
const EGLAttrib* attrib_list);
EGLBoolean eglQueryDebugKHR(
EGLint attribute,
EGLAttrib* value);
EGLInt eglLabelObjectKHR(
EGLDisplay display,
EGLenum objectType,
EGLObjectKHR object,
EGLLabelKHR label);
New Types
A general type to identify EGL objects, such as EGLSurface or EGLContext.
typedef void* EGLObjectKHR;
A label is a string, ID or pointer to a structure that the application
can attach to an EGL object.
typedef void* EGLLabelKHR;
The callback function that applications can define, and is accepted by
eglDebugMessageControlKHR, is defined as:
typedef void (APIENTRY *EGLDEBUGPROCKHR)(
EGLenum error,
const char *command,
EGLint messageType,
EGLLabelKHR threadLabel,
EGLLabelKHR objectLabel,
const char* message);
New Tokens
Tokens accepted by the <objectType> parameter of function
eglLabelObjectKHR:
EGL_OBJECT_THREAD_KHR 0x33B0
EGL_OBJECT_DISPLAY_KHR 0x33B1
EGL_OBJECT_CONTEXT_KHR 0x33B2
EGL_OBJECT_SURFACE_KHR 0x33B3
EGL_OBJECT_IMAGE_KHR 0x33B4
EGL_OBJECT_SYNC_KHR 0x33B5
EGL_OBJECT_STREAM_KHR 0x33B6
Tokens provided by the <messageType> parameter of EGLDEBUGPROCKHR
or the attributes input to eglControlDebugMessageKHR or attribute
of eglQueryDebugKHR:
EGL_DEBUG_MSG_CRITICAL_KHR 0x33B9
EGL_DEBUG_MSG_ERROR_KHR 0x33BA
EGL_DEBUG_MSG_WARN_KHR 0x33BB
EGL_DEBUG_MSG_INFO_KHR 0x33BC
Tokens provided by the input attribute to eglQueryDebugKHR:
EGL_DEBUG_CALLBACK_KHR 0x33B8
Additions to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors)
Add new Section 3.13:
"3.13 - Debug Output
Application developers can obtain more information from EGL runtime in
the form of debug output. This information can include details about EGL
errors, undefined behavior, implementation-dependent performance warnings,
or other useful hints.
This information is communicated through a stream of debug messages that
are generated as EGL commands are executed. The application can
receive these messages through a callback routine.
Controls are provided for disabling classes of messages that the
application does not care about.
Debug output functionality is controlled with:
EGLint eglDebugMessageControlKHR(
EGLDEBUGPROCKHR callback,
const EGLAttrib* attrib_list);
If the <callback> parameter is NULL, then no messages are sent to the
callback function and the debug message generation is disabled. If the
<callback> parameter is a pointer to a valid callback function, as defined
by EGLDEBUGPROCKHR, then messages will be sent to that callback function.
The attribute list <attrib_list> contains a set of message type enums,
and each has a value of EGL_TRUE to enable that class of messages,
or value EGL_FALSE to disable that class of message.
If the <attrib_list> contains an unknown attribute or value the function
will return a EGL_BAD_ATTRIBUTE error.
If there is no error, then the function will set the updated callback,
set the updated message types and return EGL_SUCCESS.
The messages types, their purpose and initial states are given in
table 13.1 below. The parameter <attrib_list> needs only contain the
attributes to change; an application can call eglDebugMessageControl more
than once with a valid callback, and change the message type states as
desired.
When the callback is set to NULL; the attributes are reset to their
default values.
Debug Output Message Type Informs about Initial/Default state
------------------------- ------------- ---------------------
EGL_DEBUG_MSG_CRITICAL_KHR Internal EGL driver failures ENABLED
i.e. EGL_BAD_ALLOC,
EGL_CONTEXT_LOST
EGL_DEBUG_MSG_ERROR_KHR Input and bad match errors ENABLED
i.e. EGL_BAD_CONTEXT,
EGL_BAD_PARAMETER...
EGL_DEBUG_MSG_WARN_KHR Warnings, code is EGL_SUCCESS, DISABLED
but message indicates
deprecated or inefficient
operation.
EGL_DEBUG_MSG_INFO_KHR Verbose operation DISABLED
Messages such as object
creation and destruction
or change in state.
---------------------------------------------------------------------------
Table 13.1: Types of debug output messages. Each debug message is associated
with one of these types that describes the nature or class of the message.
3.13.1 - Debug Message Callback
Applications must provide a callback function for receiving debug messages
of the following type:
typedef void (APIENTRY *EGLDEBUGPROCKHR)(
EGLenum error,
const char *command,
EGLint messageType,
EGLLabelKHR threadLabel,
EGLLabelKHR objectLabel,
const char* message);
The function's prototype must follow the type definition of EGLDEBUGPROCKHR.
Only one debug callback can be in-use for the application, and
further calls overwrite the previous callback. Specifying NULL as the
value of <callback> clears the current callback and disables message
output.
The callback will receive the following in its parameters:
<error> will contain an EGL error code, or EGL_SUCCESS, as applicable.
<command> will contain a pointer to a string. Example "eglBindApi".
<messageType> will contain one of the debug message types listed in
table 13.1.
<threadLabel> will contain the label attached to the current thread.
The <threadLabel> will be NULL if not set by the application. If the
message is from an internal thread, the label will be NULL.
<objectLabel> will contain the label attached to the primary object
of the message; Labels will be NULL if not set by the application.
The primary object should be the object the function operates on, see
table 13.2 which provides the recommended mapping between functions and
their primary object. This <objectLabel> may be NULL even though the
application labeled the object. This is because it is possible an error
was raised while executing the command before the primary object was
validated, therefore its label cannot be included in the callback.
<message> will contain a platform specific debug string message;
This string should provide added information to the application
developer regarding the condition that generated the message.
The format of a message is implementation-defined, although it should
represent a concise description of the event that caused the message
to be generated. Message strings can be NULL and should not be assumed
otherwise.
EGL Command Primary object
------------------------- -------------
eglBindAPI thread
eglBindTexImage surface
eglChooseConfig display
eglClientWaitSync sync
eglCopyBuffers surface
eglCreateContext display
eglCreateImage display
eglCreatePbufferFromClientBuffer display
eglCreatePbufferSurface display
eglCreatePixmapSurface display
eglCreatePlatformWindowSurface display
eglCreatePlatformPixmapSurface display
eglCreateSync display
eglCreateWindowSurface display
eglDestroyContext context
eglDestroyImage image
eglDestroySurface surface
eglDestroySync sync
eglGetConfigAttrib display
eglGetConfigs display
eglGetCurrentContext context
eglGetCurrentDisplay display
eglGetCurrentSurface surface
eglGetDisplay thread
eglGetError thread
eglGetPlatformDisplay thread
eglGetSyncAttrib sync
eglInitialize display
eglMakeCurrent context
eglQueryAPI context
eglQueryContext context
eglQueryString display
eglQuerySurface surface
eglReleaseTexImage surface
eglReleaseThread thread
eglSurfaceAttrib surface
eglSwapBuffers surface
eglSwapInterval surface
eglTerminate display
eglWaitClient context
eglWaitGL context
eglWaitNative thread
eglWaitSync sync
eglDebugMessageControlKHR -none-
eglQueryDebugKHR -none-
eglLabelObjectKHR labeled object
---------------------------------------------------------------------------
Table 13.2: Recommendation of primary object in a callback as result
of various EGL commands.
If the application has specified a <callback> function for receiving debug
output, the implementation will call that function whenever any enabled
message is generated. A message must be posted for every error since
debug messages can be used as an alternative to eglGetError() for error
detection and handling. Specifying a callback function does not affect the
behavior of eglGetError; errors are reported through both mechanisms.
Applications that specify a callback function must be aware of certain
special conditions when executing code inside a callback when it is
called by EGL. The memory for <message> is read-only, owned and managed
by EGL, and should only be considered valid for the duration of the
function call. Likewise the <command> string is read-only EGL managed
memory and should be considered valid only for the duration of the
callback.
Setting the label for EGL objects is optional and only intended for
applications to correlate application structures with EGL objects.
All object labels are initially NULL.
The behavior of calling any EGL operation, its client APIs, or window system
functions from within the callback function is undefined and may lead
to program termination. It should not be considered reentrant.
Only one debug callback may be registered at a time; registering a new
callback will replace the previous callback. The callback is used by any
thread that calls EGL, so if the application calls into EGL concurrently
from multiple threads it must ensure the callback is thread-safe.
EGL may employ internal threads to execute EGL commands. These threads can
post debug messages to the callback function. The labels for these
internal threads will be NULL.
3.13.2 Debug Labels:
Debug labels provide a method for annotating any object (context, surface,
sync, etc.) with an application provided label. These labels may then be
used by the debug output or an external tool such as a debugger or profiler
to describe labeled objects.
The command
EGLint eglLabelObjectKHR(
EGLDisplay display,
EGLenum objectType,
EGLObjectKHR object,
EGLLabelKHR label);
enables the application to attach a label to a specified object.
The <display>, <objectType>, and <object> identify the object to be
labeled.
The <label> contains a pointer sized variable to attach to the
object. This label can be a integer identifier, string or pointer to a
application defined structure. EGL will not interpret this value;
it will merely provide it when the object is involved in a callback
message. The label for any object will initially be NULL until set by
the application.
An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <objectType>
doesn't match one of the object type enums. An EGL_BAD_PARAMETER is also
returned if the <objectType> is not a supported type; such as no support
for streams.
An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <object> is
invalid, unknown, NULL, or is not an object created with
EGLDisplay <display>.
When the <objectType> is EGL_OBJECT_THREAD_KHR, the <object> parameter
will be ignored by EGL. The thread is implicitly the active thread. It is
recommended that the application pass a NULL for the <object> parameter in
this case.
When the <objectType> is EGL_OBJECT_DISPLAY_KHR, the <object> parameter
must be the same as the <display> parameter - the Display to label. If
these do not match, in this case, a EGL_BAD_PARAMETER is generated.
The <display> does not need to be initialized for <objectType>
EGL_OBJECT_THREAD_KHR, or EGL_OBJECT_DISPLAY_KHR; However for all other
types it must be initialized in order to validate the <object> for
attaching a label.
If there is no error, then the function will set the label and return
EGL_SUCCESS.
3.13.3 Debug Queries:
The command
EGLBoolean eglQueryDebugKHR(
EGLint attribute,
EGLAttrib* value);
enables the application to query the current value for the debug
attributes. On success the function returns EGL_TRUE.
If <attribute> is a message type enum, the value returned will
be either EGL_TRUE or EGL_FALSE to indicate whether the specified types of
messages are enabled or disabled respectively.
Querying for attribute EGL_DEBUG_CALLBACK_KHR will return the current
callback pointer. This feature is intended to enable layering of the
callback with helper libraries.
Querying for an unknown attribute will result in an EGL_BAD_ATTRIBUTE error
and a return of EGL_FALSE.
Usage Examples
This example shows starting debug messaging and attaching string labels to
newly created objects.
void MyCallBack(EGLenum error,
const char *command,
EGLint messageType,
EGLLabelKHR threadLabel,
EGLLabelKHR objectLabel,
const char* message)
{
printf("Error: %x, With command %s, Type: %d,"
"Thread: %s, Object: %s, Message: %s.",
error, command, messageType, threadLabel, objectLabel, message);
}
EGLint result;
// DEBUG_MSG_ERROR and CRITICAL are enabled by default
EGLAttrib debugAttribs = {EGL_DEBUG_MSG_WARN_KHR, EGL_TRUE, EGL_NONE};
// Start up debug messaging:
result = eglDebugMessageControl(MyCallBack, debugAttribs);
// Label for the rendering thread.
EGLLabelKHR renderThreadLabel = (EGLLabelKHR)"Render thread";
result = eglLabelObject(NULL, EGL_OBJECT_THREAD_KHR, NULL, renderThreadLabel);
EGLDisplay dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY);
EGLLabelKHR myDisplay = (EGLLabelKHR)"Default display";
result = eglLabelObject(dpy, EGL_OBJECT_DISPLAY_KHR, dpy, myDisplay);
eglInitialize(dpy);
EGLLabelKHR renderContextLabel = (EGLLabelKHR)"Render context";
EGLContext ctx = eglCreateContext(dpy, config, NULL, contextAttribs);
result = eglLabelObject(dpy, EGL_OBJECT_CONTEXT_KHR, ctx, renderContextLabel);
Issues
-
Why not use GL_KHR_debug?
RESOLVED: Most EGL use and object creation happens before creating a GL context. And since EGL operations are thread related - the debug messages should be too.
-
Is the callback expected only to be called from the thread which it's registered?
RESOLVED: In most cases when an application thread calls an EGL function, it is expected that EGL upon detecting an error will callback using that application thread. However, EGL may have internal helper threads that execute operations. These threads can callback but will have no threadLabel. It is the responsibility of EGL to ensure that if these threads are blocked in the application's callback by a breakpoint; that EGL does not fail. Internal threads are an implementation detail and are not required.
Revision History
Revision 18, 2016-07-28 (Jeff Vigil)
- Clarify return values/error codes.
Revision 17, 2015-09-23 (Jeff Vigil)
- Correct type name to "EGLDEBUGPROCKHR". Updated example code.
Revision 16, 2015-04-15 (Jeff Vigil)
- Clarified that <objectLabel> maybe NULL in the callback, if an error
is raised before the primary object handle is validated.
Revision 15, 2015-03-30 (Jeff Vigil)
- Further details to labeling of EGL_OBJECT_DISPLAY_KHR.
Revision 14, 2015-03-27 (Jeff Vigil)
- Further clarification of returns and errors. Add further details to
labeling of EGL_OBJECT_THREAD_KHR and EGL_OBJECT_DISPLAY_KHR.
Revision 13, 2015-03-26 (Jeff Vigil)
- Clarified returns and errors.
Revision 12, 2015-03-24 (Jeff Vigil)
- Improve readability. Add assigned enum values.
Revision 11, 2015-03-02 (Jeff Vigil)
- Clarify text regarding parameter attribute_list and its persistence.
Revision 10, 2015-02-25 (Jeff Vigil)
- Clarify text regarding callback blocking.
- The implementation must provide errors and success in callbacks so
that the callback replaces the use of eglGetError.
- <command> strings are read-only EGL memory.
- Specify default values for attributes.
- Fix typos.
Revision 9, 2015-02-03 (Jeff Vigil)
- Updated contributors.
- Add extension type.
- Add "KHR" to token and function names.
- Fix typos.
- Add query to get current callback pointer.
Revision 8, 2014-12-03 (Jeff Vigil)
- Add table containing recommendation for primary object in the callback.
Revision 7, 2014-10-21 (Jeff Vigil)
- Remove configs as a label-able object.
- Remove redundant text.
- Simplify to one callback per process, not per thread.
Revision 6, 2014-10-17 (Jeff Vigil)
- Add issues.
- Address internal EGL threads posting messages.
Revision 5, 2014-05-27 (Jeff Vigil)
- Add missing text for eglQueryDebug.
- Clarify threading model.
Revision 4, 2014-04-14 (Jeff Vigil)
- Fix due to feedback from EGL WG face-to-face conference.
Revision 3, 2014-04-10 (Jeff Vigil)
- Refinements.
Revision 2, 2014-02-21 (Jeff Vigil)
- Simplify API.
Revision 1, 2013-09-08 (Jeff Vigil)
- Work in progress for F2F, Based on GL_KHR_debug, replace GL with EGL
and remove GL spec specific text.