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