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 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 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 parameter is NULL, then no messages are sent to the callback function and the debug message generation is disabled. If the 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 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 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 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 clears the current callback and disables message output. The callback will receive the following in its parameters: will contain an EGL error code, or EGL_SUCCESS, as applicable. will contain a pointer to a string. Example "eglBindApi". will contain one of the debug message types listed in table 13.1. will contain the label attached to the current thread. The will be NULL if not set by the application. If the message is from an internal thread, the label will be NULL. 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 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. 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 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 is read-only, owned and managed by EGL, and should only be considered valid for the duration of the function call. Likewise the 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 , , and identify the object to be labeled. The