1Name 2 3 ARB_debug_output 4 5Name Strings 6 7 GL_ARB_debug_output 8 9Contact 10 11 Jaakko Konttinen (jaakko.konttinen 'at' amd.com) 12 13Contributors 14 15 Graham Sellers, AMD 16 Mark Young, AMD 17 Ahmet Oguz Akyuz, AMD 18 Bruce Merry, ARM 19 Daniel Koch, TransGaming 20 Jon Leech, Independent 21 Pat Brown, NVIDIA 22 Greg Roth, NVIDIA 23 Yaki Tebeka, Graphic Remedy 24 25Notice 26 27 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 28 http://www.khronos.org/registry/speccopyright.html 29 30Specification Update Policy 31 32 Khronos-approved extension specifications are updated in response to 33 issues and bugs prioritized by the Khronos OpenGL Working Group. For 34 extensions which have been promoted to a core Specification, fixes will 35 first appear in the latest version of that core Specification, and will 36 eventually be backported to the extension document. This policy is 37 described in more detail at 38 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 39 40Status 41 42 Complete. Approved by the ARB on June 9, 2010. 43 Approved by the Khronos Board of Promoters on July 23, 2010. 44 45Version 46 47 Last Modified Date: July 8, 2013 48 Author Revision: 17 49 50Number 51 52 ARB Extension #104 53 54Dependencies 55 56 OpenGL 1.1 is required. 57 58 The extension is written against the OpenGL 4.0 Core specification 59 (March 11, 2010). 60 61 The extension interacts with OpenGL 4.0 Compatibility specification 62 and other specifications that provide display list support. 63 64 The extension interacts with OpenGL 4.0 Compatibility specification 65 and other specifications that provide the GetPointerv entry point. 66 67Overview 68 69 This extension allows the GL to notify applications when various 70 events occur that may be useful during application development and 71 debugging. 72 73 These events are represented in the form of enumerable messages with 74 a human-readable string representation. Examples of debug events 75 include incorrect use of the GL, warnings of undefined behavior, and 76 performance warnings. 77 78 A message is uniquely identified by a source, a type and an 79 implementation-dependent ID within the source and type pair. 80 81 A message's source identifies the origin of the message and can 82 either describe components of the GL, the window system, 83 third-party external sources such as external debuggers, or even 84 the application itself. 85 86 The type of the message roughly identifies the nature of the event 87 that caused the message. Examples include errors, performance 88 warnings, or warnings about undefined behavior. 89 90 A message's ID for a given source and type further 91 distinguishes messages within those groups. For example, an error 92 caused by a negative parameter value or an invalid internal 93 texture format are both errors generated by the API, but would 94 likely have different message IDs. 95 96 Each message is also assigned to a severity level that denotes 97 roughly how "important" that message is in comparison to other 98 messages across all sources and types. For example, notification 99 of a GL error would likely have a higher severity than a performance 100 warning due to redundant state changes. 101 102 Finally, every message contains an implementation-dependent string 103 representation that provides a useful description of the event. 104 105 Messages are communicated to the application through an application- 106 defined callback function that is called by the GL implementation on 107 each debug message. The motivation for the callback routine is to 108 free application developers from actively having to query whether 109 a GL error, or any other debuggable event has happened after each 110 call to a GL function. With a callback, developers can keep their 111 code free of debug checks, and only have to react to messages as 112 they occur. In situations where using a callback is not possible, 113 a message log is also provided that stores copies of recent messages 114 until they are actively queried. 115 116 To control the volume of debug output, messages can be disabled 117 either individually by ID, or entire groups of messages can be 118 turned off based on combination of source and type. 119 120 The only requirement on the minimum quantity and type of messages 121 that implementations of this extension must support is that some 122 sort of message must be sent notifying the application whenever any 123 GL error occurs. Any further messages are left to the 124 implementation. Implementations do not have to output messages from 125 all sources nor do they have to use all types of messages listed 126 by this extension, and both new sources and types can be added by 127 other extensions. 128 129 For performance reasons it is recommended, but not required, that 130 implementations restrict supporting this extension only to 131 contexts created using the debug flag as provided by 132 WGL_create_context or GLX_create_context. This extension places no 133 limits on any other functionality provided by debug contexts through 134 other extensions. 135 136IP Status 137 138 No known IP claims. 139 140New Procedures and Functions 141 142 void DebugMessageControlARB(enum source, 143 enum type, 144 enum severity, 145 sizei count, 146 const uint* ids, 147 boolean enabled); 148 149 void DebugMessageInsertARB(enum source, 150 enum type, 151 uint id, 152 enum severity, 153 sizei length, 154 const char* buf); 155 156 void DebugMessageCallbackARB(DEBUGPROCARB callback, 157 const void* userParam); 158 159 uint GetDebugMessageLogARB(uint count, 160 sizei bufSize, 161 enum* sources, 162 enum* types, 163 uint* ids, 164 enum* severities, 165 sizei* lengths, 166 char* messageLog); 167 168 void GetPointerv(enum pname, 169 void** params); 170 171New Types 172 173 The callback function that applications can define, and 174 is accepted by DebugMessageCallbackARB, is defined as: 175 176 typedef void (APIENTRY *DEBUGPROCARB)(enum source, 177 enum type, 178 uint id, 179 enum severity, 180 sizei length, 181 const char* message, 182 const void* userParam); 183 184 Note that this function pointer is defined as having the 185 same calling convention as the GL functions. 186 187New Tokens 188 189 Tokens accepted by the <target> parameters of Enable, Disable, 190 and IsEnabled: 191 192 DEBUG_OUTPUT_SYNCHRONOUS_ARB 0x8242 193 194 Tokens accepted by the <value> parameters of GetBooleanv, 195 GetIntegerv, GetFloatv, and GetDoublev: 196 197 MAX_DEBUG_MESSAGE_LENGTH_ARB 0x9143 198 MAX_DEBUG_LOGGED_MESSAGES_ARB 0x9144 199 DEBUG_LOGGED_MESSAGES_ARB 0x9145 200 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB 0x8243 201 202 Tokens accepted by the <pname> parameter of GetPointerv: 203 204 DEBUG_CALLBACK_FUNCTION_ARB 0x8244 205 DEBUG_CALLBACK_USER_PARAM_ARB 0x8245 206 207 Tokens accepted or provided by the <source> parameters of 208 DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, 209 and the <sources> parameter of GetDebugMessageLogARB: 210 211 DEBUG_SOURCE_API_ARB 0x8246 212 DEBUG_SOURCE_WINDOW_SYSTEM_ARB 0x8247 213 DEBUG_SOURCE_SHADER_COMPILER_ARB 0x8248 214 DEBUG_SOURCE_THIRD_PARTY_ARB 0x8249 215 DEBUG_SOURCE_APPLICATION_ARB 0x824A 216 DEBUG_SOURCE_OTHER_ARB 0x824B 217 218 Tokens accepted or provided by the <type> parameters of 219 DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB, 220 and the <types> parameter of GetDebugMessageLogARB: 221 222 DEBUG_TYPE_ERROR_ARB 0x824C 223 DEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB 0x824D 224 DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARB 0x824E 225 DEBUG_TYPE_PORTABILITY_ARB 0x824F 226 DEBUG_TYPE_PERFORMANCE_ARB 0x8250 227 DEBUG_TYPE_OTHER_ARB 0x8251 228 229 Tokens accepted or provided by the <severity> parameters of 230 DebugMessageControlARB, DebugMessageInsertARB and DEBUGPROCARB 231 callback functions, and the <severities> parameter of 232 GetDebugMessageLogARB: 233 234 DEBUG_SEVERITY_HIGH_ARB 0x9146 235 DEBUG_SEVERITY_MEDIUM_ARB 0x9147 236 DEBUG_SEVERITY_LOW_ARB 0x9148 237 238Additions to Chapter 2 of the OpenGL 4.0 Core Specification 239(OpenGL Operation) 240 241 In section 2.5 - GL Errors: 242 Add to the end of the section (pg 19): 243 244 "When an error is generated, the GL will also generate a debug 245 output message describing its cause (see section 5.5). The message 246 has the source DEBUG_SOURCE_API_ARB and the type 247 DEBUG_TYPE_ERROR_ARB, and an implementation-dependent ID." 248 249Additions to Chapter 3 of the OpenGL 4.0 Core Specification 250(Rasterization) 251 252 None. 253 254Additions to Chapter 4 of the OpenGL 4.0 Core Specification 255(Per-Fragment Operations and the Frame Buffer) 256 257 None. 258 259Additions to Chapter 5 of the OpenGL 4.0 Core Specification 260(Special Functions) 261 262 After section 5.4 - Hints (pg. 300), add new section: 263 264 "5.5 - Debug Output 265 266 Application developers can obtain more information from the GL 267 runtime in the form of debug output. This information can include 268 details about GL errors, undefined behavior, implementation- 269 dependent performance warnings, or other useful hints. 270 271 This information is communicated through a stream of debug 272 messages that are generated as GL commands are executed. The 273 application can choose to receive these messages either through a 274 callback routine, or by querying for them from a message log. 275 276 Controls are provided for disabling messages that the 277 application does not care about, and for inserting application- 278 generated messages into the stream. 279 280 5.5.1 - Debug Messages 281 282 A debug message is uniquely identified by the source that generated 283 it, a type within that source, and an unsigned integer ID 284 identifying the message within that type. The message source is 285 one of the symbolic constants listed in Table 5.3. The message 286 type is one of the symbolic constants listed in Table 5.4. 287 288 Debug Output Message Source Messages Generated by 289 --------------------------- --------------------- 290 DEBUG_SOURCE_API_ARB The GL 291 292 DEBUG_SOURCE_SHADER_COMPILER_ARB The GLSL shader compiler or compilers for 293 other extension-provided languages 294 295 DEBUG_SOURCE_WINDOW_SYSTEM_ARB The window system, such as WGL or GLX 296 297 DEBUG_SOURCE_THIRD_PARTY_ARB External debuggers or third-party middleware 298 libraries 299 300 DEBUG_SOURCE_APPLICATION_ARB The application 301 302 DEBUG_SOURCE_OTHER_ARB Sources that do not fit to any of the ones listed above 303 ---------------------------------------------------------------------------- 304 Table 5.3: Sources of debug output messages. Each message must originate 305 from a source listed in this table. 306 307 308 Debug Output Message Type Informs about 309 ------------------------- ------------- 310 DEBUG_TYPE_ERROR_ARB Events that generated an error 311 312 DEBUG_TYPE_DEPRECATED_BEHAVIOR_ARB Behavior that has been marked for 313 deprecation 314 315 DEBUG_TYPE_UNDEFINED_BEHAVIOR_ARB Behavior that is undefined according to 316 the specification 317 318 DEBUG_TYPE_PERFORMANCE_ARB Implementation-dependent performance 319 warnings 320 321 DEBUG_TYPE_PORTABILITY_ARB Use of extensions or shaders in a way that 322 is highly vendor-specific 323 324 DEBUG_TYPE_OTHER_ARB Types of events that do not fit any of 325 the ones listed above 326 327 ---------------------------------------------------------------------------- 328 Table 5.4: Types of debug output messages. Each message is associated with 329 one of these types that describes the nature of the message. 330 331 Each message source and type pair contains its own namespace of 332 messages with every message being associated with an ID. The 333 assignment of IDs to messages within a namespace is implementation- 334 dependent. There can potentially be overlap between the namespaces 335 of two different pairs of source and type, so messages can only be 336 uniquely distinguished from each other by the full combination of 337 source, type and ID. 338 339 Each message is also assigned a severity level that roughly 340 describes its importance across all sources and types along a 341 single global axis. The severity of a message is one of the 342 symbolic constants defined in Table 5.5. Because messages can be 343 disabled by their severity, this allows for quick control the global 344 volume of debug output. 345 346 Severity Level Token Suggested examples of messages 347 -------------------- ------------------------------ 348 349 DEBUG_SEVERITY_HIGH_ARB Any GL error; dangerous undefined behavior; 350 any GLSL or ARB shader compiler and 351 linker errors; 352 353 DEBUG_SEVERITY_MEDIUM_ARB Severe performance warnings; GLSL 354 or other shader compiler and linker 355 warnings; use of currently deprecated 356 behavior 357 358 DEBUG_SEVERITY_LOW_ARB Performance warnings from redundant 359 state changes; trivial undefined behavior 360 ---------------------------------------------------------------------------- 361 Table 5.5: Severity levels of messages. Each debug output message is 362 associated with one of these severity levels. 363 364 365 Every message also has a null-terminated string representation that 366 is used to describe the message. The contents of the string can 367 change slightly between different instances of the same message 368 (e.g. which parameter value caused a specific GL error to occur). 369 The format of a message string is left as implementation-dependent, 370 although it should at least represent a concise description of the 371 event that caused the message to be generated. Messages with 372 different IDs should also have sufficiently distinguishable string 373 representations to warrant their separation. 374 375 The lengths of all messages, including their null terminators, must 376 be guaranteed to be less or equal to the implementation-dependent 377 constant MAX_DEBUG_MESSAGE_LENGTH_ARB. 378 379 Messages can be either enabled or disabled. Messages that are 380 disabled will not be generated. All messages are initially enabled 381 unless their assigned severity is DEBUG_SEVERITY_LOW_ARB. The 382 enabled state of messages can be changed using the command 383 DebugMessageControlARB. 384 385 5.5.2 - Debug Message Callback 386 387 Applications can provide a callback function for receiving debug 388 messages using the command 389 390 void DebugMessageCallbackARB(DEBUGPROCARB callback, 391 const void* userParam); 392 393 with <callback> storing the address of the callback function. This 394 function's prototype must follow the type definition of 395 DEBUGPROCARB including its platform-dependent calling convention. 396 Anything else will result in undefined behavior. Only one debug 397 callback can be specified for the current context, and further calls 398 overwrite the previous callback. Specifying NULL as the value of 399 <callback> clears the current callback and disables message output 400 through callbacks. Applications can provide user-specified data 401 through the pointer <userParam>. The context will store this 402 pointer and will include it as one of the parameters in each call to 403 the callback function. 404 405 If the application has specified a callback function for receiving 406 debug output, the implementation will call that function whenever 407 any enabled message is generated. The source, type, ID, and 408 severity of the message are specified by the DEBUGPROCARB parameters 409 <source>, <type>, <id>, and <severity>, respectively. The string 410 representation of the message is stored in <message> and its length 411 (excluding the null-terminator) is stored in <length>. The 412 parameter <userParam> is the user-specified parameter that was given 413 when calling DebugMessageCallbackARB. 414 415 Applications can query the current callback function and 416 the current user-specified parameter by obtaining the values of 417 DEBUG_CALLBACK_FUNCTION_ARB and DEBUG_CALLBACK_USER_PARAM_ARB, 418 respectively. 419 420 Applications that specify a callback function must be aware of 421 certain special conditions when executing code inside a callback 422 when it is called by the GL, regardless of the debug source. 423 424 The memory for <message> is owned and managed by the GL, and should 425 only be considered valid for the duration of the function call. 426 427 The behavior of calling any GL or window system function 428 from within the callback function is undefined and may lead to 429 program termination. 430 431 Care must also be taken in securing debug callbacks for use with 432 asynchronous debug output by multi-threaded GL implementations. 433 Section 5.5.6 describes this in further detail. 434 435 5.5.3 - Debug Message Log 436 437 If DEBUG_CALLBACK_FUNCTION_ARB is NULL, then debug messages are 438 instead stored in an internal message log up to some maximum number 439 of messages as defined by the value of 440 MAX_DEBUG_LOGGED_MESSAGES_ARB. 441 442 Each context stores its own message log and will only store messages 443 generated by commands operating in that context. If the message log 444 fills up, then any subsequently generated messages will not be 445 placed in the log until the message log is cleared, and will instead 446 be discarded. 447 448 Applications can query the number of messages currently in the 449 log by obtaining the value of DEBUG_LOGGED_MESSAGES_ARB, and the 450 string length (including its null terminator) of the oldest message 451 in the log through the value of 452 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB. 453 454 To fetch message data stored in the log, the command 455 GetDebugMessageLogARB can be used. 456 457 If DEBUG_CALLBACK_FUNCTION_ARB is not NULL, no generated messages 458 will be stored in the log but will instead be passed to the 459 debug callback routine as described in section 5.5.2. 460 461 5.5.4 - Controlling Debug Messages 462 463 Applications can control the volume of debug output by disabling 464 specific or groups of messages with the command: 465 466 void DebugMessageControlARB(enum source, 467 enum type, 468 enum severity, 469 sizei count, 470 const uint* ids, 471 boolean enabled); 472 473 If <enabled> is TRUE, the referenced subset of messages will be 474 enabled. If FALSE, then those messages will be disabled. 475 476 This command can reference different subsets of messages by first 477 considering the set of all messages, and filtering out messages 478 based on the following ways: 479 480 - If <source> is not DONT_CARE, then all messages whose source 481 does not match <source> will not be referenced. 482 483 - If <type> is not DONT_CARE, then all messages whose type does 484 not match <type> will not be referenced. 485 486 - If <severity> is not DONT_CARE, then all messages whose 487 severity level does not match <severity> will not be 488 referenced. 489 490 - If <count> is greater than zero, then <ids> is an array of 491 <count> message IDs for the specified combination of 492 <source> and <type>. In this case, if <source> or <type> 493 is DONT_CARE, or <severity> is not DONT_CARE, the error 494 INVALID_OPERATION is generated. If <count> is zero, the 495 value if <ids> is ignored. 496 497 In addition, if any of <source>, <type>, and <severity> is not 498 DONT_CARE and is not one of the symbols from, respectively, Table 499 5.3, Table 5.4, and Table 5.5, the error INVALID_ENUM is 500 generated. If <count> is negative, the error INVALID_VALUE is 501 generated. 502 503 Although messages are grouped into an implicit hierarchy by their 504 sources and types, there is no explicit per-source, per-type or 505 per-severity enabled state. Instead, the enabled state is stored 506 individually for each message. There is no difference between 507 disabling all messages from one source in a single call, and 508 individually disabling all messages from that source using their 509 types and IDs. 510 511 5.5.5 - Externally Generated Messages 512 513 To support applications and third-party libraries generating their 514 own messages, such as ones containing timestamp information or 515 signals about specific render system events, the following function 516 can be called 517 518 void DebugMessageInsertARB(enum source, 519 enum type, 520 uint id, 521 enum severity, 522 int length, 523 const char* buf); 524 525 The value of <id> specifies the ID for the message and <severity> 526 indicates its severity level as defined by the caller. If 527 <severity> is not one of the severity levels listed in Table 5.5, 528 the error INVALID_ENUM will be generated. The value of <type> 529 must be one of the values from Table 5.4 and the value of <source> 530 must be either DEBUG_SOURCE_APPLICATION_ARB or 531 DEBUG_SOURCE_THIRD_PARTY_ARB, or the error INVALID_ENUM will be 532 generated. The string <buf> contains the string representation of 533 the message. The parameter <length> contains the number of 534 characters in <buf>. If <length> is negative, it is implied that 535 <buf> contains a null terminated string. The error INVALID_VALUE 536 will be generated if the number of characters in <buf>, excluding 537 the null terminator when <length> is negative, is not less than 538 MAX_DEBUG_MESSAGE_LENGTH_ARB. 539 540 5.5.6 - Asynchronous and Synchronous Debug Output 541 542 The behavior of how and when the GL driver is allowed to generate 543 debug messages, and subsequently either call back to the application 544 or place the message in the debug message log, is affected by 545 the state DEBUG_OUTPUT_SYNCHRONOUS_ARB. This state can be modified 546 by the Enable and Disable commands. Its initial value is FALSE. 547 548 When DEBUG_OUTPUT_SYNCHRONOUS_ARB is disabled, the 549 driver is optionally allowed to concurrently call the debug callback 550 routine from potentially multiple threads, including threads that 551 the context that generated the message is not currently bound to. 552 The implementation may also call the callback routine asynchronously 553 after the GL command that generated the message has already 554 returned. The application is fully responsible for ensuring thread 555 safety due to debug callbacks under these circumstances. In this 556 situation the <userParam> value may be helpful in identifying which 557 application thread's command originally generated the debug 558 callback. 559 560 When DEBUG_OUTPUT_SYNCHRONOUS_ARB is enabled, the 561 driver guarantees synchronous calls to the callback routine 562 by the context. When synchronous callbacks are enabled, 563 all calls to the callback routine will be made by the thread 564 that owns the current context; all such calls will be made 565 serially by the current context; and each call will be made 566 before the GL command that generated the debug message is allowed to 567 return. 568 569 When no callback is specified and DEBUG_OUTPUT_SYNCHRONOUS_ARB 570 is disabled, the driver can still asynchronously place messages 571 in the debug message log, even after the context thread has 572 returned from the GL function that generated those messages. When 573 DEBUG_OUTPUT_SYNCHRONOUS_ARB is enabled, the driver guarantees that 574 all messages are added to the log before the GL function returns. 575 576 Enabling synchronous debug output greatly simplifies the 577 responsibilities of the application for making its callback 578 functions thread-safe, but may potentially result in drastically 579 reduced driver performance. 580 581 The DEBUG_OUTPUT_SYNCHRONOUS_ARB only guarantees 582 intra-context synchronization for the callbacks of messages 583 generated by that context, and does not guarantee synchronization 584 across multiple contexts. If multiple contexts are concurrently 585 used by the application, it is allowed for those contexts to 586 also concurrently call their designated callbacks, and the 587 application is responsible for handling thread safety in that 588 situation even if DEBUG_OUTPUT_SYNCHRONOUS_ARB is enabled 589 in all contexts." 590 591Additions to Chapter 6 of the OpenGL 4.0 Core Specification 592(State and State Requests) 593 594 Modify the title of Section 6.1.6 - String Queries to read 595 "Section 6.1.6 - Pointer and String Queries", and insert to the 596 beginning of the section: 597 598 The command 599 600 void GetPointerv(enum pname, void** params); 601 602 obtains the pointer or pointers named <pname> in the array <params>. 603 The possible values for <pname> are DEBUG_CALLBACK_FUNCTION_ARB and 604 DEBUG_CALLBACK_USER_PARAM_ARB, which respectively return the current 605 debug output callback function pointer and its application-specified 606 user parameter. Each <pname> returns a single pointer value. 607 608 After Section 6.1.14 - Renderbuffer Object Queries (pg 324): 609 Add new Section 6.1.15 - Debug Object Queries: 610 611 6.1.15 - Debug Output Queries 612 613 When no debug callback is set, debug messages are stored in 614 a debug message log as described in section 5.5.3. Messages can 615 be queried from the log by calling 616 617 uint GetDebugMessageLogARB(uint count, 618 sizei bufSize, 619 enum* sources, 620 enum* types, 621 uint* ids, 622 enum* severities, 623 sizei* lengths, 624 char* messageLog); 625 626 This function fetches a maximum of <count> messages from the message 627 log, and will return the number of messages successfully fetched. 628 629 Messages will be fetched from the log in order of oldest to 630 newest. Those messages that were fetched will be removed from the 631 log. 632 633 The sources, types, severities, IDs, and string lengths of 634 fetched messages will be stored in the application-provided arrays 635 <sources>, <types>, <severities>, <ids>, and <lengths>, 636 respectively. The application is responsible for allocating enough 637 space for each array to hold up to <count> elements. The string 638 representations of all fetched messages are stored in the 639 <messageLog> array. If multiple messages are fetched, their strings 640 are concatenated into the same <messageLog> array and will be 641 separated by single null terminators. The last string in the array 642 will also be null-terminated. The maximum size of <messageLog>, 643 including the space used by all null terminators, is given by 644 <bufSize>. If <bufSize> is less than zero, the error INVALID_VALUE 645 will be generated. If a message's string, including its null 646 terminator, can not fully fit within the <messageLog> array's 647 remaining space, then that message and any subsequent messages will 648 not be fetched and will remain in the log. The string lengths 649 stored in the array <lengths> include the space for the null 650 terminator of each string. 651 652 Any or all of the arrays <sources>, <types>, <ids>, <severities>, 653 <lengths> and <messageLog> can also be null pointers, which causes 654 the attributes for such arrays to be discarded when messages 655 are fetched, however those messages will still be removed from the 656 log. Thus to simply delete up to <count> messages from the message 657 log while ignoring their attributes, the application can call the 658 function with null pointers for all attribute arrays. If 659 <messageLog> is NULL, the value of <bufSize> is ignored. 660 661Additions to the OpenGL / GLX / GLX Protocol Specifications 662 663 None. 664 665Additions to the WGL Specification 666 667 None. 668 669Dependencies on GL and ES profiles, versions, and other extensions 670 671 Dependencies on OpenGL 4.0 Compatibility specification and any other 672 versions or extensions that already provide the GetPointerv entry 673 point as provided by the OpenGL 4.0 Compatibility specification 674 675 - Remove the modifications to Section 6.1.6 from this 676 specification with the exception that GetPointerv will still 677 accept DEBUG_CALLBACK_FUNCTION_ARB and 678 DEBUG_CALLBACK_USER_PARAM_ARB as valid values for <pname>, 679 and will return the same values as described in Chapter 6. 680 681 Dependencies on OpenGL 4.0 Compatibility specification and any other 682 versions that support display lists 683 684 - DebugMessageControlARB, DebugMessageInsertARB, 685 DebugMessageCallbackARB, and GetDebugMessageLogARB are 686 not compiled into display lists. 687 688 Add the following to section 5.5.1 of the OpenGL 4.0 689 Compatibility specification, after the paragraph beginning 690 with "GL command stream management" (pg 414): 691 692 "Debug output: DebugMessageControlARB, 693 DebugMessageInsertARB, DebugMessageCallbackARB, and 694 GetDebugMessageLogARB" 695 696 Add the same language to corresponding sections of other 697 specifications. 698 699Errors 700 701 The error INVALID_ENUM will be generated by DebugMessageControlARB 702 if <source> is not DONT_CARE or one of the debug output sources 703 listed in Table 5.3. 704 705 The error INVALID_ENUM will be generated by DebugMessageControlARB 706 if <type> is not DONT_CARE or one of the debug output types listed 707 in Table 5.4. 708 709 The error INVALID_ENUM will be generated by DebugMessageControlARB 710 if <severity> is not DONT_CARE or one of the severity levels listed 711 in Table 5.5. 712 713 The error INVALID_VALUE will be generated by DebugMessageControlARB 714 if <count> is less than zero. 715 716 The error INVALID_OPERATION will be generated by 717 DebugMessageControlARB when <count> is greater than zero and 718 <source> is DONT_CARE. 719 720 The error INVALID_OPERATION will be generated by 721 DebugMessageControlARB when <count> is greater than zero and 722 <type> is DONT_CARE. 723 724 The error INVALID_OPERATION will be generated by 725 DebugMessageControlARB when <count> is greater than zero and 726 and <severity> is not DONT_CARE. 727 728 The error INVALID_VALUE will be generated by GetDebugMessageLogARB 729 if the value of <count> is less than zero. 730 731 The error INVALID_VALUE will be generated by GetDebugMessageLogARB 732 if <bufSize> is less than zero. 733 734 The error INVALID_ENUM will be generated by DebugMessageInsertARB if 735 the value of <source> is not DEBUG_SOURCE_APPLICATION_ARB or 736 DEBUG_SOURCE_THIRD_PARTY_ARB. 737 738 The error INVALID_ENUM will be generated by DebugMessageInsertARB if 739 the value of <type> is not one of the values from Table 5.4. 740 741 The error INVALID_ENUM will be generated by DebugMessageInsertARB if 742 <severity> is not a valid debug severity level listed in Table 5.5. 743 744 The error INVALID_VALUE will be generated by DebugMessageInsertARB 745 if the number of characters in <buf>, excluding the null terminator 746 when <length> is negative, is not less than 747 MAX_DEBUG_MESSAGE_LENGTH_ARB. 748 749New State 750 751 Add new table 6.55 after p.376 (Debug Output): 752 753 Initial 754 Get Value Type Get Command Value Description Sec Attribute 755 -------------------------- ---- ----------- ----- ------------------------- ------ --------- 756 DEBUG_CALLBACK_FUNCTION_ARB Y GetPointerv NULL The current debug output 5.5.2 - 757 callback function pointer 758 759 DEBUG_CALLBACK_USER_PARAM_ARB Y GetPointerv NULL The current debug output 5.5.2 - 760 callback user parameter 761 762 DEBUG_LOGGED_MESSAGES_ARB Z+ GetIntegerv 0 The number of messages 5.5.3 - 763 currently in the debug 764 message log 765 766 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB Z+ GetIntegerv 0 The string length of the 5.5.3 - 767 oldest debug message in 768 the debug message log 769 770 DEBUG_OUTPUT_SYNCHRONOUS_ARB B IsEnabled FALSE The enabled state for 5.5.6 771 synchronous debug message 772 callbacks 773 774New Implementation Dependent State 775 776 Add new table 6.56 after table 6.55 (Implementation Dependent Debug Output Values): 777 Minimum 778 Get Value Type Get Command Value Description Sec Attribute 779 -------------------------------- -- ----------- ----- ------------------------- ------ --------- 780 MAX_DEBUG_MESSAGE_LENGTH_ARB Z+ GetIntegerv 1 The maximum length of a 5.5.1 - 781 debug message string, 782 including its null 783 terminator 784 785 MAX_DEBUG_LOGGED_MESSAGES_ARB Z+ GetIntegerv 1 The maximum number of 5.5.3 - 786 messages stored in the 787 debug message log 788 789Issues 790 791 01) Should we reserve tokens for arbitrary vendor-specific 792 categories (e.g. DEBUG_CATEGORY_VENDOR0)? 793 794 RESOLVED: No. Since this is an ARB extension, there is no 795 reason to do this now in the current version. 796 797 798 02) Should we allow explicit controls for printing to stderr or 799 through OutputDebugString instead of the callback? 800 801 RESOLVED: No. It is up to the application to setup this 802 behavior itself using the provided functionality. 803 804 805 03) How do the different filtering rules interact? If a category is 806 filtered, but a message in that same category is set to be 807 unfiltered by ID or severity level, should that message still be 808 filtered? If I specifically filter a category and then unfilter 809 all messages globally with a later command, should that category 810 still be filtered? 811 812 RESOLVED: Message enable state is stored individually for each 813 message. There is no explicit group-wise enable 814 state or different ordered levels of "enabledness" in 815 the implied hierarchy of messages. Operations on 816 groups of messages affect all messages within 817 that group individually, and overwrite the previous 818 and individual state of those messages. 819 820 04) Should applications be allowed to insert their own messages 821 through a custom category? How would this be done? 822 823 RESOLVED: Yes. A new category will be provided for 824 application-specific messages and an entry point will 825 be provided to write messages in that category. 826 827 05) Should we provide a mechanism to ensure synchronized calls of 828 the debug output callback by the implementation? 829 830 RESOLVED: Yes. This is useful for the application to observe 831 which GL function caused a specific message to be 832 generated by observing the debugger call stack. 833 834 It will also simplify the application's 835 responsibility for creating a thread-safe callback 836 routine at the understood price of potential reduced 837 driver performance when the debug layer is active. 838 839 A new state 840 DEBUG_OUTPUT_SYNCHRONOUS_CALLBACK_ARB will be 841 provided that can be enabled by the application to 842 provide this functionality. 843 844 06) Is it possible that multi-threaded drivers that generate 845 messages asynchronously into the message log can cause a 846 race condition where a message is inserted between the time 847 an application queries DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB 848 and the attempted fetch of the oldest message? 849 850 RESOLVED: Yes. When the message log is full, the oldest 851 message would be bumped out by the new message which 852 would make the queried value incorrect. A solution 853 to this is to make the message log discard messages 854 when it has filled up but otherwise preserve its 855 contents. 856 857 A similar race condition can still occur when 858 querying DEBUG_LOGGED_MESSAGES_ARB when the message 859 log is not full. However in this case the value at 860 the time of the fetch can only either be equal or 861 greater than at the time of the query, and neither 862 case will result in lost information. 863 864 The synchronous callback toggle has also been 865 modified to also explicitly affect the placing of 866 messages into the message log. 867 868Revision History 869 870 (v17, 2013-07-08, Jon Leech) 871 - Change type of userParam parameter to DebugMessageCallbackARB and 872 GLDEBUGPROCARB from 'void *' to 'const void *' to match GL core 873 and KHR_debug (Bug 10083). 874 875 (v16, 2013-04-16, Jon Leech) 876 - Fix type of <ids> parameter in GetDebugMessageLog body (Bug 10083) 877 878 (v15, 2012-06-22, Piers Daniell) 879 - Restored the ARB suffixes removed by mistake. 880 881 (v14, 2012-06-19, Jon Leech) 882 - Change logSize parameter to bufSize 883 884 (v13, 2012-04-19, pdaniell) 885 - Remove ARB suffixs to make the extension ready for OpenGL 4.3. 886 887 (v12, 2010-06-01, jkontti) 888 - Added DEBUG_TYPE_PORTABILITY_ARB 889 - Renamed DEBUG_OUTPUT_SYNCHRONOUS_CALLBACK_ARB to 890 DEBUG_OUTPUT_SYNCHRONOUS_ARB and made it explicitly affect 891 not just callbacks but also messages in the message log. 892 - Moved discussion abotu DEBUG_OUTPUT_SYNCHRONOUS_ARB to its 893 own section 5.5.6 894 - When the message log fills up, new messages will be discarded 895 instead of bumping off old messages (issue 6). 896 - Removed restrictions from third-party sources for 897 DebugMessageControlARB 898 - Removed restrictions on <type> for DebugMessageInsertARB 899 900 (v11, 2010-05-28, jkontti) 901 - Added DEBUG_OUTPUT_SYNCHRONOUS_CALLBACK_ARB enable state for 902 applications to be guaranteed that the debug callback is not 903 called asynchronously or concurrently by the implementation 904 - Created tables 6.55 and 6.56 for new introduced state and 905 implementation-dependent state 906 - Moved sections 2.21.x to 5.5.x 907 - Moved tables 2.15 to 5.3, 2.16 to 5.4, and 2.17 to 5.5 908 - Changed minimum value of MAX_DEBUG_MESSAGE_LENGTH_ARB to 1 909 - Renamed DebugMessageEnableARB to DebugMessageControlARB 910 - For DebugMessageControlARB, DONT_CARE will now be used as the 911 enum to ignore filtered message properties instead of NONE 912 913 914 (v10, 2010-05-13, jkontti) 915 - Split category attribute to orthogonal source and type. This 916 requires all new tokens (currently missing). 917 - Table 2.15 now refers to debug output source 918 - Table 2.16 now refers to debug output type 919 - New table 2.17 that now contains debug output severity 920 921 (v9, 2010-05-11, jkontti) 922 - Rewrote against OpenGL 4.0 Core specification: Section 2.20 923 renamed to 2.21 and tables 2.12 and 2.13 are now 2.15 and 2.16 924 - Added missing sections for changes to Chapters 3-6. 925 - Removed explicit language about contexts created using the 926 debug flag. Instead, implementations can choose, but are 927 not required to, only support this extension in contexts 928 created with the debug flag. 929 - Added Dependencies section to discuss behavior of the 930 debug output entry points when used inside display lists. 931 - Added new entry point GetPointerv since it is missing 932 in core profiles. 933 - Added new state DEBUG_CALLBACK_FUNCTION_ARB, 934 DEBUG_CALLBACK_USER_PARAM_ARB, 935 DEBUG_NEXT_LOGGED_MESSAGE_LENGTH_ARB (token values still 936 missing). 937 - Rewrote sections of GetDebugMessageLog to be clearer and 938 changed some of the error generation. 939 - DebugMessageInsert parameter <length> can now be negative 940 which indicates that the passed-in string is null-terminated. 941 - Updated contributors section 942 943 (v8, 2010-05-07, jkontti) 944 - Removed inconsistent language from New Tokens category for 945 tokens that are no longer accepted by DebugMessageEnableARB 946 since revision v5. 947 - Cleaned up some language and formatting issues. 948 949 (v7, 2010-01-21, jkontti) 950 - Added user-specifiable parameter to debug message callback 951 function. 952 953 (v6, 2010-01-15, jkontti) 954 - Updated contact section. 955 - Updated contributor section. 956 - Updated status section. 957 - Updated enums. 958 959 (v5, 2009-09-17, jkontti) 960 - Message ID namespaces are now contained within categories 961 instead of being in a single global namespace. 962 - Reworked DebugMessageEnable to allow disabling/enabling more 963 combinations of messages. 964 - Resolved issue 01. 965 - Resolved issue 03. 966 967 (v4, 2009-09-16, jkontti) 968 - Added category as a parameter to DebugMessageInsert for 969 future-proofing purposes, 970 - Added missing errors to DebugMessageInsert and 971 GetDebugMessageLog. 972 - Added missing tokens to New Tokens. 973 - Renamed DebugMessageFilter to DebugMessageEnable. 974 975 (v3, 2009-09-15, myoung) 976 - Cleaned up some language 977 - Added values using AMD reserved ranges. Values do not overlap 978 so can be re-used. 979 980 (v2, 2009-09-15, jkontti) 981 - Application-generated messages. 982 - More categories (window system, deprecation, profile, 983 application). 984 985 (v1, 2009-09-09, jkontti) 986 - Initial revision. 987