1Name 2 3 KHR_debug 4 5Name Strings 6 7 EGL_KHR_debug 8 9Contributors 10 11 Jeff Vigil, Qualcomm 12 Brian Ellis, Qualcomm 13 (Original contributors of Gl_KHR_debug extension for OpenGL/GL_ES) 14 Mark Callow, HI 15 John Leech, Khronos 16 Ray Smith, ARM 17 Prabindh Sundareson, Texas Instruments 18 James Jones, NVIDIA 19 Jesse Hall, Google 20 21Contact 22 23 Jeff Vigil (jvigil 'at' qualcomm.com) 24 25Notice 26 27 Copyright (c) 2012-2015 The Khronos Group Inc. Copyright terms at 28 http://www.khronos.org/registry/speccopyright.html 29 30Status 31 32 Complete. Approved by the EGL Working Group on 2015/04/24. 33 Approved by the Khronos Board of Promoters on 2015/06/26. 34 35Version 36 37 Version 18, Modified Date: September 28, 2016 38 39Number 40 41 EGL Extension #92 42 43Extension Type 44 45 EGL client extension 46 47Dependencies 48 49 Applicable to any version of EGL 1.x, but written in relationship 50 to EGL 1.5. 51 52Overview 53 54 This extension allows EGL to notify applications when various events 55 occur that may be useful during application development and debugging. 56 57 These events are represented in the form of debug messages with a 58 human-readable string representation. Examples of debug events include 59 errors due to incorrect use of the EGL API, warnings of undefined behavior, 60 and performance warnings. 61 62 The "type" of the message roughly identifies the nature of the event that 63 caused the message. Examples include input errors, performance 64 information, or warnings about undefined behavior. 65 66 Messages are communicated to the application through an application- 67 defined callback function that is called by the EGL implementation on 68 each debug message. The motivation for the callback routine is to free 69 application developers from actively having to query whether an EGL error, 70 or any other debuggable event has happened after each call to a EGL 71 function. With a callback, developers can keep their code free of debug 72 checks, set breakpoints in the callback function, and only have to react 73 to messages as they occur. The callback also offers much more information 74 than just an error code. 75 76 To control the volume of debug output, types of messages can be enabled or 77 disabled. The mechanism is controlled by attributes passed to EGL. The 78 state of the message type control can be queried. 79 80 Debug output can be enabled and disabled by changing the callback function. 81 NULL will disable the feature while a valid function pointer will enable 82 it. 83 84 Finally, this extension defines a mechanism for EGL applications to 85 label their objects (contexts, surfaces, syncs, etc.) with a pointer 86 to an application provided structure. This pointer can be a descriptive 87 string, identifier or pointer to a structure. This enables the application 88 to associate the EGL object with application information. EGL will not 89 interpret this pointer as a string or any other meaning - just attach to 90 the object and pass back in the callback when that object is the primary 91 object of an event. 92 93IP Status 94 95 No known IP claims. 96 97New Procedures and Functions 98 99 EGLint eglDebugMessageControlKHR( 100 EGLDEBUGPROCKHR callback, 101 const EGLAttrib* attrib_list); 102 103 EGLBoolean eglQueryDebugKHR( 104 EGLint attribute, 105 EGLAttrib* value); 106 107 EGLInt eglLabelObjectKHR( 108 EGLDisplay display, 109 EGLenum objectType, 110 EGLObjectKHR object, 111 EGLLabelKHR label); 112 113New Types 114 115 A general type to identify EGL objects, such as EGLSurface or EGLContext. 116 117 typedef void* EGLObjectKHR; 118 119 A label is a string, ID or pointer to a structure that the application 120 can attach to an EGL object. 121 122 typedef void* EGLLabelKHR; 123 124 The callback function that applications can define, and is accepted by 125 eglDebugMessageControlKHR, is defined as: 126 127 typedef void (APIENTRY *EGLDEBUGPROCKHR)( 128 EGLenum error, 129 const char *command, 130 EGLint messageType, 131 EGLLabelKHR threadLabel, 132 EGLLabelKHR objectLabel, 133 const char* message); 134 135New Tokens 136 137 Tokens accepted by the <objectType> parameter of function 138 eglLabelObjectKHR: 139 140 EGL_OBJECT_THREAD_KHR 0x33B0 141 EGL_OBJECT_DISPLAY_KHR 0x33B1 142 EGL_OBJECT_CONTEXT_KHR 0x33B2 143 EGL_OBJECT_SURFACE_KHR 0x33B3 144 EGL_OBJECT_IMAGE_KHR 0x33B4 145 EGL_OBJECT_SYNC_KHR 0x33B5 146 EGL_OBJECT_STREAM_KHR 0x33B6 147 148 Tokens provided by the <messageType> parameter of EGLDEBUGPROCKHR 149 or the attributes input to eglControlDebugMessageKHR or attribute 150 of eglQueryDebugKHR: 151 152 EGL_DEBUG_MSG_CRITICAL_KHR 0x33B9 153 EGL_DEBUG_MSG_ERROR_KHR 0x33BA 154 EGL_DEBUG_MSG_WARN_KHR 0x33BB 155 EGL_DEBUG_MSG_INFO_KHR 0x33BC 156 157 Tokens provided by the input attribute to eglQueryDebugKHR: 158 159 EGL_DEBUG_CALLBACK_KHR 0x33B8 160 161Additions to Chapter 3 of the EGL 1.5 Specification 162(EGL Functions and Errors) 163 164 Add new Section 3.13: 165 166 "3.13 - Debug Output 167 168 Application developers can obtain more information from EGL runtime in 169 the form of debug output. This information can include details about EGL 170 errors, undefined behavior, implementation-dependent performance warnings, 171 or other useful hints. 172 173 This information is communicated through a stream of debug messages that 174 are generated as EGL commands are executed. The application can 175 receive these messages through a callback routine. 176 177 Controls are provided for disabling classes of messages that the 178 application does not care about. 179 180 Debug output functionality is controlled with: 181 182 EGLint eglDebugMessageControlKHR( 183 EGLDEBUGPROCKHR callback, 184 const EGLAttrib* attrib_list); 185 186 If the <callback> parameter is NULL, then no messages are sent to the 187 callback function and the debug message generation is disabled. If the 188 <callback> parameter is a pointer to a valid callback function, as defined 189 by EGLDEBUGPROCKHR, then messages will be sent to that callback function. 190 191 The attribute list <attrib_list> contains a set of message type enums, 192 and each has a value of EGL_TRUE to enable that class of messages, 193 or value EGL_FALSE to disable that class of message. 194 195 If the <attrib_list> contains an unknown attribute or value the function 196 will return a EGL_BAD_ATTRIBUTE error. 197 198 If there is no error, then the function will set the updated callback, 199 set the updated message types and return EGL_SUCCESS. 200 201 The messages types, their purpose and initial states are given in 202 table 13.1 below. The parameter <attrib_list> needs only contain the 203 attributes to change; an application can call eglDebugMessageControl more 204 than once with a valid callback, and change the message type states as 205 desired. 206 207 When the callback is set to NULL; the attributes are reset to their 208 default values. 209 210 Debug Output Message Type Informs about Initial/Default state 211 ------------------------- ------------- --------------------- 212 EGL_DEBUG_MSG_CRITICAL_KHR Internal EGL driver failures ENABLED 213 i.e. EGL_BAD_ALLOC, 214 EGL_CONTEXT_LOST 215 216 EGL_DEBUG_MSG_ERROR_KHR Input and bad match errors ENABLED 217 i.e. EGL_BAD_CONTEXT, 218 EGL_BAD_PARAMETER... 219 220 EGL_DEBUG_MSG_WARN_KHR Warnings, code is EGL_SUCCESS, DISABLED 221 but message indicates 222 deprecated or inefficient 223 operation. 224 225 EGL_DEBUG_MSG_INFO_KHR Verbose operation DISABLED 226 Messages such as object 227 creation and destruction 228 or change in state. 229 230 --------------------------------------------------------------------------- 231 Table 13.1: Types of debug output messages. Each debug message is associated 232 with one of these types that describes the nature or class of the message. 233 234 3.13.1 - Debug Message Callback 235 236 Applications must provide a callback function for receiving debug messages 237 of the following type: 238 239 typedef void (APIENTRY *EGLDEBUGPROCKHR)( 240 EGLenum error, 241 const char *command, 242 EGLint messageType, 243 EGLLabelKHR threadLabel, 244 EGLLabelKHR objectLabel, 245 const char* message); 246 247 The function's prototype must follow the type definition of EGLDEBUGPROCKHR. 248 Only one debug callback can be in-use for the application, and 249 further calls overwrite the previous callback. Specifying NULL as the 250 value of <callback> clears the current callback and disables message 251 output. 252 253 The callback will receive the following in its parameters: 254 255 <error> will contain an EGL error code, or EGL_SUCCESS, as applicable. 256 257 <command> will contain a pointer to a string. Example "eglBindApi". 258 259 <messageType> will contain one of the debug message types listed in 260 table 13.1. 261 262 <threadLabel> will contain the label attached to the current thread. 263 The <threadLabel> will be NULL if not set by the application. If the 264 message is from an internal thread, the label will be NULL. 265 266 <objectLabel> will contain the label attached to the primary object 267 of the message; Labels will be NULL if not set by the application. 268 The primary object should be the object the function operates on, see 269 table 13.2 which provides the recommended mapping between functions and 270 their primary object. This <objectLabel> may be NULL even though the 271 application labeled the object. This is because it is possible an error 272 was raised while executing the command before the primary object was 273 validated, therefore its label cannot be included in the callback. 274 275 <message> will contain a platform specific debug string message; 276 This string should provide added information to the application 277 developer regarding the condition that generated the message. 278 The format of a message is implementation-defined, although it should 279 represent a concise description of the event that caused the message 280 to be generated. Message strings can be NULL and should not be assumed 281 otherwise. 282 283 EGL Command Primary object 284 ------------------------- ------------- 285 286 eglBindAPI thread 287 eglBindTexImage surface 288 eglChooseConfig display 289 eglClientWaitSync sync 290 eglCopyBuffers surface 291 eglCreateContext display 292 eglCreateImage display 293 eglCreatePbufferFromClientBuffer display 294 eglCreatePbufferSurface display 295 eglCreatePixmapSurface display 296 eglCreatePlatformWindowSurface display 297 eglCreatePlatformPixmapSurface display 298 eglCreateSync display 299 eglCreateWindowSurface display 300 eglDestroyContext context 301 eglDestroyImage image 302 eglDestroySurface surface 303 eglDestroySync sync 304 eglGetConfigAttrib display 305 eglGetConfigs display 306 eglGetCurrentContext context 307 eglGetCurrentDisplay display 308 eglGetCurrentSurface surface 309 eglGetDisplay thread 310 eglGetError thread 311 eglGetPlatformDisplay thread 312 eglGetSyncAttrib sync 313 eglInitialize display 314 eglMakeCurrent context 315 eglQueryAPI context 316 eglQueryContext context 317 eglQueryString display 318 eglQuerySurface surface 319 eglReleaseTexImage surface 320 eglReleaseThread thread 321 eglSurfaceAttrib surface 322 eglSwapBuffers surface 323 eglSwapInterval surface 324 eglTerminate display 325 eglWaitClient context 326 eglWaitGL context 327 eglWaitNative thread 328 eglWaitSync sync 329 eglDebugMessageControlKHR -none- 330 eglQueryDebugKHR -none- 331 eglLabelObjectKHR labeled object 332 333 --------------------------------------------------------------------------- 334 Table 13.2: Recommendation of primary object in a callback as result 335 of various EGL commands. 336 337 If the application has specified a <callback> function for receiving debug 338 output, the implementation will call that function whenever any enabled 339 message is generated. A message must be posted for every error since 340 debug messages can be used as an alternative to eglGetError() for error 341 detection and handling. Specifying a callback function does not affect the 342 behavior of eglGetError; errors are reported through both mechanisms. 343 344 Applications that specify a callback function must be aware of certain 345 special conditions when executing code inside a callback when it is 346 called by EGL. The memory for <message> is read-only, owned and managed 347 by EGL, and should only be considered valid for the duration of the 348 function call. Likewise the <command> string is read-only EGL managed 349 memory and should be considered valid only for the duration of the 350 callback. 351 352 Setting the label for EGL objects is optional and only intended for 353 applications to correlate application structures with EGL objects. 354 All object labels are initially NULL. 355 356 The behavior of calling any EGL operation, its client APIs, or window system 357 functions from within the callback function is undefined and may lead 358 to program termination. It should not be considered reentrant. 359 360 Only one debug callback may be registered at a time; registering a new 361 callback will replace the previous callback. The callback is used by any 362 thread that calls EGL, so if the application calls into EGL concurrently 363 from multiple threads it must ensure the callback is thread-safe. 364 365 EGL may employ internal threads to execute EGL commands. These threads can 366 post debug messages to the callback function. The labels for these 367 internal threads will be NULL. 368 369 3.13.2 Debug Labels: 370 371 Debug labels provide a method for annotating any object (context, surface, 372 sync, etc.) with an application provided label. These labels may then be 373 used by the debug output or an external tool such as a debugger or profiler 374 to describe labeled objects. 375 376 The command 377 378 EGLint eglLabelObjectKHR( 379 EGLDisplay display, 380 EGLenum objectType, 381 EGLObjectKHR object, 382 EGLLabelKHR label); 383 384 enables the application to attach a label to a specified object. 385 The <display>, <objectType>, and <object> identify the object to be 386 labeled. 387 388 The <label> contains a pointer sized variable to attach to the 389 object. This label can be a integer identifier, string or pointer to a 390 application defined structure. EGL will not interpret this value; 391 it will merely provide it when the object is involved in a callback 392 message. The label for any object will initially be NULL until set by 393 the application. 394 395 An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <objectType> 396 doesn't match one of the object type enums. An EGL_BAD_PARAMETER is also 397 returned if the <objectType> is not a supported type; such as no support 398 for streams. 399 400 An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <object> is 401 invalid, unknown, NULL, or is not an object created with 402 EGLDisplay <display>. 403 404 When the <objectType> is EGL_OBJECT_THREAD_KHR, the <object> parameter 405 will be ignored by EGL. The thread is implicitly the active thread. It is 406 recommended that the application pass a NULL for the <object> parameter in 407 this case. 408 409 When the <objectType> is EGL_OBJECT_DISPLAY_KHR, the <object> parameter 410 must be the same as the <display> parameter - the Display to label. If 411 these do not match, in this case, a EGL_BAD_PARAMETER is generated. 412 413 The <display> does not need to be initialized for <objectType> 414 EGL_OBJECT_THREAD_KHR, or EGL_OBJECT_DISPLAY_KHR; However for all other 415 types it must be initialized in order to validate the <object> for 416 attaching a label. 417 418 If there is no error, then the function will set the label and return 419 EGL_SUCCESS. 420 421 3.13.3 Debug Queries: 422 423 The command 424 425 EGLBoolean eglQueryDebugKHR( 426 EGLint attribute, 427 EGLAttrib* value); 428 429 enables the application to query the current value for the debug 430 attributes. On success the function returns EGL_TRUE. 431 432 If <attribute> is a message type enum, the value returned will 433 be either EGL_TRUE or EGL_FALSE to indicate whether the specified types of 434 messages are enabled or disabled respectively. 435 436 Querying for attribute EGL_DEBUG_CALLBACK_KHR will return the current 437 callback pointer. This feature is intended to enable layering of the 438 callback with helper libraries. 439 440 Querying for an unknown attribute will result in an EGL_BAD_ATTRIBUTE error 441 and a return of EGL_FALSE. 442 443Usage Examples 444 445 This example shows starting debug messaging and attaching string labels to 446 newly created objects. 447 448 void MyCallBack(EGLenum error, 449 const char *command, 450 EGLint messageType, 451 EGLLabelKHR threadLabel, 452 EGLLabelKHR objectLabel, 453 const char* message) 454 { 455 printf("Error: %x, With command %s, Type: %d," 456 "Thread: %s, Object: %s, Message: %s.", 457 error, command, messageType, threadLabel, objectLabel, message); 458 } 459 460 EGLint result; 461 462 // DEBUG_MSG_ERROR and CRITICAL are enabled by default 463 EGLAttrib debugAttribs = {EGL_DEBUG_MSG_WARN_KHR, EGL_TRUE, EGL_NONE}; 464 // Start up debug messaging: 465 result = eglDebugMessageControl(MyCallBack, debugAttribs); 466 467 // Label for the rendering thread. 468 EGLLabelKHR renderThreadLabel = (EGLLabelKHR)"Render thread"; 469 result = eglLabelObject(NULL, EGL_OBJECT_THREAD_KHR, NULL, renderThreadLabel); 470 471 EGLDisplay dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY); 472 EGLLabelKHR myDisplay = (EGLLabelKHR)"Default display"; 473 result = eglLabelObject(dpy, EGL_OBJECT_DISPLAY_KHR, dpy, myDisplay); 474 475 eglInitialize(dpy); 476 477 EGLLabelKHR renderContextLabel = (EGLLabelKHR)"Render context"; 478 EGLContext ctx = eglCreateContext(dpy, config, NULL, contextAttribs); 479 result = eglLabelObject(dpy, EGL_OBJECT_CONTEXT_KHR, ctx, renderContextLabel); 480 481 482Issues 483 484 1. Why not use GL_KHR_debug? 485 486 RESOLVED: Most EGL use and object creation happens before creating a 487 GL context. And since EGL operations are thread related - the debug 488 messages should be too. 489 490 2. Is the callback expected only to be called from the thread which it's 491 registered? 492 493 RESOLVED: In most cases when an application thread calls an EGL function, 494 it is expected that EGL upon detecting an error will callback using that 495 application thread. However, EGL may have internal helper threads that 496 execute operations. These threads can callback but will have no 497 threadLabel. It is the responsibility of EGL to ensure that if these 498 threads are blocked in the application's callback by a breakpoint; that 499 EGL does not fail. Internal threads are an implementation detail and 500 are not required. 501 502 503Revision History 504 505 Revision 18, 2016-07-28 (Jeff Vigil) 506 - Clarify return values/error codes. 507 508 Revision 17, 2015-09-23 (Jeff Vigil) 509 - Correct type name to "EGLDEBUGPROCKHR". Updated example code. 510 511 Revision 16, 2015-04-15 (Jeff Vigil) 512 - Clarified that <objectLabel> maybe NULL in the callback, if an error 513 is raised before the primary object handle is validated. 514 515 Revision 15, 2015-03-30 (Jeff Vigil) 516 - Further details to labeling of EGL_OBJECT_DISPLAY_KHR. 517 518 Revision 14, 2015-03-27 (Jeff Vigil) 519 - Further clarification of returns and errors. Add further details to 520 labeling of EGL_OBJECT_THREAD_KHR and EGL_OBJECT_DISPLAY_KHR. 521 522 Revision 13, 2015-03-26 (Jeff Vigil) 523 - Clarified returns and errors. 524 525 Revision 12, 2015-03-24 (Jeff Vigil) 526 - Improve readability. Add assigned enum values. 527 528 Revision 11, 2015-03-02 (Jeff Vigil) 529 - Clarify text regarding parameter attribute_list and its persistence. 530 531 Revision 10, 2015-02-25 (Jeff Vigil) 532 - Clarify text regarding callback blocking. 533 - The implementation must provide errors and success in callbacks so 534 that the callback replaces the use of eglGetError. 535 - <command> strings are read-only EGL memory. 536 - Specify default values for attributes. 537 - Fix typos. 538 539 Revision 9, 2015-02-03 (Jeff Vigil) 540 - Updated contributors. 541 - Add extension type. 542 - Add "KHR" to token and function names. 543 - Fix typos. 544 - Add query to get current callback pointer. 545 546 Revision 8, 2014-12-03 (Jeff Vigil) 547 - Add table containing recommendation for primary object in the callback. 548 549 Revision 7, 2014-10-21 (Jeff Vigil) 550 - Remove configs as a label-able object. 551 - Remove redundant text. 552 - Simplify to one callback per process, not per thread. 553 554 Revision 6, 2014-10-17 (Jeff Vigil) 555 - Add issues. 556 - Address internal EGL threads posting messages. 557 558 Revision 5, 2014-05-27 (Jeff Vigil) 559 - Add missing text for eglQueryDebug. 560 - Clarify threading model. 561 562 Revision 4, 2014-04-14 (Jeff Vigil) 563 - Fix due to feedback from EGL WG face-to-face conference. 564 565 Revision 3, 2014-04-10 (Jeff Vigil) 566 - Refinements. 567 568 Revision 2, 2014-02-21 (Jeff Vigil) 569 - Simplify API. 570 571 Revision 1, 2013-09-08 (Jeff Vigil) 572 - Work in progress for F2F, Based on GL_KHR_debug, replace GL with EGL 573 and remove GL spec specific text. 574