1Name 2 3 KHR_debug 4 5Name Strings 6 7 GL_KHR_debug 8 9Contact 10 11 Christophe Riccio (christophe.riccio 'at' amd.com) 12 13Contributors 14 15 Jaakko Konttinen, AMD 16 Graham Sellers, AMD 17 Mark Young, AMD 18 Ahmet Oguz Akyuz, AMD 19 Bruce Merry, ARM 20 Daniel Koch, TransGaming 21 Jon Leech, Independent 22 Pat Brown, NVIDIA 23 Greg Roth, NVIDIA 24 Yaki Tebeka, Graphic Remedy 25 Piers Daniell, NVIDIA 26 Seth Sowerby, Apple 27 Benj Lipchak, Apple 28 Jean-François Roy, Apple 29 Daniel Rakos, AMD 30 Mark Callow, HI 31 32Notice 33 34 Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at 35 http://www.khronos.org/registry/speccopyright.html 36 37Specification Update Policy 38 39 Khronos-approved extension specifications are updated in response to 40 issues and bugs prioritized by the Khronos OpenGL and OpenGL ES Working Groups. For 41 extensions which have been promoted to a core Specification, fixes will 42 first appear in the latest version of that core Specification, and will 43 eventually be backported to the extension document. This policy is 44 described in more detail at 45 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 46 47Status 48 49 Complete. 50 Approved by the ARB on 2012/06/18. 51 Approved by the OpenGL ES WG on 2012/06/15. 52 Ratified by the Khronos Board of Promoters on 2012/07/27. 53 54Version 55 56 Last Modified Date: July 2, 2015 57 Author Revision: 17 58 59Number 60 61 ARB Extension #119 62 OpenGL ES Extension #118 63 64Dependencies 65 66 OpenGL 1.1 is required. 67 68 The extension is written against the OpenGL 4.2 Compatibility Profile 69 specification (April 27, 2012). 70 71Overview 72 73 This extension allows the GL to notify applications when various events 74 occur that may be useful during application development, debugging and 75 profiling. 76 77 These events are represented in the form of enumerable messages with a 78 human-readable string representation. Examples of debug events include 79 incorrect use of the GL, warnings of undefined behavior, and performance 80 warnings. 81 82 A message is uniquely identified by a source, a type and an 83 implementation-dependent ID within the source and type pair. 84 85 A message's source identifies the origin of the message and can either 86 describe components of the GL, the window system, third-party external 87 sources such as external debuggers, or even the application itself. 88 89 The type of the message roughly identifies the nature of the event that 90 caused the message. Examples include errors, performance warnings, 91 warnings about undefined behavior or notifications identifying that the 92 application is within a specific section of the application code. 93 94 A message's ID for a given source and type further distinguishes messages 95 within namespaces. For example, an error caused by a negative parameter 96 value or an invalid internal texture format are both errors generated by 97 the API, but would likely have different message IDs. 98 99 Each message is also assigned to a severity level that denotes roughly how 100 "important" that message is in comparison to other messages across all 101 sources and types. For example, notification of a GL error would likely 102 have a higher severity than a performance warning due to redundant state 103 changes. 104 105 Furthermore, every message contains an implementation-dependent string 106 representation that provides a useful description of the event. 107 108 Messages are communicated to the application through an application- 109 defined callback function that is called by the GL implementation on each 110 debug message. The motivation for the callback routine is to free 111 application developers from actively having to query whether a GL error, 112 or any other debuggable event has happened after each call to a GL 113 function. With a callback, developers can keep their code free of debug 114 checks, set breakpoints in the callback function, and only have to react 115 to messages as they occur. In situations where using a callback is not 116 possible, a message log is also provided that stores only copies of recent 117 messages until they are actively queried. 118 119 To control the volume of debug output, messages can be disabled either 120 individually by ID, or entire sets of messages can be turned off based on 121 combination of source and type, through the entire application code or 122 only section of the code encapsulated in debug groups. A debug group may 123 also be used to annotate the command stream using descriptive texts. 124 125 This extension also defines debug markers, a mechanism for the OpenGL 126 application to annotate the command stream with markers for discrete 127 events. 128 129 When profiling or debugging an OpenGL application with a built-in or an 130 external debugger or profiler, it is difficult to relate the commands 131 within the command stream to the elements of the scene or parts of the 132 program code to which they correspond. Debug markers and debug groups help 133 obviate this by allowing applications to specify this link. For example, a 134 debug marker can be used to identify the beginning of a frame in the 135 command stream and a debug group can encapsulate a specific command stream 136 to identify a rendering pass. Debug groups also allow control of the debug 137 outputs volume per section of an application code providing an effective 138 way to handle the massive amount of debug outputs that drivers can 139 generate. 140 141 Some existing implementations of ARB_debug_output only expose the 142 ARB_debug_output extension string if the context was created with the 143 debug flag {GLX|WGL}_CONTEXT_DEBUG_BIT_ARB as specified in 144 {GLX|WGL}_ARB_create_context. The behavior is not obvious when the 145 functionality is brought into the OpenGL core specification because the 146 extension string and function entry points must always exist. 147 148 This extension modifies the existing ARB_debug_output extension to allow 149 implementations to always have an empty message log. The specific messages 150 written to the message log or callback routines are already implementation 151 defined, so this specification simply makes it explicit that it's fine for 152 there to be zero messages generated, even when a GL error occurs, which is 153 useful if the context is non-debug. 154 155 Debug output can be enabled and disabled by changing the DEBUG_OUTPUT 156 state. It is implementation defined how much debug output is generated if 157 the context was created without the CONTEXT_DEBUG_BIT set. This is a new 158 query bit added to the existing GL_CONTEXT_FLAGS state to specify whether 159 the context was created with debug enabled. 160 161 Finally, this extension defines a mechanism for OpenGL applications to 162 label their objects (textures, buffers, shaders, etc.) with a descriptive 163 string. 164 165 When profiling or debugging an OpenGL application within an external or 166 built-in (debut output API) debugger or profiler it is difficult to 167 identify objects from their object names (integers). 168 169 Even when the object itself is viewed it can be problematic to 170 differentiate between similar objects. Attaching a descriptive string, a 171 label, to an object obviates this difficulty. 172 173 The intended purpose of this extension is purely to improve the user 174 experience within OpenGL development tools and application built-in 175 profilers and debuggers. This extension typically improves OpenGL 176 programmers efficiency by allowing them to instantly detect issues and the 177 reason for these issues giving him more time to focus on adding new 178 features to an OpenGL application. 179 180IP Status 181 182 No known IP claims. 183 184New Procedures and Functions 185 186 NOTE: when implemented in an OpenGL ES context, all entry points defined 187 by this extension must have a "KHR" suffix. When implemented in an 188 OpenGL context, all entry points must have NO suffix, as shown below. 189 190 void DebugMessageControl(enum source, 191 enum type, 192 enum severity, 193 sizei count, 194 const uint* ids, 195 boolean enabled); 196 197 void DebugMessageInsert(enum source, 198 enum type, 199 uint id, 200 enum severity, 201 sizei length, 202 const char* buf); 203 204 void DebugMessageCallback(DEBUGPROC callback, 205 const void* userParam); 206 207 uint GetDebugMessageLog(uint count, 208 sizei bufSize, 209 enum* sources, 210 enum* types, 211 uint* ids, 212 enum* severities, 213 sizei* lengths, 214 char* messageLog); 215 216 void GetPointerv(enum pname, 217 void** params); 218 219 void PushDebugGroup(enum source, uint id, sizei length, 220 const char * message); 221 222 void PopDebugGroup(void); 223 224 void ObjectLabel(enum identifier, uint name, sizei length, 225 const char *label); 226 227 void GetObjectLabel(enum identifier, uint name, sizei bufSize, 228 sizei *length, char *label); 229 230 void ObjectPtrLabel(void* ptr, sizei length, 231 const char *label); 232 233 void GetObjectPtrLabel(void* ptr, sizei bufSize, 234 sizei *length, char *label); 235 236 237New Types 238 239 NOTE: when implemented in an OpenGL ES context, this typedef must have a 240 "KHR" suffix (GLDEBUGPROCKHR). When implemented in an OpenGL context, 241 thie typedef must have NO suffix, as shown below. 242 243 The callback function that applications can define, and 244 is accepted by DebugMessageCallback, is defined as: 245 246 typedef void (APIENTRY *GLDEBUGPROC)(GLenum source, 247 GLenum type, 248 GLuint id, 249 GLenum severity, 250 GLsizei length, 251 const GLchar* message, 252 const void* userParam); 253 254 Note that this function pointer is defined as having the same calling 255 convention as the GL functions. 256 257New Tokens 258 259 NOTE: when implemented in an OpenGL ES context, all tokens defined by 260 this extension must have a "_KHR" suffix. When implemented in an OpenGL 261 context, all tokens must have NO suffix, as described below. 262 263 Tokens accepted by the <target> parameters of Enable, Disable, and 264 IsEnabled: 265 266 DEBUG_OUTPUT 0x92E0 267 DEBUG_OUTPUT_SYNCHRONOUS 0x8242 268 269 Returned by GetIntegerv when <pname> is CONTEXT_FLAGS: 270 271 CONTEXT_FLAG_DEBUG_BIT 0x00000002 272 273 Tokens accepted by the <value> parameters of GetBooleanv, GetIntegerv, 274 GetFloatv, GetDoublev and GetInteger64v: 275 276 MAX_DEBUG_MESSAGE_LENGTH 0x9143 277 MAX_DEBUG_LOGGED_MESSAGES 0x9144 278 DEBUG_LOGGED_MESSAGES 0x9145 279 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH 0x8243 280 MAX_DEBUG_GROUP_STACK_DEPTH 0x826C 281 DEBUG_GROUP_STACK_DEPTH 0x826D 282 MAX_LABEL_LENGTH 0x82E8 283 284 Tokens accepted by the <pname> parameter of GetPointerv: 285 286 DEBUG_CALLBACK_FUNCTION 0x8244 287 DEBUG_CALLBACK_USER_PARAM 0x8245 288 289 Tokens accepted or provided by the <source> parameters of 290 DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the <sources> 291 parameter of GetDebugMessageLog (some commands restrict <source> to a 292 subset of these parameters; see the specification body for details): 293 294 DEBUG_SOURCE_API 0x8246 295 DEBUG_SOURCE_WINDOW_SYSTEM 0x8247 296 DEBUG_SOURCE_SHADER_COMPILER 0x8248 297 DEBUG_SOURCE_THIRD_PARTY 0x8249 298 DEBUG_SOURCE_APPLICATION 0x824A 299 DEBUG_SOURCE_OTHER 0x824B 300 301 Tokens accepted or provided by the <type> parameters of 302 DebugMessageControl, DebugMessageInsert and DEBUGPROC, and the <types> 303 parameter of GetDebugMessageLog: 304 305 DEBUG_TYPE_ERROR 0x824C 306 DEBUG_TYPE_DEPRECATED_BEHAVIOR 0x824D 307 DEBUG_TYPE_UNDEFINED_BEHAVIOR 0x824E 308 DEBUG_TYPE_PORTABILITY 0x824F 309 DEBUG_TYPE_PERFORMANCE 0x8250 310 DEBUG_TYPE_OTHER 0x8251 311 DEBUG_TYPE_MARKER 0x8268 312 313 Tokens accepted or provided by the <type> parameters of 314 DebugMessageControl and DEBUGPROC, and the <types> parameter of 315 GetDebugMessageLog: 316 317 DEBUG_TYPE_PUSH_GROUP 0x8269 318 DEBUG_TYPE_POP_GROUP 0x826A 319 320 Tokens accepted or provided by the <severity> parameters of 321 DebugMessageControl, DebugMessageInsert and DEBUGPROC callback functions, 322 and the <severities> parameter of GetDebugMessageLog: 323 324 DEBUG_SEVERITY_HIGH 0x9146 325 DEBUG_SEVERITY_MEDIUM 0x9147 326 DEBUG_SEVERITY_LOW 0x9148 327 DEBUG_SEVERITY_NOTIFICATION 0x826B 328 329 Returned by GetError: 330 331 STACK_UNDERFLOW 0x0504 332 STACK_OVERFLOW 0x0503 333 334 Tokens accepted or provided by the <identifier> parameters of 335 ObjectLabel and GetObjectLabel: 336 337 BUFFER 0x82E0 338 SHADER 0x82E1 339 PROGRAM 0x82E2 340 VERTEX_ARRAY 341 QUERY 0x82E3 342 PROGRAM_PIPELINE 0x82E4 343 TRANSFORM_FEEDBACK 344 SAMPLER 0x82E6 345 TEXTURE 346 RENDERBUFFER 347 FRAMEBUFFER 348 [[ Compatibility Profile ]] 349 DISPLAY_LIST 0x82E7 350 [[ End Profile-Specific Language ]] 351 352 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 353 GetFloatv, GetDoublev, and GetInteger64v: 354 355 MAX_LABEL_LENGTH 356 357Additions to Chapter 2 of the OpenGL 4.2 Specification 358(OpenGL Operation) 359 360 In section 2.5 - GL Errors: 361 Add to the end of the section (pg 19): 362 363 "When an error is generated, the GL will also generate a debug output 364 message describing its cause (see section 5.5). The message has the 365 source DEBUG_SOURCE_API and the type DEBUG_TYPE_ERROR, and an 366 implementation-dependent ID." 367 368Additions to Chapter 3 of the OpenGL 4.2 Specification 369(Rasterization) 370 371 None. 372 373Additions to Chapter 4 of the OpenGL 4.2 Specification 374(Per-Fragment Operations and the Frame Buffer) 375 376 None. 377 378Additions to Chapter 5 of the OpenGL 4.2 Specification 379(Special Functions) 380 381 After section 5.4 - Hints (pg. 300) (section 5.3, p 217 in OpenGL ES 3.0), 382 add new section: 383 384 "5.5 - Debug Output 385 386 Application developers can obtain more information from the GL runtime in 387 the form of debug output. This information can include details about GL 388 errors, undefined behavior, implementation-dependent performance warnings, 389 or other useful hints. 390 391 This information is communicated through a stream of debug messages that 392 are generated as GL commands are executed. The application can choose to 393 receive these messages either through a callback routine, or by querying 394 for them from a message log. 395 396 Controls are provided for disabling messages that the application does not 397 care about, and for inserting application-generated messages into the 398 stream. 399 400 The GL may provide different levels of debug output depending on how the 401 context was created. If the context was created without the 402 CONTEXT_FLAG_DEBUG_BIT in the CONTEXT_FLAGS state, as described in Section 403 6.1.12, then the GL may optionally not generate any debug messages, but 404 the functions described below will otherwise operate without error. 405 406 Debug output functionality is controlled with the DEBUG_OUTPUT enable 407 state. If the context is created with the CONTEXT_FLAG_DEBUG_BIT set then 408 the initial state of DEBUG_OUTPUT is TRUE, otherwise the initial state of 409 DEBUG_OUTPUT is FALSE. In a debug context, if DEBUG_OUTPUT is disabled the 410 GL will not generate any debug output logs or callbacks. Enabling 411 DEBUG_OUTPUT again will enable full debug output functionality. If the 412 context was created without the CONTEXT_FLAG_DEBUG_BIT and the 413 DEBUG_OUTPUT is later enabled, the level of debug output logging is 414 defined by the GL implementation, which may have zero debug output. To 415 guarantee the full debug output support of the GL implementation the 416 context should be created with CONTEXT_FLAG_DEBUG_BIT context flag bit 417 set. 418 419 5.5.1 - Debug Messages 420 421 A debug message is uniquely identified by the source that generated it, a 422 type within that source, and an unsigned integer ID identifying the 423 message within that type. The message source is one of the symbolic 424 constants listed in Table 5.3. The message type is one of the symbolic 425 constants listed in Table 5.4. 426 427 Debug Output Message Source Messages Generated by 428 --------------------------- --------------------- 429 DEBUG_SOURCE_API The GL 430 431 DEBUG_SOURCE_SHADER_COMPILER The GLSL shader compiler or compilers for 432 other extension-provided languages 433 434 DEBUG_SOURCE_WINDOW_SYSTEM The window system, such as WGL or GLX 435 436 DEBUG_SOURCE_THIRD_PARTY External debuggers or third-party middleware 437 libraries 438 439 DEBUG_SOURCE_APPLICATION The application 440 441 DEBUG_SOURCE_OTHER Sources that do not fit to any of the ones listed above 442 ---------------------------------------------------------------------------- 443 Table 5.3: Sources of debug output messages. Each message must originate 444 from a source listed in this table. 445 446 447 Debug Output Message Type Informs about 448 ------------------------- ------------- 449 DEBUG_TYPE_ERROR Events that generated an error 450 451 DEBUG_TYPE_DEPRECATED_BEHAVIOR Behavior that has been marked for 452 deprecation 453 454 DEBUG_TYPE_UNDEFINED_BEHAVIOR Behavior that is undefined according to 455 the specification 456 457 DEBUG_TYPE_PERFORMANCE Implementation-dependent performance 458 warnings 459 460 DEBUG_TYPE_PORTABILITY Use of extensions or shaders in a way that 461 is highly vendor-specific 462 463 DEBUG_TYPE_OTHER Types of events that do not fit any of 464 the ones listed above 465 466 DEBUG_TYPE_MARKER Annotation of the command stream 467 468 DEBUG_TYPE_PUSH_GROUP Entering a debug group 469 470 DEBUG_TYPE_POP_GROUP Leaving a debug group 471 472 ---------------------------------------------------------------------------- 473 Table 5.4: Types of debug output messages. Each message is associated with 474 one of these types that describes the nature of the message. 475 476 Each message source and type pair contains its own namespace of messages 477 with every message being associated with an ID. The assignment of IDs to 478 messages within a namespace is implementation-dependent. There can 479 potentially be overlap between the namespaces of two different pairs of 480 source and type, so messages can only be uniquely distinguished from each 481 other by the full combination of source, type and ID. 482 483 Each message is also assigned a severity level that roughly describes its 484 importance across all sources and types along a single global axis. The 485 severity of a message is one of the symbolic constants defined in 486 Table 5.5. Because messages can be disabled by their severity, this allows 487 for quick control the global volume of debug output. 488 489 Severity Level Token Suggested examples of messages 490 -------------------- ------------------------------ 491 492 DEBUG_SEVERITY_HIGH Any GL error; dangerous undefined behavior; 493 any GLSL or ARB shader compiler and 494 linker errors; 495 496 DEBUG_SEVERITY_MEDIUM Severe performance warnings; GLSL 497 or other shader compiler and linker 498 warnings; use of currently deprecated 499 behavior 500 501 DEBUG_SEVERITY_LOW Performance warnings from redundant 502 state changes; trivial undefined behavior 503 504 DEBUG_SEVERITY_NOTIFICATION Any message which is not an 505 error or performance concern 506 507 ---------------------------------------------------------------------------- 508 Table 5.5: Severity levels of messages. Each debug output message is 509 associated with one of these severity levels. 510 511 512 Every message also has a null-terminated string representation that is 513 used to describe the message. The contents of the string can change 514 slightly between different instances of the same message (e.g. which 515 parameter value caused a specific GL error to occur). The format of a 516 message string is left as implementation-dependent, although it should at 517 least represent a concise description of the event that caused the message 518 to be generated. Messages with different IDs should also have 519 sufficiently distinguishable string representations to warrant their 520 separation. 521 522 The lengths of all messages, including their null terminators, must be 523 guaranteed to be less or equal to the value of the 524 implementation-dependent constant MAX_DEBUG_MESSAGE_LENGTH. 525 526 Messages can be either enabled or disabled. Messages that are disabled 527 will not be generated. All messages are initially enabled unless their 528 assigned severity is DEBUG_SEVERITY_LOW. The enabled state of messages can 529 be changed using the command DebugMessageControl. 530 531 5.5.2 - Debug Message Callback 532 533 Applications can provide a callback function for receiving debug messages 534 using the command 535 536 void DebugMessageCallback(DEBUGPROC callback, 537 const void* userParam); 538 539 with <callback> storing the address of the callback function. This 540 function's prototype must follow the type definition of DEBUGPROC 541 including its platform-dependent calling convention. Anything else will 542 result in undefined behavior. Only one debug callback can be specified 543 for the current context, and further calls overwrite the previous 544 callback. Specifying NULL as the value of <callback> clears the current 545 callback and disables message output through callbacks. Applications can 546 provide user-specified data through the pointer <userParam>. The context 547 will store this pointer and will include it as one of the parameters in 548 each call to the callback function. 549 550 If the application has specified a callback function for receiving debug 551 output, the implementation will call that function whenever any enabled 552 message is generated. The source, type, ID, and severity of the message 553 are specified by the DEBUGPROC parameters <source>, <type>, <id>, and 554 <severity>, respectively. The string representation of the message is 555 stored in <message> and its length (excluding the null-terminator) is 556 stored in <length>. The parameter <userParam> is the user-specified 557 parameter that was given when calling DebugMessageCallback. 558 559 Applications can query the current callback function and the current 560 user-specified parameter by obtaining the values of 561 DEBUG_CALLBACK_FUNCTION and DEBUG_CALLBACK_USER_PARAM, respectively. 562 563 Applications that specify a callback function must be aware of certain 564 special conditions when executing code inside a callback when it is 565 called by the GL, regardless of the debug source. 566 567 The memory for <message> is owned and managed by the GL, and should 568 only be considered valid for the duration of the function call. 569 570 The behavior of calling any GL or window system function from within the 571 callback function is undefined and may lead to program termination. 572 573 Care must also be taken in securing debug callbacks for use with 574 asynchronous debug output by multi-threaded GL implementations. 575 Section 5.5.7 describes this in further detail. 576 577 If the DEBUG_OUTPUT state is disabled then the GL will not call the 578 callback function. 579 580 5.5.3 - Debug Message Log 581 582 If DEBUG_CALLBACK_FUNCTION is NULL, then debug messages are instead 583 stored in an internal message log up to some maximum number of messages 584 as defined by the value of MAX_DEBUG_LOGGED_MESSAGES. 585 586 Each context stores its own message log and will only store messages 587 generated by commands operating in that context. If the message log 588 fills up, then any subsequently generated messages will not be 589 placed in the log until the message log is cleared, and will instead 590 be discarded. 591 592 Applications can query the number of messages currently in the log by 593 obtaining the value of DEBUG_LOGGED_MESSAGES, and the string length 594 (including its null terminator) of the oldest message in the log through 595 the value of DEBUG_NEXT_LOGGED_MESSAGE_LENGTH. 596 597 To fetch message data stored in the log, the command GetDebugMessageLog 598 can be used as described in section 6.1.15. 599 600 If DEBUG_CALLBACK_FUNCTION is not NULL, no generated messages will be 601 stored in the log but will instead be passed to the debug callback routine 602 as described in section 5.5.2. 603 604 If the DEBUG_OUTPUT state is disabled then no messages are added to the 605 message log. 606 607 5.5.4 - Controlling Debug Messages 608 609 Applications can control the volume of debug output in the active debug 610 group, by disabling specific or groups of messages with the command: 611 612 void DebugMessageControl(enum source, 613 enum type, 614 enum severity, 615 sizei count, 616 const uint* ids, 617 boolean enabled); 618 619 If <enabled> is TRUE, the referenced subset of messages will be enabled. 620 If FALSE, then those messages will be disabled. 621 622 This command can reference different subsets of messages by first 623 considering the set of all messages, and filtering out messages based on 624 the following ways: 625 626 - If <source>, <type>, or <severity> is DONT_CARE, the messages from 627 all sources, of all types, or of all severities are referenced 628 respectively. 629 630 - When values other than DONT_CARE are specified, all messages whose 631 source, type, or severity match the specified <source>, <type>, or 632 <severity> respectively will be referenced. 633 634 - If <count> is greater than zero, then <ids> is an array of <count> 635 message IDs for the specified combination of <source> and <type>. In 636 this case, if <source> or <type> is DONT_CARE, or <severity> is not 637 DONT_CARE, the error INVALID_OPERATION is generated. 638 639 Unrecognized message IDs in <ids> are ignored. If <count> is zero, 640 the value if <ids> is ignored. 641 642 In addition, if any of <source>, <type>, and <severity> is not DONT_CARE 643 and is not one of the symbols from, respectively, Table 5.3, Table 5.4, 644 and Table 5.5, the error INVALID_ENUM is generated. If <count> is 645 negative, the error INVALID_VALUE is generated. 646 647 Although messages are grouped into an implicit hierarchy by their 648 sources and types, there is no explicit per-source, per-type or 649 per-severity enabled state. Instead, the enabled state is stored 650 individually for each message. There is no difference between disabling 651 all messages from one source in a single call, and individually 652 disabling all messages from that source using their types and IDs. 653 654 If the DEBUG_OUTPUT state is disabled the GL operates the same as 655 if messages of every <source>, <type> or <severity> are disabled. 656 657 5.5.5 - Externally Generated Messages 658 659 To support applications and third-party libraries generating their own 660 messages, such as ones containing timestamp information or signals about 661 specific render system events, the following function can be called 662 663 void DebugMessageInsert(enum source, 664 enum type, 665 uint id, 666 enum severity, 667 int length, 668 const char* buf); 669 670 The value of <id> specifies the ID for the message and <severity> 671 indicates its severity level as defined by the caller. If <severity> is 672 not one of the severity levels listed in Table 5.5, the error 673 INVALID_ENUM will be generated. The value of <type> must be one of the 674 values from Table 5.4 and the value of <source> must be either 675 DEBUG_SOURCE_APPLICATION or DEBUG_SOURCE_THIRD_PARTY, or the error 676 INVALID_ENUM will be generated. The string <buf> contains the string 677 representation of the message. The parameter <length> contains the number 678 of characters in <buf>. If <length> is negative, it is implied that <buf> 679 contains a null terminated string. The error INVALID_VALUE will be 680 generated if the number of characters in <buf>, excluding the null 681 terminator when <length> is negative, is not less than the value of 682 MAX_DEBUG_MESSAGE_LENGTH. 683 684 If the DEBUG_OUTPUT state is disabled calls to DebugMessageInsert are 685 discarded and do not generate an error. 686 687 5.5.6 - Debug Groups 688 689 Debug groups provide a method for annotating a command stream with 690 discrete groups of commands using a descriptive text. Debug output 691 messages, either generated by the implementation or inserted by the 692 application with DebugMessageInsert are written to the active debug group, 693 the top of the debug group stack. Debug groups are strictly hierarchical. 694 Their sequences may be nested within other debug groups but can not 695 overlap. If no debug group has been pushed by the application then the 696 active debug group is the default debug group. 697 698 The command 699 700 void PushDebugGroup(enum source, uint id, sizei length, 701 const char *message); 702 703 pushes a debug group described by the string <message> into the command 704 stream. The value of <id> specifies the ID of messages generated. The 705 parameter <length> contains the number of characters in <message>. If 706 <length> is negative, it is implied that <message> contains a null 707 terminated string. The message has the specified <source> and <id>, <type> 708 DEBUG_TYPE_PUSH_GROUP, and <severity> DEBUG_SEVERITY_NOTIFICATION. The GL 709 will put a new debug group on top of the debug group stack which inherits 710 the control of the volume of debug output of the debug group previously 711 residing on the top of the debug group stack. Because debug groups are 712 strictly hierarchical, any additional control of the debug output volume 713 will only apply within the active debug group and the debug groups pushed 714 on top of the active debug group. 715 716 An INVALID_ENUM error is generated if the value of <source> is neither 717 DEBUG_SOURCE_APPLICATION nor DEBUG_SOURCE_THIRD_PARTY. An INVALID_VALUE 718 error is generated if <length> is negative and the number of characters in 719 <message>, excluding the null-terminator, is not less than the value of 720 MAX_DEBUG_MESSAGE_LENGTH. 721 722 The command 723 724 void PopDebugGroup(); 725 726 pops the active debug group. When a debug group is popped, the GL 727 will also generate a debug output message describing its cause based 728 on the <message> string, the source <source>, and an ID <id> submitted 729 to the associated PushDebugGroup command. DEBUG_TYPE_PUSH_GROUP 730 and DEBUG_TYPE_POP_GROUP share a single namespace for message <id>. 731 <severity> has the value DEBUG_SEVERITY_NOTIFICATION. The <type> 732 has the value DEBUG_TYPE_POP_GROUP. Popping a debug group restores 733 the debug output volume control of the parent debug group. 734 735 Attempting to pop the default debug group off the stack generates a 736 STACK_UNDERFLOW error; pushing a debug group onto a stack containing 737 MAX_DEBUG_GROUP_STACK_DEPTH minus one elements will generate a 738 STACK_OVERFLOW error. 739 740 5.5.7 - Asynchronous and Synchronous Debug Output 741 742 The behavior of how and when the GL driver is allowed to generate debug 743 messages, and subsequently either call back to the application or place 744 the message in the debug message log, is affected by the state 745 DEBUG_OUTPUT_SYNCHRONOUS. This state can be modified by the Enable and 746 Disable commands. Its initial value is FALSE. 747 748 When DEBUG_OUTPUT_SYNCHRONOUS is disabled, the driver is optionally 749 allowed to concurrently call the debug callback routine from 750 potentially multiple threads, including threads that the context that 751 generated the message is not currently bound to. The implementation may 752 also call the callback routine asynchronously after the GL command that 753 generated the message has already returned. The application is fully 754 responsible for ensuring thread safety due to debug callbacks under 755 these circumstances. In this situation the <userParam> value may be 756 helpful in identifying which application thread's command originally 757 generated the debug callback. 758 759 When DEBUG_OUTPUT_SYNCHRONOUS is enabled, the driver guarantees 760 synchronous calls to the callback routine by the context. When synchronous 761 callbacks are enabled, all calls to the callback routine will be made by 762 the thread that owns the current context; all such calls will be made 763 serially by the current context; and each call will be made before the GL 764 command that generated the debug message is allowed to return. 765 766 When no callback is specified and DEBUG_OUTPUT_SYNCHRONOUS is disabled, 767 the driver can still asynchronously place messages in the debug message 768 log, even after the context thread has returned from the GL function that 769 generated those messages. When DEBUG_OUTPUT_SYNCHRONOUS is enabled, the 770 driver guarantees that all messages are added to the log before the GL 771 function returns. 772 773 Enabling synchronous debug output greatly simplifies the responsibilities 774 of the application for making its callback functions thread-safe, but may 775 potentially result in drastically reduced driver performance. 776 777 DEBUG_OUTPUT_SYNCHRONOUS only guarantees intra-context synchronization for 778 the callbacks of messages generated by that context, and does not 779 guarantee synchronization across multiple contexts. If multiple contexts 780 are concurrently used by the application, it is allowed for those contexts 781 to also concurrently call their designated callbacks, and the application 782 is responsible for handling thread safety in that situation even if 783 DEBUG_OUTPUT_SYNCHRONOUS is enabled in all contexts." 784 785 5.5.8 Debug Labels: 786 787 Debug labels provide a method for annotating any object (texture, buffer, 788 shader, etc.) with a descriptive text label. These labels may then be used 789 by the debug output (see section 5.5) or an external tool such as a 790 debugger or profiler to describe labelled objects. 791 792 The command 793 794 void ObjectLabel(enum identifier, uint name, sizei length, const char *label); 795 796 labels the object identified by <name> and its namespace <identifier>. 797 <identifier> must be one of the tokens in table 5.1, indicating the type 798 of the object corresponding to <name>. 799 800 801 Identifier Object Type 802 --------------------------------------- 803 BUFFER | buffer 804 SHADER | shader 805 PROGRAM | program 806 VERTEX_ARRAY | vertex array 807 QUERY | query 808 PROGRAM_PIPELINE | program pipeline 809 TRANSFORM_FEEDBACK| transform feedback 810 SAMPLER | sampler 811 TEXTURE | texture 812 RENDERBUFFER | render buffer 813 FRAMEBUFFER | frame buffer 814[[ Compatibility Profile Only]] 815 DISPLAY_LIST | display list 816[[ End Profile-Specific Language ]] 817 --------------------------------------- 818 Table 5.1. Valid object namespace identifiers and the corresponding 819 object type. 820 821 The command 822 823 void ObjectPtrLabel(void* ptr, sizei length, const char *label); 824 825 labels a sync object identified by <ptr>. 826 827 <label> contains a string used to label an object. <length> contains the 828 number of characters in <label>. If <length> is negative, it is implied that 829 <label> contains a null-terminated string. If <label> is NULL, any debug 830 label is effectively removed from the object. 831 832 An INVALID_ENUM error is generated by ObjectLabel if <identifier> is not 833 one of the object types listed in table 5.1. 834 835 An INVALID_VALUE error is generated by ObjectLabel if <name> is not 836 the name of a valid object of the type specified by <identifier>. 837 838 An INVALID_VALUE is generated if the <ptr> parameter of ObjectPtrLabel 839 is not the name of a sync object. 840 841 An INVALID_VALUE error is generated if the number of characters in 842 <label>, excluding the null terminator when <length> is negative, is not 843 less than the value of MAX_LABEL_LENGTH. 844 845 A label is part of the state of the object to which it is associated. 846 The initial state of an object's label is the empty string. Labels need 847 not be unique. 848 849 850Additions to Chapter 6 of the OpenGL 4.2 Specification 851(State and State Requests) 852 853 Modify the title of Section 6.1.6 - String Queries to read 854 "Section 6.1.6 - Pointer and String Queries", and insert to the 855 beginning of the section: 856 857 The command 858 859 void GetPointerv(enum pname, void** params); 860 861 obtains the pointer or pointers named <pname> in the array <params>. 862 The possible values for <pname> are DEBUG_CALLBACK_FUNCTION and 863 DEBUG_CALLBACK_USER_PARAM, which respectively return the current 864 debug output callback function pointer and its application-specified 865 user parameter. Each <pname> returns a single pointer value. 866 867 Modify Section 6.1.12 "Pointer and String Queries" 868 869 Add to the paragraph describing the context profile mask and flags 870 (preceding the description of GetStringi) on page 485: 871 872 "If CONTEXT_FLAG_DEBUG_BIT is set in CONTEXT_FLAGS, then the DEBUG_OUTPUT 873 state, as described in section 5.5, will be enabled by default." 874 875 After Section 6.1.14 - Renderbuffer Object Queries (pg 324): 876 Add new Section 6.1.15 - Debug Object Queries: 877 878 6.1.15 - Debug Output Queries 879 880 When no debug callback is set, debug messages are stored in 881 a debug message log as described in section 5.5.3. Messages can 882 be queried from the log by calling 883 884 uint GetDebugMessageLog(uint count, 885 sizei bufSize, 886 enum* sources, 887 enum* types, 888 uint* ids, 889 enum* severities, 890 sizei* lengths, 891 char* messageLog); 892 893 This function fetches a maximum of <count> messages from the message 894 log, and will return the number of messages successfully fetched. 895 896 Messages will be fetched from the log in order of oldest to 897 newest. Those messages that were fetched will be removed from the 898 log. 899 900 The sources, types, severities, IDs, and string lengths of 901 fetched messages will be stored in the application-provided arrays 902 <sources>, <types>, <severities>, <ids>, and <lengths>, 903 respectively. The application is responsible for allocating enough 904 space for each array to hold up to <count> elements. The string 905 representations of all fetched messages are stored in the 906 <messageLog> array. If multiple messages are fetched, their strings 907 are concatenated into the same <messageLog> array and will be 908 separated by single null terminators. The last string in the array 909 will also be null-terminated. The maximum size of <messageLog>, 910 including the space used by all null terminators, is given by 911 <bufSize>. If <bufSize> is less than zero and <messageLog> is not 912 NULL, an INVALID_VALUE error will be generated. If a message's 913 string, including its null terminator, can not fully fit within the 914 <messageLog> array's remaining space, then that message and any 915 subsequent messages will not be fetched and will remain in the log. 916 The string lengths stored in the array <lengths> include the space 917 for the null terminator of each string. 918 919 Any or all of the arrays <sources>, <types>, <ids>, <severities>, 920 <lengths> and <messageLog> can also be null pointers, which causes 921 the attributes for such arrays to be discarded when messages 922 are fetched, however those messages will still be removed from the 923 log. Thus to simply delete up to <count> messages from the message 924 log while ignoring their attributes, the application can call the 925 function with null pointers for all attribute arrays. 926 927 If the context was created without the CONTEXT_FLAG_DEBUG_BIT in the 928 CONTEXT_FLAGS state, as described in Section 6.1.12, then the GL can opt 929 to never add messages to the message log so GetDebugMessageLog will 930 always return zero. 931 932 Add new Section 6.1.16 - Debug Label Queries: 933 934 6.1.16 - Debug Label Queries 935 936 The command 937 938 void GetObjectLabel(enum identifier, uint name, sizei bufSize, 939 sizei *length, char *label); 940 void GetObjectPtrLabel(void* ptr, sizei bufSize, 941 sizei *length, char *label); 942 943 returns in <label> the string labelling an object. <label> will be 944 null-terminated. The actual number of characters written into <label>, 945 excluding the null terminator, is returned in <length>. If <length> is 946 NULL, no length is returned. The maximum number of characters that may 947 be written into <label>, including the null terminator, is specified by 948 <bufSize>. If no debug label was specified for the object then <label> 949 will contain a null-terminated empty string, and zero will be returned 950 in <length>. If <label> is NULL and <length> is non-NULL then no string 951 will be returned and the length of the label will be returned in 952 <length>. 953 954 An INVALID_ENUM error is generated by GetObjectLabel if identifier is not 955 one of the object types listed in table 5.1 except SYNC. 956 957 An INVALID_VALUE error is generated by GetObjectLabel if <name> is not 958 the name of a valid object of the type specified by <identifier>. 959 960Additions to the OpenGL / GLX / GLX Protocol Specifications 961 962 None. 963 964Additions to the WGL Specification 965 966 None. 967 968 969Interactions with OpenGL ES 970 971 This extension specification uses non-suffixed names for new entry 972 points, types, and tokens. This is correct for implementations against 973 OpenGL. However, when implemented in an OpenGL ES context, all new entry 974 points, types, and tokens are given KHR suffixes. 975 976 In OpenGL ES versions prior to and including ES 3.1 there is no 977 CONTEXT_FLAGS state and therefore the CONTEXT_FLAG_DEBUG_BIT cannot be 978 queried. GLES contexts must act as if this state existed as described 979 in this specification even if the state itself is not visible to 980 applications. For example, DEBUG_OUTPUT must still be enabled by default 981 if the context was created with debug enabled. 982 983Interactions with GLX_ARB_create_context_robustness 984 985 If the GLX window-system binding API is used to create a context, 986 the GLX_ARB_create_context extension is supported, and the bit 987 GLX_CONTEXT_DEBUG_BIT_ARB is set in GLX_CONTEXT_FLAGS when 988 glXCreateContextAttribsARB is called, the resulting context will 989 have debug enabled, and the CONTEXT_FLAG_DEBUG_BIT bit will be set 990 in CONTEXT_FLAGS as described above in section 6.1.12. 991 992Interactions with WGL_ARB_create_context_robustness 993 994 If the WGL window-system binding API is used to create a context, 995 the WGL_ARB_create_context extension is supported, and the bit 996 WGL_CONTEXT_DEBUG_BIT_ARB is set in WGL_CONTEXT_FLAGS when 997 wglCreateContextAttribsARB is called, the resulting context will 998 have debug enabled, and the CONTEXT_FLAG_DEBUG_BIT bit will be set 999 in CONTEXT_FLAGS as described above in section 6.1.12. 1000 1001Dependencies on GL and ES profiles, versions, and other extensions 1002 1003 Dependencies on OpenGL 4.2 Compatibility specification and any other 1004 versions or extensions that already provide the GetPointerv entry 1005 point as provided by the OpenGL 4.2 Compatibility specification 1006 1007 - Remove the modifications to Section 6.1.6 from this 1008 specification with the exception that GetPointerv will still 1009 accept DEBUG_CALLBACK_FUNCTION and 1010 DEBUG_CALLBACK_USER_PARAM as valid values for <pname>, 1011 and will return the same values as described in Chapter 6. 1012 1013 Dependencies on OpenGL 4.2 Compatibility specification and any other 1014 versions that support display lists 1015 1016 - DebugMessageControl, DebugMessageInsert, 1017 DebugMessageCallback, and GetDebugMessageLog are 1018 not compiled into display lists. 1019 1020 Add the following to section 5.5.1 of the OpenGL 4.0 1021 Compatibility specification, after the paragraph beginning 1022 with "GL command stream management" (pg 414): 1023 1024 "Debug output: DebugMessageControl, 1025 DebugMessageInsert, DebugMessageCallback, and 1026 GetDebugMessageLog" 1027 1028 Add the same language to corresponding sections of other 1029 specifications. 1030 1031Dependencies on program pipeline objects 1032 1033 If program pipeline objects are not supported, remove PROGRAM_PIPELINE 1034 from table 5.1. 1035 1036 Program pipeline objects are supported starting with OpenGL 4.2 and 1037 OpenGL ES 3.1. They are also supported if the OpenGL 1038 GL_ARB_separate_shader_objects or OpenGL ES 1039 GL_EXT_separate_shader_objects extensions are supported. 1040 1041Errors 1042 1043 The error INVALID_ENUM will be generated by DebugMessageControl 1044 if <source> is not DONT_CARE or one of the debug output sources 1045 listed in Table 5.3. 1046 1047 The error INVALID_ENUM will be generated by DebugMessageControl 1048 if <type> is not DONT_CARE or one of the debug output types listed 1049 in Table 5.4. 1050 1051 The error INVALID_ENUM will be generated by DebugMessageControl 1052 if <severity> is not DONT_CARE or one of the severity levels listed 1053 in Table 5.5. 1054 1055 The error INVALID_VALUE will be generated by DebugMessageControl 1056 if <count> is less than zero. 1057 1058 The error INVALID_OPERATION will be generated by 1059 DebugMessageControl when <count> is greater than zero and 1060 <source> is DONT_CARE. 1061 1062 The error INVALID_OPERATION will be generated by 1063 DebugMessageControl when <count> is greater than zero and 1064 <type> is DONT_CARE. 1065 1066 The error INVALID_OPERATION will be generated by 1067 DebugMessageControl when <count> is greater than zero and 1068 and <severity> is not DONT_CARE. 1069 1070 The error INVALID_VALUE will be generated by GetDebugMessageLog 1071 if the value of <count> is less than zero. 1072 1073 The error INVALID_VALUE will be generated by GetDebugMessageLog 1074 if <bufSize> is less than zero. 1075 1076 The error INVALID_ENUM will be generated by DebugMessageInsert if 1077 the value of <source> is not DEBUG_SOURCE_APPLICATION or 1078 DEBUG_SOURCE_THIRD_PARTY. 1079 1080 The error INVALID_ENUM will be generated by DebugMessageInsert if 1081 the value of <type> is not one of the values from Table 5.4. 1082 1083 The error INVALID_ENUM will be generated by DebugMessageInsert if 1084 <severity> is not a valid debug severity level listed in Table 5.5. 1085 1086 The error INVALID_VALUE will be generated by DebugMessageInsert 1087 if the number of characters in <buf>, excluding the null terminator 1088 when <length> is negative, is not less than 1089 MAX_DEBUG_MESSAGE_LENGTH. 1090 1091 The error INVALID_ENUM will be generated by PushDebugGroup 1092 if <source> is not DEBUG_SOURCE_APPLICATION or 1093 DEBUG_SOURCE_THIRD_PARTY. 1094 1095 The error INVALID_VALUE will be generated by PushDebugGroup 1096 if <length> is negative and the number of characters in <message>, 1097 excluding the null-terminator, is not less than the value of 1098 MAX_DEBUG_MESSAGE_LENGTH. 1099 1100 The <source> value of PushDebugGroup must be either 1101 DEBUG_SOURCE_APPLICATION or DEBUG_SOURCE_THIRD_PARTY, or the 1102 error INVALID_ENUM will be generated. 1103 1104 Popping a group off the stack with no entry generates the error 1105 STACK_UNDERFLOW; pushing a debug group onto a full stack generates 1106 the error STACK_OVERFLOW. 1107 1108 An INVALID_VALUE error is generated by ObjectLabel and 1109 GetObjectLabel if <name> is not the name of a valid object of the type 1110 specified by <identifier>. 1111 1112 An INVALID_VALUE error is generated by ObjectPtrLabel and 1113 GetObjectPtrLabel if <ptr> is not the name of a sync object. 1114 1115 An INVALID_VALUE error is generated by ObjectLabel if the number of 1116 characters in <label>, excluding the null terminator when <length> is 1117 negative, is not less than MAX_LABEL_LENGTH. 1118 1119 An INVALID_ENUM error is generated by ObjectLabel and GetObjectLabel if 1120 <identifier> is not one of the object namespace tokens in table 5.1. 1121 1122 1123New State 1124 1125 Add new table 6.55 after p.376 (Debug Output): 1126 1127 Initial 1128 Get Value Type Get Command Value Description Sec Attribute 1129 -------------------------- ---- ----------- ------- ------------------------- ------ --------- 1130 DEBUG_CALLBACK_FUNCTION Y GetPointerv NULL The current debug output 5.5.2 - 1131 callback function pointer 1132 1133 DEBUG_CALLBACK_USER_PARAM Y GetPointerv NULL The current debug output 5.5.2 - 1134 callback user parameter 1135 1136 DEBUG_LOGGED_MESSAGES Z+ GetIntegerv 0 The number of messages 5.5.3 - 1137 currently in the debug 1138 message log 1139 1140 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH Z+ GetIntegerv 0 The string length of the 5.5.3 - 1141 oldest debug message in 1142 the debug message log 1143 1144 DEBUG_GROUP_STACK_DEPTH Z+ GetIntegerv 1 Debug group stack 5.5.6 - 1145 pointer 1146 1147 DEBUG_OUTPUT_SYNCHRONOUS B IsEnabled FALSE The enabled state for 5.5.7 - 1148 synchronous debug message 1149 callbacks 1150 1151 DEBUG_OUTPUT B IsEnabled Depends on The enabled state for 5.5 - 1152 the context* debug output 1153 functionality 1154 1155 * Contexts created with the CONTEXT_DEBUG_BIT bit set, as defined in 1156 GLX_ARB_create_context and WGL_ARB_create_context control the initial 1157 value of this state. If CONTEXT_DEBUG_BIT is set then the initial 1158 value of DEBUG_OUTPUT is TRUE otherwise its FALSE. 1159 1160 1161 Add the following to Table 6.14 Buffer Object State: 1162 1163 Initial 1164 Get Value Type Get Command Value Description Sec 1165 --------- ---- -------------- ------- ----------- --- 1166 - S GetObjectLabel empty Debug label 6.2 1167 1168 Add the following to Table 6.24 Textures (state per texture object): 1169 1170 Initial 1171 Get Value Type Get Command Value Description Sec 1172 --------- ---- -------------- ------- ----------- --- 1173 - S GetObjectLabel empty Debug label 6.2 1174 1175 Add the following to Table 6.44 Shader Object State: 1176 1177 Initial 1178 Get Value Type Get Command Value Description Sec 1179 --------- ---- -------------- ------- ----------- --- 1180 - S GetObjectLabel empty Debug label 6.2 1181 1182 Add the following to Table 6.46 Program Object State: 1183 1184 Initial 1185 Get Value Type Get Command Value Description Sec 1186 --------- ---- -------------- ------- ----------- --- 1187 - S GetObjectLabel empty Debug label 6.2 1188 1189 Add the following to Table 6.36 Renderbuffer (state per renderbuffer object): 1190 1191 Initial 1192 Get Value Type Get Command Value Description Sec 1193 --------- ---- -------------- ------- ----------- --- 1194 - S GetObjectLabel empty Debug label 6.2 1195 1196 Add the following to Table 6.33 Framebuffer (state per framebuffer object): 1197 1198 Initial 1199 Get Value Type Get Command Value Description Sec 1200 --------- ---- -------------- ------- ----------- --- 1201 - S GetObjectLabel empty Debug label 6.2 1202 1203 Add the following to Table 6.9 Vertex Array Object State: 1204 1205 Initial 1206 Get Value Type Get Command Value Description Sec 1207 --------- ---- -------------- ------- ----------- --- 1208 - S GetObjectLabel empty Debug label 6.2 1209 1210 Add the following to Table 6.54 Query Object State: 1211 1212 Initial 1213 Get Value Type Get Command Value Description Sec 1214 --------- ---- -------------- ------- ----------- --- 1215 - S GetObjectLabel empty Debug label 6.2 1216 1217 Add the following to Table 6.45 Program Pipeline Object State: 1218 1219 Initial 1220 Get Value Type Get Command Value Description Sec 1221 --------- ---- -------------- ------- ----------- --- 1222 - S GetObjectLabel empty Debug label 6.2 1223 1224 Add the following to Table 6.26 Textures (state per sampler object): 1225 1226 Initial 1227 Get Value Type Get Command Value Description Sec 1228 --------- ---- -------------- ------- ----------- --- 1229 - S GetObjectLabel empty Debug label 6.2 1230 1231 Add the following to Table 6.56 Transform Feedback State: 1232 1233 Initial 1234 Get Value Type Get Command Value Description Sec 1235 --------- ---- -------------- ------- ----------- --- 1236 - S GetObjectLabel empty Debug label 6.2 1237 1238 Add the following to Table 6.57 Sync (state per sync object): 1239 1240 Initial 1241 Get Value Type Get Command Value Description Sec 1242 --------- ---- ----------------- ------- ----------- --- 1243 - S GetObjectPtrLabel empty Debug label 6.2 1244 1245 [[ Compatibility Profile ]] 1246 Add Table 6.60 Display List State: 1247 1248 Initial 1249 Get Value Type Get Command Value Description Sec 1250 --------- ---- ----------------- ------- ----------- --- 1251 - S GetObjectLabel empty Debug label 6.2 1252 [[ End Profile-Specific Language ]] 1253 1254 1255New Implementation Dependent State 1256 1257 Add new table 6.56 after table 6.55 (Implementation Dependent Debug Output Values): 1258 Minimum 1259 Get Value Type Get Command Value Description Sec Attribute 1260 -------------------------------- -- ----------- ----- ------------------------- ------ --------- 1261 MAX_DEBUG_MESSAGE_LENGTH Z+ GetIntegerv 1 The maximum length of a 5.5.1 - 1262 debug message string, 1263 including its null 1264 terminator 1265 1266 MAX_DEBUG_LOGGED_MESSAGES Z+ GetIntegerv 1 The maximum number of 5.5.3 - 1267 messages stored in the 1268 debug message log 1269 1270 MAX_DEBUG_GROUP_STACK_DEPTH Z+ GetIntegerv 64 Maximum group 5.5.6 - 1271 stack depth 1272 1273 MAX_LABEL_LENGTH Z+ GetIntegerv 256 Max length of a label 5.5.8 - 1274 string 1275 1276 1277Usage Examples 1278 1279 Scenario 1: skip a section of the code 1280 // Setup of the default active debug group: Filter everything in 1281 glDebugMessageControl(GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_TRUE); 1282 1283 // Generate a debug marker debug output message 1284 glDebugMessageInsert( 1285 GL_DEBUG_SOURCE_APPLICATION, 1286 GL_DEBUG_TYPE_MARKER, 100, 1287 GL_DEBUG_SEVERITY_NOTIFICATION, 1288 -1, "Message 1"); 1289 1290 // Push debug group 1 1291 glPushDebugGroup( 1292 GL_DEBUG_SOURCE_APPLICATION, 1293 1, 1294 -1, "Message 2"); 1295 1296 // Setup of the debug group 1: Filter everything out 1297 glDebugMessageControl(GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_FALSE); 1298 1299 // This message won't appear in the debug output log of 1300 glDebugMessageInsert( 1301 GL_DEBUG_SOURCE_APPLICATION, 1302 GL_DEBUG_TYPE_MARKER, 100, 1303 GL_DEBUG_SEVERITY_NOTIFICATION, 1304 -1, "Message 3"); 1305 1306 // Pop debug group 1, restore the volume control of the default debug group. 1307 glPopDebugGroup(); 1308 1309 // Generate a debug marker debug output message 1310 glDebugMessageInsert( 1311 GL_DEBUG_SOURCE_APPLICATION, 1312 GL_DEBUG_TYPE_MARKER, 100, 1313 GL_DEBUG_SEVERITY_NOTIFICATION, 1314 -1, "Message 5"); 1315 1316 // Expected debug output from the GL implementation 1317 // Message 1 1318 // Message 2 1319 // Message 2 1320 // Message 5 1321 1322 Scenario 2: Only output a subsection of the code 1323 and disable some messages for the entire application 1324 1325 // Setup the control of de debug output for the default debug group 1326 glDebugMessageControl( 1327 GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_FALSE); 1328 glDebugMessageControl( 1329 GL_DEBUG_SOURCE_THIRD_PARTY, GL_DONT_CARE, GL_DONT_CARE, 0, NULL, GL_FALSE); 1330 std::vector<GLuint> Messages = {1234, 2345, 3456, 4567}; 1331 glDebugMessageControl( 1332 GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_OTHER, GL_DONT_CARE, 1333 GLuint(Messages,size()), &Messages[0], GL_FALSE); 1334 glDebugMessageControl( 1335 GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_PORTABILITY, GL_DONT_CARE, 1336 GLuint(Messages,size()), &Messages[0], GL_FALSE); 1337 1338 // Push debug group 1 1339 // Inheritate of the default debug group debug output volume control 1340 // Filtered out by glDebugMessageControl 1341 glPushDebugGroup( 1342 GL_DEBUG_SOURCE_APPLICATION, 1343 1, 1344 -1, "Message 1"); 1345 1346 // In this section of the code, we are interested in performances. 1347 glDebugMessageControl( 1348 GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_PERFORMANCE, GL_DONT_CARE, 0, NULL, GL_TRUE); 1349 // But we already identify that some messages are not really useful for us. 1350 std::vector<GLuint> Messages = {5678, 6789}; 1351 glDebugMessageControl( 1352 GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_OTHER, GL_DONT_CARE, 1353 GLuint(Messages,size()), &Messages[0], GL_FALSE); 1354 1355 glDebugMessageInsert( 1356 GL_DEBUG_SOURCE_APPLICATION, 1357 GL_DEBUG_TYPE_PERFORMANCE, 1357, 1358 GL_DEBUG_SEVERITY_MEDIUM, 1359 -1, "Message 2"); 1360 glDebugMessageInsert( 1361 GL_DEBUG_SOURCE_THIRD_PARTY, // We still filter out these messages. 1362 GL_DEBUG_TYPE_OTHER, 3579, 1363 GL_DEBUG_SEVERITY_MEDIUM, 1364 -1, "Message 3"); 1365 1366 glPopDebugGroup(); 1367 1368 // Expected debug output from the GL implementation 1369 // Message 2 1370 1371 1372Issues 1373 1374 (1) Should the extension provides a method for querying markers? 1375 1376 RESOLVED: No. 1377 1378 1379 (2) Is the concept of <severity> meaningful for most profiling use cases? 1380 1381 DISCUSSION: The debug output API was originally designed for debugging 1382 but its design has led implementation and application to use 1383 it for profiling. Furthermore, markers are not strictly 1384 speaking low, medium or high severity messages. 1385 1386 RESOLVED: Added DEBUG_SEVERITY_NOTIFICATION 1387 1388 1389 (3) How should an implementation behave when the application doesn't push 1390 and pop group markers evenly? 1391 1392 DISCUSSION: Extra "pop" may be ignored as it is done in OpenGL ES 1393 EXT_debug_marker but what to do if the user push too many 1394 time? In any case, if a software doesn't push and pop evenly, 1395 its design is pretty ill. Hence it is better to notify the 1396 application as soon as possible by generating an error. 1397 1398 OpenGL legacy handles this problem by limiting the size of the 1399 stacks and generating STACK_UNDERFLOW and STACK_OVERFLOW 1400 errors. 1401 1402 The size of the marker group stack need to be big enough so 1403 that the application won't be limited but small enough so that 1404 an error is generated soon when pushes and pops are not even. 1405 1406 Another option is to let the drivers workaround this issue by 1407 ignoring push commands for a full stack and pop commands for 1408 an empty stack. In such case, an application doesn't have an 1409 immediate feedback for this behavior. 1410 1411 RESOLVED: Generates STACK_UNDERFLOW or STACK_UNDERFLOW errors 1412 1413 1414 (4) Do we need a maximum length for a marker string? 1415 1416 RESOLVED: No, reuse MAX_DEBUG_MESSAGE_LENGTH 1417 1418 1419 (5) Can we use this new extension to allow applications to request the 1420 info logs from compiling, linking and validating to be automatically 1421 submitted to the debug output log and debug output call-back function? 1422 1423 DISCUSSION: The API may need a new <type> value DEBUG_TYPE_INFO_LOG 1424 for every kind of info logs. glLinkProgram, glCompileShader, 1425 glCreateShaderProgram, glValidateProgram and 1426 glValidateProgramPipeline, which execution generate the info 1427 logs, could also automatically submit this logs the the debug 1428 output API. 1429 1430 Such strategy can already be apply by querying the info log 1431 manually and submitting it to the debug output API with 1432 DebugMessageInsert but on some implementations querying the 1433 log immediately after the operation may significantly slow 1434 down the general compilation of shaders process. 1435 1436 The mechanism could be enable with glEnable with a dedicated 1437 value (DEBUG_OUTPUT_INFO_LOG). When enable, an option is 1438 that shader, program and program pipeline would not have to 1439 maintain this log. 1440 1441 This perspective emphasis the centralised nature of OpenGL 1442 debugging to the debug output API. 1443 1444 RESOLVED: Nothing prevent an implementation implementing ARB_debug_output 1445 to do it already. 1446 1447 1448 (6) Should we use dedicated functions for pushing and popping the group 1449 marker stack or use DebugMessageInsert with a dedicated types? 1450 1451 DISCUSSION: These functions have side effects (causing underflow errors, 1452 causing other messages to become disabled) rather than purely 1453 injecting messages into the debug log. 1454 1455 RESOLVED: Use separated functions. 1456 1457 1458 (7) Should we generate an error when we pop the last entry or when the 1459 stack is empty? 1460 1461 DISCUSSION: For the deprecated stacks, at the beginning of the program the 1462 stack depth was 1 which implies a default debug group (id 0?) 1463 in the present case. 1464 1465 RESOLVED: Let's follow the deprecated stacks precedent. 1466 1467 1468 (8) Should we be able to query the current debug group? 1469 1470 DISCUSSION: ARB_debug_output doesn't provide a query API for debug output 1471 control states, should we follow this precedent or are there 1472 use cases where is could be especially useful? 1473 1474 RESOLVED: No, it doesn't seem very useful. 1475 1476 1477 (9) Should we provide within which debug group a message is generated? 1478 1479 DISCUSSION: Such information might be useful but we would need to add a 1480 parameter to the callback function. Also, the application can 1481 take the responsibility of saving the current active debug 1482 group. Such option avoid API disruption. 1483 1484 RESOLVED: (8) could resolve this issue as well if this is actually at 1485 desired feature. Also nothing prevents an implementation to use 1486 a debug group id to form the debug output message. Finally an 1487 application can always store the current debug group each time 1488 a DEBUG_TYPE_PUSH_GROUP is generated. 1489 1490 1491 (10) Do we need a dedicated mechanism to enable and disable debug outputs? 1492 1493 DISCUSSION: It could seem that using glDebugMessageControl could allow 1494 to disable debug output. However with the introduction of 1495 debug groups, glDebugMessageControl only disable the active 1496 debug group and it could be pretty complex for an application 1497 to ensure that each debug group is disable. A easier idea 1498 would be to be global switch glEnable(GL_DEBUG_OUTPUT) 1499 allowing the application to completely switch on and off the 1500 entire debug output mechanism. 1501 1502 RESOLVED: Issue covered by ARB_debug_output2 1503 1504 1505 (11) Should there be a way to enable and disable the debug output 1506 functionality via glEnable(GL_DEBUG_OUTPUT) in addition to the way 1507 the context is created? This may be useful for third-party or 1508 pre-existing code that doesn't have control over how the context is 1509 created. This could be exposed in addition to the context creation 1510 flag, and the context creation flag just sets the default state of 1511 the enable. 1512 1513 RESOLVED: Yes, based on various feedback this would be useful. Added 1514 to revision 3 of this extension spec. 1515 1516 1517 (12) Should we use a single function to set the label for all objects? 1518 1519 DISCUSSION: This is the approach chosen in OpenGL ES extension 1520 EXT_debug_label. It builds up a new strong precedent 1521 for an important functionality but not exactly one 1522 which purpose is to build a strong design precedent. 1523 1524 On one hand using a unique function for all objects 1525 reduce the number of new entry point from 24 to 2. 1526 1527 RESOLVED: For the purpose of convergence with ES, the groups have 1528 voted for only 2 functions. 1529 1530 1531 (13) Do we need a maximum length (MAX_LABEL_LENGTH) for the label? 1532 1533 DISCUSSION: Following the precedents given by others strings in 1534 OpenGL, this seems useful. On one hand ARB_debug_output 1535 has a maximum size of the debug message 1536 (MAX_DEBUG_MESSAGE_LENGTH), shader variable names have 1537 a maximum length but on other hand the shader source 1538 and the program info log doesn't have such limitation. 1539 However, it seems hard to imagine that implementations 1540 doesn't have limitation somehow. 1541 1542 RESOLVED: Yes 1543 1544 1545 (14) Should we provide a function to label a display list? 1546 1547 RESOLVED: Yes for compatibility profile only. 1548 1549 1550 (15) Should the ES version of this extension supports the message log 1551 or only the callback function? 1552 1553 DISCUSSION: When promoting AMD_debug_output to ARB_debug_output, the ARB 1554 has added a message log that can be query by the application 1555 if no callback function has been specified by the application. 1556 The purpose of this addition was to support remote rendering. 1557 Is remote rendering supported by OpenGL ES? The ES group 1558 typically wants to have only one way to do things, should we 1559 only support the callback function for ES debug output? 1560 1561 RESOLVED: The ES group has chosen to keep it by vote 1562 1563 1564 (16) Why do OpenGL implementations use KHR suffixes, while OpenGL 1565 implementations use no suffix? 1566 1567 DISCUSSION: this functionality was initially defined by OpenGL 4.3, and 1568 set of "backwards compatibility" extensions were defined to allow 1569 implementing it against earlier GL versions. OpenGL ARB policy in the 1570 case of backwards compatibility extensions is that extension suffixes 1571 should not be added. The OpenGL ES Working Group then decided to support 1572 the same functionality as an OpenGL ES extension, and both groups agreed 1573 to share a single KHR specification for the extension. However, OpenGL 1574 ES policy requires extension suffixes on Khronos-approved OES and KHR 1575 extensions. 1576 1577 We are aware of this inconsistency, but both working groups have chosen 1578 to stand by their own naming policies and the inconsistency is unlikely 1579 to be resolved. 1580 1581Revision History 1582 1583 Revision 17, 2015/07/02 (Jan-Harald Fredriksen) 1584 - Clarify CONTEXT_FLAGS state for ES3.1 and earlier in the Interactions 1585 section (Bug 13104). 1586 1587 Revision 16, 2015/03/11 (Jon Leech) 1588 - Clarify dependencies required to support PROGRAM_PIPELINE (Bug 1589 13545). 1590 1591 Revision 15, 2014/03/04 (Jon Leech) 1592 - Minor changes to clean up expected message output format in example 1593 code and refer to the value of state named by tokens, rather than 1594 the token values themselves (Bug 10083). 1595 1596 Revision 14, 2013/11/05 (Jon Leech) 1597 - Edit state tables to replace the "Get Value" of LABEL with "-", 1598 indicating unnamed state. There is no token LABEL in the extension, 1599 and the GetObject*Label commands do not take <pname> parameters (Bug 1600 11131). 1601 1602 Revision 13, 2013/06/24 (Jon Leech) 1603 - Add 'const' attribute to <userParam> for DebugMessageCallback and 1604 the corresponding GLDEBUGPROC type. Specify that unrecognized 1605 message IDs are ignored in the DebugMessageControl <ids> array. 1606 Specify that GetDebugMessageLog <messageLog> parameter must be 1607 NULL when <bufSize> is less than zero, to allow an early out. 1608 Replace spurious GLvoid with void. (Bug 10083). 1609 1610 Revision 12, 2013/06/15 (Jon Leech) 1611 - Clarify in the New Tokens section that the <source> parameter of 1612 some commands may not allow all possible values shown in this 1613 section (public Bug 889). 1614 1615 Revision 11, 2013/04/26 (Jon Leech) 1616 - Implement OpenGL ES policy of adding KHR suffixes to all KHR 1617 extensions. Add notes, OpenGL ES Interaction section, and issue 16 1618 explaining the situation (Bug 9716). 1619 1620 Revision 10, 2013/04/16 (Jon Leech) 1621 - Fix type of <ids> parameter in GetDebugMessageLog body (Bug 10083) 1622 1623 Revision 9, 2012/09/18 (pbrown) 1624 - Add a "void" function argument list for PopDebugGroup(). The GLEW 1625 library needs this to properly parse the extension spec file. 1626 1627 Revision 8, 2012/09/16 (Jon Leech) 1628 - Add existing tokens allowed for ObjectLabel identifiers to "New 1629 Tokens" section, without enum values since they aren't actually new 1630 (Bug 9506). 1631 1632 Revision 7, 2012/09/12 (Jon Leech) 1633 - Clarify description of DebugMessageControl parameters to avoid 1634 triple negatives (Bug 9392). 1635 1636 Revision 6, 2012/07/31 (criccio) 1637 - ObjectLabel generates an INVALID_VALUE error if <name> 1638 doesn't identify a valid object. 1639 1640 Revision 5, 2012/06/22 (criccio) 1641 - Resolved issue 15 1642 1643 Revision 4, 2012/06/19 (Jon Leech) 1644 - Change logSize parameter to bufSize 1645 1646 Revision 3, 2012/06/12 (criccio) 1647 - Added ObjectPtrLabel and GetObjectPtrLabel (bug 9140) 1648 1649 Revision 2, 2012/06/07 (criccio) 1650 - Updated overview for higher consistence of the language. 1651 - Clarified when the message is generated by the GL when popping 1652 a debug group. 1653 1654 Revision 1, 2012/06/04 (criccio) 1655 - First draft, merged GL_ARB_debug_output, GL_ARB_debug_output2, 1656 GL_ARB_debug_group and GL_ARB_debug_label. 1657 1658