| 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 |
| |
| 1. 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. |
| |
| 2. 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. |