1Name 2 3 ARB_multi_bind 4 5Name Strings 6 7 GL_ARB_multi_bind 8 9Contact 10 11 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 12 13Contributors 14 15 Jeff Bolz, NVIDIA 16 Frank Chen, Qualcomm 17 Piers Daniell, NVIDIA 18 Daniel Koch, NVIDIA 19 Jon Leech 20 21Notice 22 23 Copyright (c) 2013 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. Approved by the ARB on June 3, 2013. 39 Ratified by the Khronos Board of Promoters on July 19, 2013. 40 41Version 42 43 Last Modified Date: May 30, 2013 44 Revision: 10 45 46Number 47 48 ARB Extension #147 49 50Dependencies 51 52 This extension is written against the OpenGL 4.3 (Compatibility Profile) 53 Specification, dated August 6, 2012. 54 55 OpenGL 3.0 is required. 56 57 This extension interacts with OpenGL 3.3 and ARB_sampler_objects. 58 59 This extension interacts with OpenGL 4.3 and ARB_vertex_attrib_binding. 60 61Overview 62 63 This extension provides a new set of commands allowing applications to 64 bind or unbind a set of objects in a single call, instead of requiring a 65 separate call for each bind or unbind operation. Using a single command 66 allows OpenGL implementations to amortize function call, name space 67 lookup, and potential locking overhead over multiple bind or unbind 68 operations. The rendering loops of graphics applications frequently 69 switch between different states, binding different sets of resources, 70 including texture objects, sampler objects, textures for image loads and 71 stores, uniform buffers, and vertex buffers; this extension provides 72 "multi-bind" entry points for all of these object types. 73 74 Each command in this extension includes a <first> and <count> parameter, 75 specifying a continguous range of binding points to update, as well as an 76 array of <count> object names specifying the objects to bind. Unlike 77 single bind commands, multi-bind commands can be used only to bind or 78 unbind existing objects. Passing a previously unused object name 79 (generated or not) results in an error and does not create a new object. 80 For binding points with associated data (e.g., ranges of a buffer), 81 separate arrays are used to pass the associated data for each binding 82 point. Passing zero values in the array of object names removes the 83 object bound to the current bounding point. Additionally, if NULL is 84 passed as the array of objects, objects bound to the entire range of 85 binding points are unbound, as though the caller passed an array of 86 zeroes. 87 88New Procedures and Functions 89 90 void BindBuffersBase(enum target, uint first, sizei count, 91 const uint *buffers); 92 93 void BindBuffersRange(enum target, uint first, sizei count, 94 const uint *buffers, const intptr *offsets, 95 const sizeiptr *sizes); 96 97 void BindTextures(uint first, sizei count, const uint *textures); 98 99 void BindSamplers(uint first, sizei count, const uint *samplers); 100 101 void BindImageTextures(uint first, sizei count, const uint *textures); 102 103 void BindVertexBuffers(uint first, sizei count, const uint *buffers, 104 const intptr *offsets, const sizei *strides); 105 106New Tokens 107 108 None. 109 110Modifications to the OpenGL 4.3 (Compatibility Profile) Specification 111 112 Modify Section 2.3.1, Errors, p. 15 113 114 (modify third paragraph, p. 16, adding "unless otherwise noted" 115 qualification to the general rule that commands producing errors have no 116 side effects) 117 118 Table 2.3 summarizes ... if an OUT_OF_MEMORY error has occurred. In 119 other cases, there are no side effects unless otherwise noted; the command 120 which generates the error is ignored so that it has no effect on GL state 121 or framebuffer contents. ... 122 123 124 Modify Section 6.1.1, Binding Buffer Objects To Indexed Targets, p. 55 125 126 (insert immediately after the "Errors" block at the end of the section, 127 p. 56) 128 129 The commands 130 131 void BindBuffersBase(enum target, uint first, sizei count, 132 const uint *buffers); 133 134 void BindBuffersRange(enum target, uint first, sizei count, 135 const uint *buffers, const intptr *offsets, 136 const sizeiptr *sizes); 137 138 bind <count> existing buffer objects to bindings numbered <first> through 139 <first>+<count>-1 in the array of buffer binding points corresponding to 140 <target>. If <buffers> is not NULL, it specifies an array of <count> 141 values, each of which must be zero or the name of an existing buffer 142 object. For BindBuffersRange, <offsets> and <sizes> specify arrays of 143 <count> values indicating the range of each buffer to bind. If <buffers> 144 is NULL, all bindings from <first> through <first>+<count>-1 are reset 145 to their unbound (zero) state. In this case, the offsets and sizes 146 associated with the binding points are set to default values, ignoring 147 <offsets> and <sizes>. 148 149 BindBuffersBase is equivalent to: 150 151 for (i = 0; i < count; i++) { 152 if (buffers == NULL) { 153 glBindBufferBase(target, first + i, 0); 154 } else { 155 glBindBufferBase(target, first + i, buffers[i]); 156 } 157 } 158 159 except that the single general buffer binding corresponding to <target> 160 is unmodified, and that buffers will not be created if they do not 161 exist. 162 163 BindBuffersRange is equivalent to: 164 165 for (i = 0; i < count; i++) { 166 if (buffers == NULL) { 167 glBindBufferRange(target, first + i, 0, 0, 0); 168 } else { 169 glBindBufferRange(target, first + i, buffers[i], offsets[i], 170 sizes[i]); 171 } 172 } 173 174 except that the single general buffer binding corresponding to <target> 175 is unmodified, and that buffers will not be created if they do not 176 exist. 177 178 The values specified in <buffers>, <offsets>, and <sizes> will be checked 179 separately for each binding point. When values for a specific binding 180 point are invalid, the state for that binding point will be unchanged and 181 an error will be generated. However, state for other binding points will 182 still be changed if their corresponding values are valid. 183 184 Errors 185 186 An INVALID_ENUM error is generated if <target> is not one of the targets 187 listed above. 188 189 An INVALID_OPERATION error is generated if <first> + <count> is greater 190 than the number of target-specific indexed binding points, as described 191 in section 6.7.1. 192 193 An INVALID_OPERATION error is generated if any value in <buffers> is not 194 zero or the name of an existing buffer object (per binding). 195 196 An INVALID_VALUE error is generated by BindBuffersRange if any value in 197 <offsets> is less than zero (per binding). 198 199 An INVALID_VALUE error is generated by BindBuffersRange if any value in 200 <sizes> is less than or equal to zero (per binding). 201 202 An INVALID_VALUE error is generated by BindBuffersRange if any pair of 203 values in <offsets> and <sizes> does not respectively satisfy the 204 constraints described for those parameters for the specified target, as 205 described in section 6.7.1 (per binding). 206 207 208 Modify Section 8.1, Texture Objects (p. 155) 209 210 (insert after errors section, p. 156) 211 212 The command 213 214 void BindTextures(uint first, sizei count, const uint *textures); 215 216 binds <count> existing texture objects to texture image units numbered 217 <first> through <first>+<count>-1. If <textures> is not NULL, it 218 specifies an array of <count> values, each of which must be zero or the 219 name of an existing texture object. When an entry in <textures> is the 220 name of an existing texture object, that object is bound to corresponding 221 texture unit for the target specified when the texture object was created. 222 When an entry in <textures> is zero, each of the targets enumerated at the 223 beginning of this section is reset to its default texture for the 224 corresponding texture image unit. If <textures> is NULL, each target of 225 each affected texture image unit from <first> through <first>+<count>-1 is 226 reset to its default texture. 227 228 BindTextures is equivalent to 229 230 for (i = 0; i < count; i++) { 231 uint texture; 232 if (textures == NULL) { 233 texture = 0; 234 } else { 235 texture = textures[i]; 236 } 237 ActiveTexture(TEXTURE0 + first + i); 238 if (texture != 0) { 239 enum target = /* target of texture object textures[i] */; 240 BindTexture(target, textures[i]); 241 } else { 242 for (target in all supported targets) { 243 BindTexture(target, 0); 244 } 245 } 246 } 247 248 except that the active texture selector retains its original value upon 249 completion of the command, and that textures will not be created if they 250 do not exist. 251 252 253 The values specified in <textures> will be checked separately for each 254 texture image unit. When a value for a specific texture image unit is 255 invalid, the state for that texture image unit will be unchanged and an 256 error will be generated. However, state for other texture image units 257 will still be changed if their corresponding values are valid. 258 259 Errors 260 261 An INVALID_OPERATION error is generated if <first> + <count> is greater 262 than the number of texture image units supported by the implementation. 263 264 An INVALID_OPERATION error is generated if any value in <textures> is 265 not zero or the name of an existing texture object (per binding). 266 267 268 Modify Section 8.2, Sampler Objects (p. 158) 269 270 (insert after errors section, p. 159) 271 272 The command 273 274 void BindSamplers(uint first, sizei count, const uint *samplers); 275 276 binds <count> existing sampler objects to texture image units numbered 277 <first> through <first>+<count>-1. If <samplers> is not NULL, it 278 specifies an array of <count> values, each of which must be zero or the 279 name of an existing sampler object. If <samplers> is NULL, each affected 280 texture image unit from <first> through <first>+<count>-1 will be reset to 281 have no bound sampler object. 282 283 BindSamplers is equivalent to 284 285 for (i = 0; i < count; i++) { 286 if (samplers == NULL) { 287 glBindSampler(first + i, 0); 288 } else { 289 glBindSampler(first + i, samplers[i]); 290 } 291 } 292 293 The values specified in <samplers> will be checked separately for each 294 texture image unit. When a value for a specific texture image unit is 295 invalid, the state for that texture image unit will be unchanged and an 296 error will be generated. However, state for other texture image units 297 will still be changed if their corresponding values are valid. 298 299 Errors 300 301 An INVALID_OPERATION error is generated if <first> + <count> is greater 302 than the number of texture image units supported by the implementation. 303 304 An INVALID_OPERATION error is generated if any value in <samplers> is 305 not zero or the name of an existing sampler object (per binding). 306 307 308 Modify Section 8.25, Texture Image Loads and Stores, p. 281 309 310 (insert before the next-to-last paragraph, p. 282, "When a shader 311 accesses...") 312 313 The command 314 315 void BindImageTextures(uint first, sizei count, const uint *textures); 316 317 binds <count> existing texture objects to image units numbered <first> 318 through <first>+<count>-1. If <textures> is not NULL, it specifies an 319 array of <count> values, each of which must be zero or the name of an 320 existing texture object. If <textures> is NULL, each affected image unit 321 from <first> through <first>+<count>-1 will be reset to have no bound 322 texture object. 323 324 When binding a non-zero texture object to an image unit, the image unit 325 <level>, <layered>, <layer>, and <access> parameters are set to zero, 326 TRUE, zero, and READ_WRITE, respectively. The image unit <format> 327 parameter is taken from the internal format of the texture image at level 328 zero of the texture object identified by <textures>. For cube map 329 textures, the internal format of the TEXTURE_CUBE_MAP_POSITIVE_X image of 330 level zero is used. For multisample, multisample array, buffer, and 331 rectangle textures, the internal format of the single texture level is 332 used. 333 334 When unbinding a texture object from an image unit, the image unit 335 parameters <level>, <layered>, <layer>, and <format> will be reset to 336 their default values of zero, FALSE, 0, and R8, respectively. 337 338 BindImageTextures is equivalent to 339 340 for (i = 0; i < count; i++) { 341 if (textures == NULL || textures[i] = 0) { 342 glBindImageTexture(first + i, 0, 0, FALSE, 0, READ_ONLY, R8); 343 } else { 344 glBindImageTexture(first + i, textures[i], 0, TRUE, 0, READ_WRITE, 345 lookupInternalFormat(textures[i])); 346 } 347 } 348 349 where lookupInternalFormat returns the internal format of the specified 350 texture object. 351 352 The values specified in <textures> will be checked separately for each 353 image unit. When a value for a specific image unit is invalid, the state 354 for that image unit will be unchanged and an error will be generated. 355 However, state for other image units will still be changed if their 356 corresponding values are valid. 357 358 Errors 359 360 An INVALID_OPERATION error is generated if <first> + <count> is greater 361 than the number of image units supported by the implementation. 362 363 An INVALID_OPERATION error is generated if any value in <textures> is 364 not zero or the name of an existing texture object (per binding). 365 366 An INVALID_OPERATION error is generated if the internal format of the 367 level zero texture image of any texture in <textures> is not found in 368 table 8.33 (per binding). 369 370 An INVALID_OPERATION error is generated if the width, height, or depth 371 of the level zero texture image of any texture in <textures> is zero 372 (per binding). 373 374 375 Modify Section 10.3.1, Specifying Arrays For Generic Attributes, p. 340 376 377 (insert after first errors section, p. 343) 378 379 The command 380 381 void BindVertexBuffers(uint first, sizei count, const uint *buffers, 382 const intptr *offsets, const sizei *strides); 383 384 binds <count> existing buffer objects to vertex buffer binding points 385 numbered <first> through <first>+<count>-1. If <buffers> is not NULL, it 386 specifies an array of <count> values, each of which must be zero or the 387 name of an existing buffer object. <offsets> and <strides> specify arrays 388 of <count> values indicating the offset of the first element and stride 389 between elements in each buffer, respectively. If <buffers> is NULL, each 390 affected vertex buffer binding point from <first> through 391 <first>+<count>-1 will be reset to have no bound buffer object. In this 392 case, the offsets and strides associated with the binding points are set 393 to default values, ignoring <offsets> and <strides>. 394 395 BindVertexBuffers is equivalent to 396 397 for (i = 0; i < count; i++) { 398 if (buffers == NULL) { 399 glBindVertexBuffer(first + i, 0, 0, 16); 400 } else { 401 glBindVertexBuffer(first + i, buffers[i], offsets[i], strides[i]); 402 } 403 } 404 405 except that buffers will not be created if they do not exist. 406 407 The values specified in <buffers>, <offsets>, and <strides> will be 408 checked separately for each vertex buffer binding point. When a value for 409 a specific binding point is invalid, the state for that binding point will 410 be unchanged and an error will be generated. However, state for other 411 binding points will still be changed if their corresponding values are 412 valid. 413 414 Errors 415 416 An INVALID_OPERATION error is generated if <first> + <count> is greater 417 than the value of MAX_VERTEX_ATTRIB_BINDINGS. 418 419 An INVALID_OPERATION error is generated if any value in <buffers> is not 420 zero or the name of an existing buffer object (per binding). 421 422 An INVALID_VALUE error is generated if any value in <offsets> or 423 <strides> is negative (per binding). 424 425 426 Modify Section 21.4.1, Commands Not Usable in Display Lists, p. 618 427 428 (add a new section below "Debug output", p. 619) 429 430 Multi-object binds: BindBuffersBase, BindBuffersRange, BindTextures, 431 BindSamplers, BindImageTextures, BindVertexBuffers 432 433 434Additions to the AGL/EGL/GLX/WGL Specifications 435 436 None 437 438GLX Protocol 439 440 TBD 441 442Dependencies on OpenGL 3.3 and ARB_sampler_objects 443 444 If neither OpenGL 3.3 nor ARB_sampler_objects is supported, references to 445 BindSamplers should be removed. 446 447Dependencies on OpenGL 4.3 and ARB_vertex_attrib_binding 448 449 If neither OpenGL 4.3 nor ARB_vertex_attrib_binding is supported, 450 references to BindVertexBuffers should be removed. 451 452Errors 453 454 An INVALID_ENUM error is generated by BindBuffersBase or BindBuffersRange 455 if <target> is not one of the indexed targets for buffer bindings. 456 457 An INVALID_OPERATION error is generated by BindBuffersBase or 458 BindBuffersRange if <first> + <count> is greater than the number of 459 target-specific indexed binding points, as described in section 6.7.1. 460 461 An INVALID_OPERATION error is generated by BindBuffersBase or 462 BindBuffersRange if any value in <buffers> is not zero or the name of an 463 existing buffer object (per binding). 464 465 An INVALID_VALUE error is generated by BindBuffersRange if any value in 466 <offsets> is less than zero (per binding). 467 468 An INVALID_VALUE error is generated by BindBuffersRange if any value in 469 <sizes> is less than or equal to zero (per binding). 470 471 An INVALID_VALUE error is generated by BindBuffersRange if any pair of 472 values in <offsets> and <sizes> do not respectively satisfy the 473 constraints described for those parameters for the specified target, as 474 described in section 6.7.1 (per binding). 475 476 An INVALID_OPERATION error is generated by BindTextures if <first> + 477 <count> is greater than the number of texture image units supported by the 478 implementation. 479 480 An INVALID_OPERATION error is generated by BindTextures if any value in 481 <textures> is not zero or the name of an existing texture object (per 482 binding). 483 484 An INVALID_OPERATION error is generated by BindSamplers if <first> + 485 <count> is greater than the number of texture image units supported by the 486 implementation. 487 488 An INVALID_OPERATION error is generated by BindSamplers if any value in 489 <samplers> is not zero or the name of an existing texture object (per 490 binding). 491 492 An INVALID_OPERATION error is generated by BindImageTextures if <first> + 493 <count> is greater than the number of image units supported by the 494 implementation. 495 496 An INVALID_OPERATION error is generated by BindImageTextures if any value 497 in <textures> is not zero or the name of an existing texture object (per 498 binding). 499 500 An INVALID_OPERATION error is generated by BindImageTextures if the 501 internal format of the level zero texture image of any texture in 502 <textures> is not found in table 8.33 (per binding). 503 504 An INVALID_OPERATION error is generated by BindImageTextures if the width, 505 height, or depth of the level zero texture image of any texture in 506 <textures> is zero (per binding). 507 508 An INVALID_OPERATION error is generated by BindVertexBuffers if <first> + 509 <count> is greater than the value of MAX_VERTEX_ATTRIB_BINDINGS. 510 511 An INVALID_OPERATION error is generated by BindVertexBuffers if any value 512 in <buffers> is not zero or the name of an existing texture object (per 513 binding). 514 515 An INVALID_VALUE error is generated by BindVertexBuffers if any value in 516 <offsets> or <strides> is negative (per binding). 517 518New State 519 520 None. 521 522New Implementation Dependent State 523 524 None. 525 526Issues 527 528 (1) Regular binding commands such as BindBuffer or BindTexture can be used 529 either to bind an existing object or to create and bind a new object. 530 Should the multi-bind commands behave similarly? 531 532 RESOLVED: No. Multi-Bind commands will only support binding existing 533 objects. They will generate an error if any of the provided objects 534 doesn't already exist. 535 536 This extension is intended to provide efficient APIs allowing 537 applications to bind multiple objects for rendering in a single command. 538 Implementations of these commands are intended to bind the objects to 539 consecutive binding points in a loop amortizing function call, name 540 space lookup, locking, and other overhead over <N> objects. Not 541 supporting bind-to-create reduces the number of cases that this loop 542 needs to handle. 543 544 Even if bind-to-create were supported, it probably wouldn't be very 545 useful. When bind-to-create is used in current single-bind APIs, the 546 binding serves two purposes -- to create the object and to bind it for 547 use by subsequent "update" APIs defining the state of the new object. 548 In a multi-Bind API, it wouldn't be possible to bind more than one of 549 the <N> objects for update. 550 551 Additionally, if BindTexture is used to create a texture object, the 552 texture type is established based on the <target> parameter (e.g., 553 TEXTURE_2D). The multi-Bind API for textures doesn't include <target> 554 parameters, so we wouldn't know what type of texture to create. 555 556 (2) Should we provide a command binding multiple texture objects of 557 different targets (e.g., TEXTURE_2D and TEXTURE_3D) in a single call? 558 For example, should you be able to bind three 2D textures to the 559 TEXTURE_2D target of image units 1, 2, and 3, as well as binding two 560 3D textures to the TEXTURE_3D target of texture image units 0 and 4? 561 562 RESOLVED: Yes. The BindTextures() command does not take <target> 563 enums. Instead, the target used for each texture image unit comes from 564 the target used when the texture object was created. 565 566 (3) Should we support unbinding objects in a multi-bind command? If so, 567 how does this work for texture objects, where each texture image unit 568 has multiple binding points (targets)? 569 570 RESOLVED: Yes, applications can unbind objects by passing zero in the 571 array of object names. For textures, passing zero will unbind textures 572 from all texture targets. 573 574 (4) Should we provide a simple way to unbind objects from a collection of 575 contiguous binding points? 576 577 RESOLVED: Yes, passing a NULL pointer instead of an array of object 578 names does an unbind for all binding points. Basically, it's treated 579 like an array of zeroes. 580 581 (5) Should we support multiple bindings of buffer objects using both the 582 "BindBufferBase" and the "BindBufferRange" styles? If so, what name 583 should we use for these APIs? 584 585 RESOLVED: Yes. BindBuffersBase() is equivalent to a loop repeatedly 586 calling BindBufferBase(); BindBuffersRange() is equivalent to a loop 587 repeatedly calling BindBufferRange(). 588 589 The name choice for the "plural" forms of BindBufferBase and 590 BindBufferRange was tricky. "BindBufferRanges" would have been a fine 591 choice for BindBufferRange, but using "BindBufferBases" would have been 592 strange since "BindBufferBase" means "bind a buffer from the base of its 593 storage (offset zero)". We considered "BindBuffers" as the plural for 594 "BindBufferBase", but decided to use "BindBuffers{Base,Range}". 595 596 (6) If we support multiple bindings using the BindBufferRange style, how 597 should the application specify the ranges? 598 599 RESOLVED: Applications will pass separate arrays of offsets and sizes. 600 601 Alternate options included: 602 603 * a single array where entry 2<N> specifies the offset for binding <N> 604 and entry 2<N>+1 specifies the size for binding <N>; 605 606 * defining a new structure type including an offset and a size, and 607 accepting an array of <N> structures 608 609 (7) Should we create a "multi-bind" command for specifying vertex buffer 610 bindings (those specified via BindVertexBuffer)? 611 612 RESOLVED: Yes. 613 614 (8) If we add a "multi-bind" command for specifying vertex buffer 615 bindings, should we also create a similar command for specifying 616 multiple vertex formats (VertexAttrib*Format) in a single call? 617 618 RESOLVED: No. The design of ARB_vertex_attrib_binding separated 619 vertex buffer bindings from vertex formats, expecting that many 620 applications will change bindings frequently but change formats 621 relatively infrequently. While we could create a command specifying 622 multiple formats at once, but it would require us to turn several format 623 parameters (<size>, <type>, <normalized>, <relativeoffset>) into arrays. 624 625 Additionally, mutable vertex array objects can already be used to make a 626 wholesale change of formats and bindings. An application using a small 627 number of formats with a large number of bindings could create a 628 separate VAO for each format, and then change bindings with the 629 "multi-bind" command. 630 631 (9) Should we provide a command to specify multiple image unit bindings in 632 a single command? 633 634 RESOLVED: Yes. We decided to support this for completeness, though the 635 required number of image units is relatively small (8). 636 637 (10) Should binding an array of buffer objects via BindBuffersBase or 638 BindBuffersRange update the generic (non-indexed) binding points for 639 <target>? 640 641 RESOLVED: No. 642 643 In unextended OpenGL 4.3, targets like UNIFORM_BUFFER include both an 644 array of indexed bindings used for shader execution as well as a generic 645 "non-indexed" binding point that can be used for commands such as 646 BufferSubData. Calling BindBufferBase or BindBufferRange updates two 647 binding points -- binding <index> in the array of indexed bindings as 648 well as the generic binding point. Updating both binding points allows 649 applications to bind a buffer for manipulation and update in a single 650 command. 651 652 For BindBuffersBase and BindBuffersRange, the caller specifies <count> 653 separate buffers. We have specified these commands not to update the 654 generic binding point. Even if we were to update the generic binding 655 point, we'd have to pick one arbitrarily. 656 657 (11) Typically, OpenGL specifies that if an error is generated by a 658 command, that command has no effect. This is somewhat unfortunate 659 for multi-bind commands, because it would require a first pass to 660 scan the entire list of bound objects for errors and then a second 661 pass to actually perform the bindings. Should we have different 662 error semantics? 663 664 RESOLVED: Yes. In this specification, when the parameters for one of 665 the <count> binding points are invalid, that binding point is not 666 updated and an error will be generated. However, other binding points 667 in the same command will be updated if their parameters are valid and no 668 other error occurs. 669 670 (12) What error should be generated if the <first> and <count> parameters 671 specified in multi-bind commands specify a range beyond 672 implementation-dependent limits? 673 674 RESOLVED: INVALID_OPERATION is typically generated when the 675 combination of two values is illegal. INVALID_VALUE would also be 676 defensible. 677 678 (13) How are the <offsets> and <sizes> parameters of BindBuffersRange used 679 if <buffers> is NULL? 680 681 RESOLVED: We specify that these parameters are ignored when buffers 682 is NULL, so that applications can unbind a range of buffers with: 683 684 BindBuffersRange(target, 0, 8, NULL, NULL, NULL); 685 686 (14) Should we provide a "multi-bind" API to attach multiple textures to 687 the color attachments of a framebuffer object? Should we add an API 688 populating all attachments at once? 689 690 RESOLVED: No. We could consider an API like: 691 692 void FramebufferColorTextures(enum target, uint first, sizei count, 693 const uint *textures, 694 const uint *levels); 695 696 One might omit the <levels> parameter, since level 0 is used most 697 frequently, and non-zero levels could still be handled by creating 698 spearate views via ARB_texture_view. If we wanted to be able to specify 699 the full set of attachments at once, we could have: 700 701 void FramebufferTextures(enum target, sizei count, 702 const uint *colorAttachments, 703 const uint depthAttachment, 704 const uint stencilAttachment); 705 706 This API effectively omits the <first> argument and always starts at 707 zero. The "all attachments" API could be handled in OpenGL today by 708 using separate framebuffer objects for each attachment combination. 709 However, for applications that work with various combinations of 710 attachments but don't already have a notion of "attachment sets" to map 711 to framebuffer objects, caching different attachment combinations is 712 somewhat unwieldy. 713 714 (15) Should we provide a multi-bind API that binds pairs of textures and 715 samplers to a set of consecutive texture image units? 716 717 RESOLVED: No. We could provide a command such as: 718 719 void BindTexturesSamplers(uint first, sizei count, 720 const uint *textures, 721 const uint *samplers); 722 723 that would be roughly equivalent to: 724 725 BindTextures(first, count, textures); 726 BindSamplers(first, count, samplers); 727 728 If we did this, we'd have to decide how it would interact with the error 729 semantics in issue (11). If we have an error generated because of an 730 invalid texture for a given unit, would the sampler state for that unit 731 still be updated if the sampler provided were valid? Since we chose not 732 to support this feature, we don't need to address this question. 733 734 (16) When binding a non-zero texture to a texture image unit, should 735 BindTextures implicitly unbind the textures bound to all other 736 targets of the unit? 737 738 RESOLVED: No. 739 740 This approach was considered to behave similarly to the proposed 741 behavior for binding zero in a multi-bind API, where it unbinds any 742 bound texture for all targets. Applications using BindTextures 743 exclusively would never have more than one texture bound to the targets 744 of a texture image unit. A driver implementation might optimize for 745 this behavior by having a single "primary" binding point for each 746 texture unit (used by this API) and then "backup" binding points for the 747 other targets (used by BindTexture). This API would update the 748 "primary" binding point but would only need to touch the "backup" 749 binding points if something were bound there via BindTexture. However, 750 BindTexture would still be available and is commonly used today, so 751 there would probably be little benefit. 752 753 (17) For the BindTextures API, should the <first> parameter be an unsigned 754 integer (0) or an enum (GL_TEXTURE0)? 755 756 RESOLVED: Use an integer unit number. 757 758 (18) The BindImageTexture API not only binds a texture to an image unit, 759 but also sets several additional pieces of state associated with an 760 image unit (level, layered or not, selected layer, and image unit 761 format). How should this state be set? Should we provide separate 762 arrays for each extra parameter? 763 764 RESOLVED: Use "default" values for each image unit. When unbinding 765 textures, reset the state to API defaults (level zero, non-layered, 766 layer zero, and R8 format). When binding textures, bind all layers of 767 level zero and take the format from the internal format of the texture 768 level being bound. Setting <layered> to TRUE in this case is not the 769 default state, but it seems like the best default choice for cube map or 770 array textures. For textures without layers, the <layered> parameter 771 has no effect, so this doesn't cause any problems with other targets 772 like TEXTURE_2D. 773 774 If an application wants to bind levels other than zero, select 775 individual layers of a level for array textures, or use a format 776 different from that of the texture, it will be necessary to do 777 individual bindings via BindImageTexture. 778 779 (19) If a texture bound to an image unit via BindImageTextures doesn't 780 have a defined texture image (i.e., width = height = 0 for 2D 781 textures), what internal format is associated with the binding? 782 783 UNRESOLVED: We will generate INVALID_OPERATION if there is no defined 784 texture image. 785 786 Note that even if a texture level has no texels defined, there is still 787 an <internalformat> associated with the level, which can be queried with 788 GetTexLevelParameter. That value could be used, but it would still have 789 to be checked to see if it's valid for image loads and stores. 790 BindImageTexture doesn't accept all possible <format> enums. 791 Additionally, the default internal format is profile-dependent: core 792 uses "RGBA", compatibility uses "1" (from OpenGL 1.0, meaning 793 LUMINANCE). Neither is accepted by BindImageTexture, though RGBA might 794 be mapped internally by a driver to an internal format like RGBA8 that 795 is accepted. 796 797 Given the potential confusion over the internal format for zero-sized 798 images and default internal formats, it's best to just not accept 799 textures without defined images. 800 801 (20) The BindBuffersRange and BindVertexBuffers accept arrays of "intptr" 802 and "sizeiptr" values, which will have different sizes on 32- and 803 64-bit architectures. Is there any problem here? 804 805 RESOLVED: The API is fine. Application developers will need to be 806 careful to use the correct data type for the arrays it passes to these 807 commands. If the array passed to <offsets> is an array of "int" instead 808 of "intptr", that code will typically work fine when compiled on 32-bit 809 architectures if "int" types are stored as 32-bit values. But if the 810 same code is compiled for a 64-bit architecture, the array will be too 811 small. We expect that compilers will generate warnings and/or errors 812 if the caller passes a pointer to the wrong type. 813 814 (21) In the compatibility profile, can multi-bind commands be included in 815 display lists? 816 817 RESOLVED: No. 818 819 (22) What error should be generated when one of the names passed to a 820 multi-bind command is not the name of an existing object? 821 822 UNRESOLVED: INVALID_OPERATION. For the core profile, as well as for 823 object types created since OpenGL 3.1, we have spec errors like the 824 following for BindTexture: 825 826 An INVALID_OPERATION error is generated if <texture> is not zero or a 827 name returned from a previous call to GenTextures, or if such a name 828 has since been deleted. 829 830 In issue (1), we decided that the multi-bind commands could not be used 831 to create objects, whether or not the object names had previously been 832 returned by commands like GenTextures. The errors we require for the 833 multi-bind commands are different from the BindTexture language quoted 834 immmediately above only in the sense that the multi-bind will 835 additionally throw an error if a texture name has been generated by 836 GenTextures but the underlying texture object hasn't yet been created. 837 However, the errors are similar enough that they should both throw the 838 same error code (INVALID_OPERATION). 839 840 841Revision History 842 843 Revision 11, August 16, 2013 (Jon Leech) 844 - Typo fix for BindBuffers* "offsets and strides" -> "offsets and 845 sizes" (Bug 10685). 846 Revision 10, July 21, 2013 (Jon Leech) 847 - Specify that multibind commands are equivalent to repeated calls to 848 the corresponding single bind commands except that objects are not 849 created if they do not exist, matching issue 1. The other single 850 bind commands do not create objects so this clarification is not 851 needed for them (Bug 10486). 852 853 Revision 9, May 30, 2013 (Jon Leech) 854 - Fix typo for <offsets> "less than to zero" -> "less than zero". Use 855 "<first> *through* <first> + <count> - 1" consistently. 856 857 Revision 8, May 28, 2013 858 - Change the error thrown when an object name passed to a multi-bind 859 command doesn't yet exist from INVALID_VALUE to INVALID_OPERATION 860 (bug 10264). 861 - Disallow the use of multi-bind commands in display lists (bug 10322). 862 - Change the <count> parameter in multi-bind commands to use the type 863 "sizei" to be consistent with other GL commands accepting a <count> 864 parameter (bug 10323). 865 - Clarify that passing NULL in arguments like <buffers> only affect 866 bindings <first> through <first>+<count>-1 (bug 10289). 867 - In the errors section for multi-bind commands, clarify which errors 868 apply to only a single binding and which apply to the entire call (bug 869 10289). 870 - Clarify in the spec language that BindImageTextures sets <access> to 871 READ_WRITE for all bindings, which was already in the pseudocode (bug 872 10289). 873 - Use the term "general buffer binding" in spec language stating that 874 BindBuffersBase and BindBuffersRange only affect numbered binding 875 points (bug 10289). 876 - Add issues (21) and (22). 877 878 Revision 7, May 18, 2013 879 - Fix typo in the description of BindSamplers. 880 881 Revision 6, May 17, 2013 882 - Modify the pseudocode for BindTextures to add in TEXTURE0 to the 883 value passed to ActiveTexture, since it takes an enum and not an 884 integer. 885 886 Revision 5, May 10, 2013 887 - Define lookupInternalFormat in pseudocode example. 888 889 Revision 4, May 2, 2013 890 - Renamed entry points for buffer bindings from BindBuffers() and 891 BindBufferRanges() to BindBuffersBase() and BindBuffersRange(), 892 respectively. 893 - Add an INVALID_OPERATION error if a non-zero texture passed to 894 BindImageTextures() does not have a defined image array. 895 - Add an "unless otherwise noted" qualification to the general spec rule 896 that commands producing errors do not modify the GL state. Multi-bind 897 commands have special error behavior discussed in issue (11). 898 - Mark issues resolved based on previous spec reviews. 899 - Added issue (20). 900 901 Revision 3, April 19, 2013 902 - Add a BindImageTextures API to bind a collection of textures to image 903 units (for shader image loads/stores). 904 - Fix the spec to consistently use the parameter name <first> to 905 identify the first binding point to update. 906 - Add new issues. 907 908 Revision 2, January 20, 2013 909 - Fix various specification errors. 910 - Add an issue about whether we should provide a multi-bind API for 911 framebuffer object attachments. 912 913 Revision 1, January 18, 2013 914 - Initial revision. 915