1Name 2 3 ARB_robustness 4 5Name Strings 6 7 GL_ARB_robustness 8 9Contributors 10 11 Acorn Pooley, NVIDIA 12 Anton Staaf, Google 13 Barthold Lichtenbelt, NVIDIA 14 Bruce Merry, ARM 15 Chris Marrin, Apple 16 Greg Roth, NVIDIA 17 Jeff Bolz, NVIDIA 18 Jon Leech 19 Kenneth Russell, Google 20 Kent Miller, Apple 21 Piers Daniell, NVIDIA 22 Vladimir Vukicevic, Mozilla 23 24Contact 25 26 Mark Kilgard, NVIDIA (mjk 'at' nvidia.com) 27 28Notice 29 30 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 31 http://www.khronos.org/registry/speccopyright.html 32 33Specification Update Policy 34 35 Khronos-approved extension specifications are updated in response to 36 issues and bugs prioritized by the Khronos OpenGL Working Group. For 37 extensions which have been promoted to a core Specification, fixes will 38 first appear in the latest version of that core Specification, and will 39 eventually be backported to the extension document. This policy is 40 described in more detail at 41 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 42 43Status 44 45 Complete. Approved by the ARB on June 9, 2010. 46 Approved by the Khronos Board of Promoters on July 23, 2010. 47 48Version 49 50 Last Modified Date: June 25, 2014 51 Version: 18 52 53Number 54 55 ARB Extension #105 56 57Dependencies 58 59 This extension is written against the OpenGL 3.2 Compatibility 60 Profile Specification but can apply to OpenGL 1.1 and up. 61 62 This specification interacts with the ARB_imaging subset of the OpenGL 63 3.2 Compatibility Profile. 64 65 This specification interacts with the OpenGL 3.2 Core Profile. 66 67 This specification interacts with EXT_direct_state_access. 68 69 GLX_ARB_create_context_robustness and 70 WGL_ARB_create_context_robustness are used to determine if a context 71 implementing this extension supports robust buffer access, and if it 72 supports reset notification. Equivalent platform-dependent 73 mechanisms in other window-system integration layers such as EGL and 74 AGL may exist for those platforms. 75 76Overview 77 78 Several recent trends in how OpenGL integrates into modern computer 79 systems have created new requirements for robustness and security 80 for OpenGL rendering contexts. 81 82 Additionally GPU architectures now support hardware fault detection; 83 for example, video memory supporting ECC (error correcting codes) 84 and error detection. OpenGL contexts should be capable of recovering 85 from hardware faults such as uncorrectable memory errors. Along with 86 recovery from such hardware faults, the recovery mechanism can 87 also allow recovery from video memory access exceptions and system 88 software failures. System software failures can be due to device 89 changes or driver failures. 90 91 Demands for increased software robustness and concerns about malware 92 exploiting buffer overflows have lead API designers to provide 93 additional "safe" APIs that bound the amount of data returned by 94 an API query. For example, the safer "snprintf" or "_snprintf" 95 routines are prefered over "sprintf". 96 97 The OpenGL API has many such robustness perils. OpenGL queries 98 return (write) some number of bytes to a buffer indicated by a 99 pointer parameter. The exact number of bytes written by existing 100 OpenGL queries is not expressed directly by any specific parameter; 101 instead the number of bytes returned is a complex function of one 102 or more query arguments, sometimes context state such as pixel 103 store modes or the active texture selector, and the current state 104 of an object (such as a texture level's number of total texels). 105 By the standards of modern API design, such queries are not "safe". 106 Making these queries safer involves introducing a new query API with 107 an additional parameter that specifies the number of bytes in the 108 buffer and never writing bytes beyond that limit. 109 110 Multi-threaded use of OpenGL contexts in a "share group" allow 111 sharing of objects such as textures and programs. Such sharing in 112 conjunction with concurrent OpenGL commands stream execution by two 113 or more contexts introduces hazards whereby one context can change 114 objects in ways that can cause buffer overflows for another context's 115 OpenGL queries. 116 117 The original ARB_vertex_buffer_object extension includes an issue 118 that explicitly states program termination is allowed when 119 out-of-bounds vertex buffer object fetches occur. Modern GPUs 120 capable of DirectX 10 enforce the well-defined behavior of always 121 returning zero values for indices or non-fixed components in this 122 case. Older GPUs may require extra checks to enforce well-defined 123 (and termination free) behavior, but this expense is warranted when 124 processing potentially untrusted content. 125 126 The intent of this extension is to address some specific robustness 127 goals: 128 129 * For all existing OpenGL queries, provide additional "safe" APIs 130 that limit data written to user pointers to a buffer size in 131 bytes that is an explicit additional parameter of the query. 132 133 * Provide a mechanism for an OpenGL application to learn about 134 graphics resets that affect the context. When a graphics reset 135 occurs, the OpenGL context becomes unusable and the application 136 must create a new context to continue operation. Detecting a 137 graphics reset happens through an inexpensive query. 138 139 * Provide an enable to guarantee that out-of-bounds buffer object 140 accesses by the GPU will have deterministic behavior and preclude 141 application instability or termination due to an incorrect buffer 142 access. Such accesses include vertex buffer fetches of 143 attributes and indices, and indexed reads of uniforms or 144 parameters from buffers. 145 146 In one anticipated usage model, WebGL contexts may make use of these 147 robust features to grant greater stability when using untrusted code. 148 WebGL contexts cannot call OpenGL commands directly but rather must 149 route all OpenGL API calls through the web browser. It is then the 150 web browser that configures the context, using the commands in this 151 extension, to enforce safe behavior. In this scenario, the WebGL 152 content cannot specify or change the use of this extension's features 153 itself; the web browser enforces this policy. 154 155 There are other well-known robustness issues with the OpenGL API 156 which this extension does not address. For example, selector-based 157 OpenGL commands are a well-known source of programming errors. 158 Code to manipulate texture state may assume the active texture 159 selector is set appropriately when an intervening function call 160 obscures a change to the active texture state resulting in 161 incorrectly updated or queried state. The EXT_direct_state_access 162 extension introduces selector-free OpenGL commands and queries to 163 address that particular issue so this extension does not. 164 165 The intent of this extension is NOT to deprecate any existing API 166 and thereby introduce compatibility issues and coding burdens on 167 existing code, but rather to provide new APIs to ensure a level of 168 robustness commensurate with the expectations of modern applications 169 of OpenGL. 170 171IP Status 172 173 No known IP claims. 174 175New Procedures and Functions 176 177 GRAPHICS RESET DETECTION AND RECOVERY 178 179 enum GetGraphicsResetStatusARB(); 180 181 SIZED BUFFER QUERIES 182 183 OpenGL 1.0 sized buffer queries 184 185 void GetnMapdvARB(enum target, enum query, sizei bufSize, double *v); 186 void GetnMapfvARB(enum target, enum query, sizei bufSize, float *v); 187 void GetnMapivARB(enum target, enum query, sizei bufSize, int *v); 188 189 void GetnPixelMapfvARB(enum map, sizei bufSize, float *values); 190 void GetnPixelMapuivARB(enum map, sizei bufSize, uint *values); 191 void GetnPixelMapusvARB(enum map, sizei bufSize, ushort *values); 192 193 void GetnPolygonStippleARB(sizei bufSize, ubyte *pattern); 194 195 void GetnTexImageARB(enum target, int level, enum format, 196 enum type, sizei bufSize, void *img); 197 198 void ReadnPixelsARB(int x, int y, sizei width, sizei height, 199 enum format, enum type, sizei bufSize, 200 void *data); 201 202 ARB_imaging sized buffer queries 203 204 void GetnColorTableARB(enum target, enum format, enum type, 205 sizei bufSize, void *table); 206 void GetnConvolutionFilterARB(enum target, enum format, 207 enum type, sizei bufSize, void *image); 208 void GetnSeparableFilterARB(enum target, enum format, enum type, 209 sizei rowBufSize, void *row, 210 sizei columnBufSize, void *column, 211 void *span); 212 void GetnHistogramARB(enum target, boolean reset, enum format, 213 enum type, sizei bufSize, void *values); 214 void GetnMinmaxARB(enum target, boolean reset, enum format, 215 enum type, sizei bufSize, void *values); 216 217 OpenGL 1.3 sized buffer queries 218 219 void GetnCompressedTexImageARB(enum target, int lod, 220 sizei bufSize, void *img); 221 222 OpenGL 2.0 sized buffer queries 223 224 void GetnUniformfvARB(uint program, int location, sizei bufSize, 225 float *params); 226 void GetnUniformivARB(uint program, int location, sizei bufSize, 227 int *params); 228 void GetnUniformuivARB(uint program, int location, sizei bufSize, 229 uint *params); 230 void GetnUniformdvARB(uint program, int location, sizei bufSize, 231 double *params); 232 233New Tokens 234 235 Returned by GetGraphicsResetStatusARB: 236 237 NO_ERROR 0x0000 238 GUILTY_CONTEXT_RESET_ARB 0x8253 239 INNOCENT_CONTEXT_RESET_ARB 0x8254 240 UNKNOWN_CONTEXT_RESET_ARB 0x8255 241 242 Accepted by the <value> parameter of GetBooleanv, GetIntegerv, 243 GetInteger64v, GetFloatv, and GetDoublev: 244 245 RESET_NOTIFICATION_STRATEGY_ARB 0x8256 246 247 Returned by GetIntegerv and related simple queries when 248 <value> is RESET_NOTIFICATION_STRATEGY_ARB: 249 250 LOSE_CONTEXT_ON_RESET_ARB 0x8252 251 NO_RESET_NOTIFICATION_ARB 0x8261 252 253 Returned by GetIntegerv when <pname> is CONTEXT_FLAGS: 254 255 CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB 0x00000004 256 257 258Additions to Chapter 2 of the OpenGL 3.2 (Compatibility Profile) 259Specification (OpenGL Operation) 260 261Add a new subsection after 2.5 "GL Errors" and renumber subsequent 262sections accordingly 263 264 2.6 "Graphics Reset Recovery" 265 266 Certain events can result in a reset of the GL context. Such a reset 267 causes all context state to be lost. Recovery from such events 268 requires recreation of all objects in the affected context. The 269 current status of the graphics reset state is returned by 270 271 enum GetGraphicsResetStatusARB(); 272 273 The symbolic constant returned indicates if the GL context has been 274 in a reset state at any point since the last call to 275 GetGraphicsResetStatusARB. NO_ERROR indicates that the GL context 276 has not been in a reset state since the last call. 277 GUILTY_CONTEXT_RESET_ARB indicates that a reset has been detected 278 that is attributable to the current GL context. 279 INNOCENT_CONTEXT_RESET_ARB indicates a reset has been detected that 280 is not attributable to the current GL context. 281 UNKNOWN_CONTEXT_RESET_ARB indicates a detected graphics reset whose 282 cause is unknown. 283 284 If a reset status other than NO_ERROR is returned and subsequent 285 calls return NO_ERROR, the context reset was encountered and 286 completed. If a reset status is repeatedly returned, the context may 287 be in the process of resetting. 288 289 Reset notification behavior is determined at context creation time, 290 and may be queried by calling GetIntegerv with the symbolic constant 291 RESET_NOTIFICATION_STRATEGY_ARB. 292 293 If the reset notification behavior is NO_RESET_NOTIFICATION_ARB, 294 then the implementation will never deliver notification of reset 295 events, and GetGraphicsResetStatusARB will always return 296 NO_ERROR[fn1]. 297 [fn1: In this case it is recommended that implementations should 298 not allow loss of context state no matter what events occur. 299 However, this is only a recommendation, and cannot be relied 300 upon by applications.] 301 302 If the behavior is LOSE_CONTEXT_ON_RESET_ARB, a graphics reset will 303 result in the loss of all context state, requiring the recreation of 304 all associated objects. In this case GetGraphicsResetStatusARB. may 305 return any of the values described above. 306 307 If a graphics reset notification occurs in a context, a notification 308 must also occur in all other contexts which share objects with that 309 context[fn2]. 310 [fn2: The values returned by GetGraphicsResetStatusARB in the 311 different contexts may differ.] 312 313 Add to Section 2.8 "Vertex Arrays" before 2.8.1 "Drawing Commands" 314 315 Robust buffer access is enabled by creating a context with robust 316 access enabled through the window system binding APIs. When enabled, 317 indices within the vertex array that lie outside the arrays defined 318 for enabled attributes result in undefined values for the 319 corresponding attributes, but cannot result in application failure. 320 321 322Additions to Chapter 3 of the OpenGL 3.2 (Compatibility Profile) 323Specification (Rasterization) 324 325 None 326 327Additions to Chapter 4 of the OpenGL 3.2 (Compatibility Profile) 328Specification (Per-Fragment Operations and the Frame Buffer) 329 330 Modify section 4.3.2 "Reading Pixels" 331 332 Pixels are read using 333 334 void ReadPixels(int x, int y, sizei width, sizei height, 335 enum format, enum type, void *data); 336 void ReadnPixelsARB(int x, int y, sizei width, sizei height, 337 enum format, enum type, sizei bufSize, 338 void *data); 339 340 The arguments after <x> and <y> to ReadPixels are described in 341 section 3.7.4. The pixel storage modes that apply to ReadPixels and 342 other commands that query images (see section 6.1) are summarized in 343 table 4.7. ReadnPixelsARB behaves identically to ReadPixels except 344 that it does not write more than <bufSize> bytes into <data>. 345 346Additions to Chapter 5 of the OpenGL 3.2 (Compatibility Profile) 347Specification (Special Functions) 348 349 None 350 351Additions to Chapter 6 of the OpenGL 3.2 (Compatibility Profile) 352Specification (State and State Requests) 353 354 Modify Section 6.1.3 "Enumerated Queries" 355 356 void GetPixelMap{ui us f}v(enum map, T data); 357 void GetnPixelMap{ui us f}vARB(enum map, sizei bufSize, T data); 358 359 return all values in the pixel map <map> in <data>. <map> must be 360 a map name from table 3.3. GetPixelMapuiv, GetnPixelMapuivARB, 361 GetPixelMapusv, and GetnPixelMapusvARB convert floating point pixel 362 map values to integers according to the UNSIGNED_INT and 363 UNSIGNED_SHORT entries, respectively, of table 4.9. 364 GetnPixelMap{ui us f}vARB does not write more than <bufSize> 365 bytes into <data>. 366 If a pixel pack buffer ... 367 ... an INVALID_OPERATIONS_ERROR results. When calling 368 GetnPixelMap{ui us f}vARB, if a pixel pack buffer object is bound 369 and <n> is greater than <bufSize>, but <data>+<n> does not exceed 370 the size of the buffer, no error results. 371 372 ... 373 374 void GetMap{ifd}v(enum map, enum value, T data); 375 void GetnMap{ifd}vARB(enum map, enum value, sizei bufSize, T data); 376 377 places information about <value> for <map> in <data>. <map> must 378 be one of the map types described in section 5.1, and <value> must 379 be one of ORDER, COEFF, or DOMAIN. GetnMap{ifd}vARB does not write 380 more than <bufSize> bytes into <data>. 381 382 Section 6.1.4 "Texture Queries" 383 384 385 Modify the description of GetTexImage: 386 387 "The commands 388 389 void GetTexImage(enum tex, int lod, enum format, enum type, 390 void *img ); 391 void GetnTexImageARB(enum tex, int lod, enum format, enum type, 392 sizei bufSize, void *img ); 393 394 are used to obtain texture images. ... 395 ... <type> is a pixel type from table 3.5. GetnTexImageARB does 396 not write more than <bufSize> bytes into <img>." 397 398 Add to the end of the sixth paragraph: 399 400 "When calling GetnTextureImageARB, if a pixel pack buffer object 401 is bound and packing a texture image into buffer memory would 402 exceed <bufSize> but not the size of the buffer, no error results." 403 404 Modify the description of GetCompressedTexImage: 405 406 "The commands 407 408 void GetCompressedTexImage(enum target, int lod, void *img); 409 void GetnCompressedTexImageARB(enum target, int lod, sizei bufSize, 410 void *img ); 411 412 are used to obtain texture images stored in compressed form. The 413 parameters <target>, <lod>, and <img> are interpreted in the same 414 manner as in GetTexImage and GetnTexImageARB respectively. When 415 called, GetCompressedTexImage and GetnCompressedTexImageARB write 416 MIN(n,bufSize) ubytes of compressed image data ... 417 418 ... If a pixel pack buffer object is bound and img + n is greater 419 than the size of the buffer, an INVALID_OPERATION error results. 420 When calling GetnCompressedTextureImageARB, if a pixel pack buffer 421 object is bound and <n> is greater than <bufSize> but <img>+<n> 422 does not exceed the size of the buffer, no error results." 423 424 Modify Section 6.1.5 "Stipple Query" 425 426 The commands 427 428 void GetPolygonStipple(void *pattern); 429 void GetnPolygonStippleARB(sizei bufSize, void *pattern); 430 431 obtain the polygon stipple. The pattern is packed into pixel pack 432 buffer or client memory according to the procedure given in section 433 4.3.2 for ReadPixels; it is as if the <height> and <width> passed 434 to that command were both equal to 32, the type were BITMAP, and 435 the format were COLOR_INDEX. GetnPolygonStippleARB does not write 436 more than <bufSize> bytes into <pattern>. 437 438 Modify Section 6.1.7 "Color Table Query" 439 440 The current contents of a color table are queried using 441 442 void GetColorTable(enum target, enum format, enum type, 443 void *table ); 444 void GetnColorTableARB(enum target, enum format, enum type, 445 sizei bufSize, void *table); 446 447 <target> must be one of the regular color table names listed in 448 table 3.4. ... 449 ... to the components requested by format are described in table 450 6.1. GetnColorTableARB does not write more than <bufSize> bytes 451 into <table>. 452 453 Modify Section 6.1.8 "Convolution Query" 454 455 The current contents of a convolution filter image are queried 456 with the command 457 458 void GetConvolutionFilter(enum target, enum format, enum type, 459 void *image ); 460 void GetnConvolutionFilterARB(enum target, enum format, 461 enum type, sizei bufSize, void *image); 462 463 <target> must be CONVOLUTION_1D or CONVOLUTION_2D. ... 464 ... Pixel processing and component mapping are identical to those 465 of GetTexImage. GetnConvolutionFilterARB does not write more than 466 <bufSize> bytes into <image>. 467 468 ... 469 470 The current contents of a separable filter image are queried using 471 472 void GetSeparableFilter(enum target, enum format, enum type, 473 void *row, void *column, void *span ); 474 void GetnSeparableFilterARB(enum target, enum format, enum type, 475 sizei rowBufSize, void *row, 476 sizei columnBufSize, void *column, 477 void *span); 478 479 ... The row and column images are returned to pixel pack buffer or 480 client memory starting at row and column respectively. 481 GetnSeparableFilterARB does not write more than <rowBufSize> bytes 482 into <row> and no more than <columnBufSize> bytes into <column>. 483 <span> is currently unused. ... 484 485 486 Modify Section 6.1.9 "Histogram Query" 487 488 The current contents of the histogram table are queried using 489 490 void GetHistogram(enum target, boolean reset, enum format, 491 enum type, void* values ); 492 void GetnHistogramARB(enum target, boolean reset, enum format, 493 enum type, sizei bufSize, void* values); 494 495 ... component values are simply clamped to the range of the target 496 data type. GetnHistogramARB does not write more than <bufSize> 497 bytes into <values>. 498 499 Modify Section 6.1.10 "Minmax Query" 500 501 The current contents of the minmax table are queried using 502 503 void GetMinmax(enum target, boolean reset, enum format, 504 enum type, void* values ); 505 void GetnMinmaxARB(enum target, boolean reset, enum format, 506 enum type, sizei bufSize, void* values); 507 508 ... A one-dimensional image of width 2 is returned to pixel pack 509 buffer or client memory starting at <values>. GetnMinmaxARB does 510 not write more than <bufSize> bytes into <values>. 511 512 Modify Section 6.1.11 "Pointer and String Queries" 513 514 Add to the paragraph describing the context profile mask and flags 515 (preceding the description of GetStringi) on page 379: 516 517 "If CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB is set in CONTEXT_FLAGS, 518 then robust buffer access will be enabled for drawing commands 519 using vertex arrays, as described in section 2.8." 520 521 Modify Section 6.1.16 "Shader and Program Queries" 522 523 The commands 524 525 void GetUniformfv(uint program, int location, float *params); 526 void GetnUniformfvARB(uint program, int location, sizei bufSize, 527 float *params); 528 void GetUniformiv(uint program, int location, int *params); 529 void GetnUniformivARB(uint program, int location, sizei bufSize, 530 int *params); 531 void GetUniformuiv(uint program, int location, uint *params); 532 void GetnUniformuivARB(uint program, int location, sizei bufSize, 533 uint *params); 534 void GetUniformdv(uint program, int location, double *params); 535 void GetnUniformdvARB(uint program, int location, sizei bufSize, 536 double *params); 537 538 return the value or values of the uniform at location location of 539 the default uniform block for program object program in the array 540 params. GetnUniformfvARB, GetnUniformivARB, GetnUniformuivARB and 541 GetnUniformdvARB do not write any data to <params> if <bufSize> is 542 less than the size of the requested data. 543 ... 544 545Additions to the AGL/GLX/WGL Specifications 546 547 None 548 549Additions to The OpenGL Shading Language Specification, Version 1.50.11 550 551 Change the first paragraph of section 4.1.9 "Arrays" 552 553 ... Undefined behavior results from indexing an array with a 554 non-constant expression that's greater than or equal to the array's 555 size or less than 0. If robust buffer access is enabled via the 556 OpenGL API, such indexing must not result in abnormal program 557 termination. The results are still undefined, but implementations 558 are encouraged to produce zero values for such accesses. Only 559 one-dimensional arrays may be declared. ... 560 561GLX Protocol 562 563 XXX 564 565Interactions with GLX_ARB_create_context_robustness 566 567 If the GLX window-system binding API is used to create a context, 568 the GLX_ARB_create_context_robustness extension is supported, and 569 the bit GLX_CONTEXT_ROBUST_ACCESS_BIT_ARB is set in 570 GLX_CONTEXT_FLAGS when glXCreateContextAttribsARB is called, the 571 resulting context will perform robust buffer access as described 572 above in section 2.8, and the CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB bit 573 will be set in CONTEXT_FLAGS as described above in section 6.1.11. 574 575 If the GLX window-system binding API is used to create a context and 576 the GLX_ARB_create_context_robustness extension is supported, then 577 the value of attribute GLX_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB 578 determines the reset notification behavior and the value of 579 RESET_NOTIFICATION_STRATEGY_ARB, as described in section 2.6. 580 581Interactions with WGL_ARB_create_context_robustness 582 583 If the WGL window-system binding API is used to create a context, 584 the WGL_ARB_create_context_robustness extension is supported, and 585 the bit WGL_CONTEXT_ROBUST_ACCESS_BIT_ARB is set in 586 WGL_CONTEXT_FLAGS when wglCreateContextAttribsARB is called, the 587 resulting context will perform robust buffer access as described 588 above in section 2.8, and the CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB bit 589 will be set in CONTEXT_FLAGS as described above in section 6.1.11. 590 591 If the WGL window-system binding API is used to create a context and 592 the WGL_ARB_create_context_robustness extension is supported, then 593 the value of attribute WGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB 594 determines the reset notification behavior and the value of 595 RESET_NOTIFICATION_STRATEGY_ARB, as described in section 2.6. 596 597Errors 598 599 GetnMapdvARB, GetnMapfvARB, GetnMapivARB, GetnPixelMapfvARB, 600 GetnPixelMapuivARB, GetnPixelMapusvARB, GetnPolygonStippleARB, 601 GetnTexImageARB, ReadnPixelsARB, GetnColorTableARB, 602 GetnConvolutionFilterARB, GetnSeparableFilterARB, GetnHistogramARB, 603 GetnMinmaxARB, GetnCompressedTexImageARB, GetnUniformfvARB, 604 GetnUniformivARB, GetnUniformuivARB and GetnUniformdvARB share all the 605 errors of their unsized buffer query counterparts with the addition 606 that INVALID_OPERATION is generated if the buffer size required to 607 fill all the requested data is greater than <bufSize>. 608 609New State 610 611 Get Value Type Get Command Value Description Sec Attribute 612 -------------------------- ---- ----------- ------------ --------------------------- ------ --------- 613 RESET_NOTIFICATION_STRATEGY_ARB Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 - 614 615 616New Implementation Dependent State 617 618 None 619 620Dependencies on the ARB_imaging subset 621 622 If the ARB_imaging subset of the OpenGL 3.2 Compatibility Profile is not 623 supported, the commands GetnColorTableARB, GetnConvolutionFilterARB, 624 GetnHistogramARB, GetnMap*ARB, GetnMinmaxARB, GetnPixelMap*ARB, and 625 GetnSeparableFilterARB defined by this extension are not supported, and 626 all references to them should be ignored. 627 628Dependencies on OpenGL 3.2 (Core Profile) 629 630 If only the core profile of OpenGL 3.2 is supported, the commands 631 GetnColorTableARB, GetnConvolutionFilterARB, GetnHistogramARB, 632 GetnMap*ARB, GetnMinmaxARB, GetnPixelMap*ARB, GetnPolygonStippleARB, and 633 GetnSeparableFilterARB defined by this extension are not supported, and 634 all references to them should be ignored. 635 636Issues 637 638 1. Does robust buffer access affect vertex pulling from vertex 639 buffer objects, client vertex arrays, or both? 640 641 RESOLVED: Only vertex buffer objects. 642 643 DirectX 10-era GPUs are guaranteed to provide guarantees 644 consistent with those required by robust buffer access. 645 646 Client memory vertex arrays should not be expected to be used 647 directly in situations requiring robust operation. 648 649 Historically the original EXT_vertex_array extension provided a 650 "GLsizei count" parameter to indicate how long vertex arrays 651 should be. This proved to be unworkable in practice because 652 applications typically found it too difficult to properly compute 653 the count; instead a very large integer was passed, obviating any 654 practical use for the parameter. When vertex arrays were added 655 to core OpenGL in version 1.1, the "GLsizei count" parameter 656 was eliminated for this reason. 657 658 There are other problems too. Clever applications using client 659 memory vertex arrays can specify the base pointer to be NULL 660 (address 0) and then use indices that essentially correspond 661 to pointers divided by the stride. There's also no guarantee a 662 pointer itself has a contiguous range of memory allocate within 663 a given range. 664 665 Moreover client memory vertex arrays are no longer a performance 666 path so they simply are not particularly interesting to address. 667 668 The result is there's really no practical way to bound client 669 vertex array access in a way that's likely to be practically 670 useful. 671 672 Vertex buffer objects do not have this same problem because 673 buffer objects have a bounded index-able range. 674 675 Robust applications should simply use vertex buffer objects for 676 robust vertex pulling (ignoring client memory vertex arrays for 677 an rendering that must be done robustly). 678 679 2. If robust buffer access is supported and a vertex index is large 680 enough to fetch beyond the size of an enabled vertex buffer 681 object, what happens? 682 683 RESOLVED: Undefined values are read for the varying (non-fixed) 684 components. 685 686 A fixed-component would be a component such as the W component 687 when only a 2- or 3-component position is fetched. In this case, 688 the W component is fixed as 1.0 and that will be the case still 689 if the index would have resulted in an out-of-bounds fetch. 690 691 Undefined results are required for implementations that can't 692 guarantee any particular value. It make testing this behavior 693 difficult, but it's required for certain implementations. 694 695 3. If robust buffer access is supported and an element array buffer 696 is accessed beyond the size of the element array buffer so 697 there's not a valide index, what happens? 698 699 RESOLVED: The value of the index is undefined. 700 701 Undefined results are required for implementations that can't 702 guarantee any particular value. It make testing this behavior 703 difficult, but it's required for certain implementations. 704 705 4. What query commands actually need a new "GLsizei bufSize" 706 parameter? 707 708 RESOLVED: If the number of bytes returned by the query is not 709 *completely* determined by the parameters to the function (in 710 the absence of errors) and not already bounded by an existing 711 GLsizei buffer size parameter, a new query is needed. 712 713 This means commands such as glGetClipPlane, glGetIntegerv, 714 etc. do NOT need new versions. 715 716 This means queries that depend on pixel store pack state need 717 new queries. Examples: glReadPixels, glGetPolygonStipple, 718 glGetTexImage, glGetConvolutionFilter, etc. 719 720 This means queries that query an object's state which can 721 vary in size need new queries. Examples: glGetTexImage, 722 glGetCompressedTexImage, glGetUniformfv, glGetUniformuiv, etc. 723 724 This means queries that query context state which can vary 725 depending on other context state variables need new queries. 726 Examples: glGetHistogram, glGetPixelMapfv, glGetColorTable, etc. 727 728 If the command already has a parameter that limits the amount 729 of data returned through a pointer, no new command is needed. 730 Examples: glGetActiveAttrib, glGetActiveUniform, glGetInfoLog, 731 glGetAttachedShaders, glGetAttachedObjects, glGetShaderSource, 732 glGetActiveAttrib, glGetBufferSubData, glGen*, etc. 733 734 5. If a new query with an explicit buffer size is called and the buffer 735 size is not sufficient to return the data, what happens? 736 737 RESOLVED: Return an INVALID_OPERATION error and ignore the query. 738 739 Some consideration was given to clearing the entire buffer range. 740 This might arguably avoid applications subsequently reading from 741 uninitialized buffers. 742 743 This was rejected for several reasons: 744 745 1) Doing something when there's an error is inconsistent with 746 the rest of OpenGL's operation. 747 748 2) If the buffer is left untouched, the application can initialize 749 the buffer to some bogus value (NaN or an invalid negative 750 value) and notice that the buffer was left unmodified after 751 the query without the expense of checking for OpenGL errors. 752 753 3) Many commands return information through packing pixels based 754 on the pixel store state. The pixel store state allows skipping 755 over some data (GL_SKIP_PIXELS, GL_SKIP_ROWS, etc.) so zero'ing 756 memory for the entire buffer isn't a good idea. 757 758 759 6. Can you explain why various glGet queries do NOT have new 760 "sized" versions? 761 762 RESOLVED: 763 764 Queries always returning a constant number of bytes: 765 766 OpenGL 1.0 767 glGetClipPlane 768 - always 4*sizeof(GLdouble) 769 OpenGL 2.0 770 glGetVertexAttribdv 771 - always 4*sizeof(GLdouble) 772 glGetVertexAttribfv 773 - always 4*sizeof(GLfloat) 774 glGetVertexAttribiv 775 - always 4*sizeof(GLint) 776 777 Queries with an effective buffer size parameter already: 778 779 OpenGL 1.5 780 glGetBufferSubData 781 - returns size (parameter) bytes 782 783 Queries with an effective buffer bound (no more bytes than) 784 parameter already: 785 786 OpenGL 2.0 787 glGetAttachedShaders 788 - returns no more than sizeof(GLuint)*maxCount 789 to count and no more than sizeof(GLuint)*maxCount 790 to shaders 791 glGetShaderInfoLog 792 glGetProgramInfoLog 793 glGetShaderSource 794 glGetActiveAttrib 795 glGetActiveUniform 796 - returns no more than bufSize bytes 797 OpenGL 3.0 798 glGetTransformFeedbackVarying 799 - returns no more than bufSize bytes 800 OpenGL 3.2 801 glGetUniformIndices 802 - returns sizeof(GLuint)*uniformCount bytes 803 glGetActiveUniformName 804 glGetActiveUniformBlockName 805 - returns no more than bufSize bytes 806 807 Query's some function of enumeration parameters fully determine 808 the number bytes returned: 809 810 OpenGL 1.0 811 glGetIntegerv 812 glGetFloatv 813 glGetDoublev 814 glGetBooleanv 815 glGetLightiv 816 glGetLightfv 817 glGetMaterialfv 818 glGetMaterialiv 819 glGetTexEnvfv 820 glGetTexEnviv 821 glGetTexGendv 822 glGetTexGenfv 823 glGetTexGeniv 824 glGetTexParameterfv 825 glGetTexParameteriv 826 glGetTexLevelParameterfv 827 glGetTexLevelParameteriv 828 - fully determined by pname parameter 829 OpenGL 1.1 830 glGetPointerv 831 - fully determined by pname parameter 832 glGenTextures 833 - sizeof(GLuint)*n 834 ARB_imaging 835 glGetColorTableParameterfv 836 glGetColorTableParameteriv 837 glGetConvolutionParameterfv 838 glGetConvolutionParameteriv 839 glGetHistogramParameterfv 840 glGetHistogramParameteriv 841 glGetMinmaxParameterfv 842 glGetMinmaxParameteriv 843 - fully determined by pname parameter 844 OpenGL 1.5 845 glGenBuffers 846 glGenQueries 847 - sizeof(GLuint)*n 848 glGetBufferParameteriv 849 glGetQueryObjectiv 850 glGetQueryObjectfv 851 glGetQueryiv 852 - fully determined by pname parameter 853 OpenGL 2.0 854 glGetVertexAttribPointerv 855 glGetShaderiv 856 glGetProgramiv 857 - fully determined by pname parameter 858 OpenGL 3.0 859 glGenRenderbuffers 860 glGenFramebuffers 861 glGenVertexArrays 862 - sizeof(GLuint)*n 863 OpenGL 3.2 864 glGetActiveUniformBlockiv 865 - function of pname and uniformCount 866 glGetActiveUniformsiv 867 - function of pname 868 869 NV_vertex_program 870 glGenProgramsNV 871 - sizeof(GLuint)*n 872 ARB_vertex_program 873 glGenProgramsARB 874 - sizeof(GLuint)*n 875 876 7. What can cause a graphics reset? 877 878 Either user or implementor errors may result in a graphics reset. 879 If the application attempts to perform a rendering that takes too long 880 whether due to an infinite loop in a shader or even just a rendering 881 operation that takes too long on the given hardware. Implementation 882 errors may produce badly formed hardware commands. Memory access errors 883 may result from user or implementor mistakes. Any of these events may 884 result in a graphics reset event that will be detectable by the mechanism 885 described in this extension. 886 887 8. How should the application react to a reset context event? 888 889 RESOLVED: For this extension, the application is expected to query 890 the reset status until NO_ERROR is returned. If a reset is encountered, 891 at least one *RESET* status will be returned. Once NO_ERROR is 892 encountered, the application can safely destroy the old context and 893 create a new one. 894 895 After a reset event, apps should not use a context for any purpose 896 other than determining its reset status, and then destroying it. If a 897 context receives a reset event, all other contexts in its share group 898 will also receive reset events, and should be destroyed and 899 recreated. 900 901 Apps should be cautious in interpreting the GUILTY and INNOCENT reset 902 statuses. These are guidelines to the immediate cause of a reset, but 903 not guarantees of the ultimate cause. 904 905 9. If a graphics reset occurs in a shared context, what happens in 906 shared contexts? 907 908 RESOLVED: A reset in one context will result in a reset in all other 909 contexts in its share group. This is mandated, not recommended 910 behavior as of revision 14. 911 912 10. How can an application query for robust buffer access support, 913 since this is now determined at context creation time? 914 915 RESOLVED. The application can query the CONTEXT_FLAGS bitfield 916 using GetIntegerv and check for the presence of CONTEXT_FLAG_- 917 ROBUST_ACCESS_BIT_ARB. 918 919 11. How is the reset notification behavior controlled? 920 921 RESOLVED: Reset notification behavior is determined at context 922 creation time using GLX/WGL/etc. mechanisms. In order that shared 923 objects be handled predictably, a context cannot share with 924 another context unless both have the same reset notification 925 behavior. 926 927Revision History 928 929 Rev. Date Author Changes 930 ---- ------------ --------- -------------------------------------------- 931 18 25 Jun 2014 Jon Leech Fix type of <params> in Get*Uniformdv. 932 17 17 Sep 2012 Jon Leech Clarify that GetnUniform* does not write 933 any data if bufSize is less than required 934 (Bug 8739). 935 16 25 Jun 2012 Jon Leech Add interactions with ARB_imaging and 936 core profile. 937 15 10 Apr 2012 Jon Leech Fix description of INVALID_OPERATION 938 error to be when required data size is 939 *greater* than bufSize, not *less*. 940 14 22 Jul 2010 Jon Leech Require resets to be delivered to all 941 contexts which share objects. Expand on 942 recommended recovery behavior in Issues 8 943 and 9. Assign enum for new token. 944 13 21 Jul 2010 Jon Leech Remove RequestGraphicsResetNotificationARB 945 and determine graphics reset notification 946 behavior at context creation time in 947 separate GLX/WGL extensions. 948 12 19 Jul 2010 pdaniell Added missing GetnUniformdARB. Add additional 949 language to the "Graphics Reset Recovery" 950 section to clarify objects of shared contexts. 951 Revert revision #7 changes to restore the 952 old "bufSize" behavior and remove the new 953 "length" parameter, both of which proved 954 problematic with implementation. Truncating 955 the output buffer data written to "bufSize" 956 length is hard to implement efficiently in 957 software and impossible with some hardware 958 paths. Also the additional "length" parameter 959 caused PBO based async calls to become sync, 960 which is undesirable. 961 11 07 Jun 2010 groth Clarify PBO errors/sized queries interaction 962 Make consistent the app response to a reset 963 Resolve issue 10 per revision 10 changes. 964 10 07 Jun 2010 Jon Leech Add a bit to the context flags query 965 indicating whether or not robust buffer 966 access was enabled at context creation. 967 9 06 Jun 2010 Jon Leech Note interactions with context creation 968 extensions enabling robust buffer 969 access, and add issue 10 regarding 970 queries for robust buffer access. 971 Remove dangling references to old 972 ROBUST_BUFFER_ACCESS token. 973 8 21 May 2010 groth bmerry comment response 974 Restore ARB suffixes in light of rejection from core 975 7 20 May 2010 groth Allow bounds checking using context creation flag 976 Fix issues. 977 Revise bounded queries to take and return lengths. 978 Add query for current reset strategy. 979 72 column resizing. 980 6 06 May 2010 groth ARBify, catch a few sized gets that hadn't 981 been named correctly. 982 5 05 May 2010 groth Add clarification regarding recovered reset 983 detection. 984 4 02 May 2010 groth Remove references to deleted functionality. 985 Add issue addressing differences with 986 3 15 Apr 2010 groth Describe GLSL array behavior when using 987 robust arrays. 988 Add issue explaining graphics reset causes. 989 2 22 Mar 2010 groth Flesh out missing secions. Remove vestiges of 990 specified limits API. Rename sized queries. 991 Various grammar corrections and clarifications. 992 1 19 Jan 2010 mjk Initial version 993