1Name 2 3 ARB_buffer_storage 4 5Name Strings 6 7 GL_ARB_buffer_storage 8 9Contact 10 11 Graham Sellers (graham.sellers 'at' amd.com) 12 13Contributors 14 15 Jeff Bolz, NVIDIA 16 Daniel Koch, NVIDIA 17 Jon Leech 18 Mark Kilgard, NVIDIA 19 20Notice 21 22 Copyright (c) 2013 The Khronos Group Inc. Copyright terms at 23 http://www.khronos.org/registry/speccopyright.html 24 25Specification Update Policy 26 27 Khronos-approved extension specifications are updated in response to 28 issues and bugs prioritized by the Khronos OpenGL Working Group. For 29 extensions which have been promoted to a core Specification, fixes will 30 first appear in the latest version of that core Specification, and will 31 eventually be backported to the extension document. This policy is 32 described in more detail at 33 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 34 35Status 36 37 Complete. Approved by the ARB on June 3, 2013. 38 Ratified by the Khronos Board of Promoters on July 19, 2013. 39 40Version 41 42 Last Modified Date: April 20, 2015 43 Revision: 25 44 45Number 46 47 ARB Extension #144 48 49Dependencies 50 51 This extension is written against version 4.3 of the Core Profile OpenGL 52 Specification, dated August 6, 2012. 53 54 The definition of this extension is affected by the presence of 55 GL_EXT_direct_state_access. 56 57Overview 58 59 OpenGL has long supported buffer objects as a means of storing data 60 that may be used to source vertex attributes, pixel data for textures, 61 uniforms and other elements. In un-extended GL, buffer data stores 62 are mutable - that is, they may be de-allocated or resized while they 63 are in use. The GL_ARB_texture_storage extension added immutable storage 64 for texture object (and was subsequently incorporated into OpenGL 4.2). 65 This extension further applies the concept of immutable storage to 66 buffer objects. If an implementation is aware of a buffer's immutability, 67 it may be able to make certain assumptions or apply particular 68 optimizations in order to increase performance or reliability. 69 70 Furthermore, this extension allows applications to pass additional 71 information about a requested allocation to the implementation which it 72 may use to select memory heaps, caching behavior or allocation strategies. 73 74 Finally, this extension introduces the concept of persistent client 75 mappings of buffer objects, which allow clients to retain pointers to a 76 buffer's data store returned as the result of a mapping, and to issue 77 drawing commands while those mappings are in place. 78 79New Procedures and Functions 80 81 void BufferStorage(enum target, 82 sizeiptr size, 83 const void * data, 84 bitfield flags); 85 86 When EXT_direct_state_access is present: 87 88 void NamedBufferStorageEXT(uint buffer, 89 sizeiptr size, 90 const void * data, 91 bitfield flags); 92 93New Tokens 94 95 Accepted in the <flags> parameter of BufferStorage and 96 NamedBufferStorageEXT: 97 98 MAP_READ_BIT 0x0001 (existing) 99 MAP_WRITE_BIT 0x0002 (existing) 100 MAP_PERSISTENT_BIT 0x0040 101 MAP_COHERENT_BIT 0x0080 102 DYNAMIC_STORAGE_BIT 0x0100 103 CLIENT_STORAGE_BIT 0x0200 104 105 Accepted as part of the <access> parameter to MapBufferRange: 106 107 MAP_PERSISTENT_BIT 0x00000040 108 MAP_COHERENT_BIT 0x00000080 109 110 Accepted by the <pname> parameter of GetBufferParameter{i|i64}v: 111 112 BUFFER_IMMUTABLE_STORAGE 0x821F 113 BUFFER_STORAGE_FLAGS 0x8220 114 115 Accepted by the <barriers> parameter of MemoryBarrier: 116 117 CLIENT_MAPPED_BUFFER_BARRIER_BIT 0x00004000 118 119IP Status 120 121 No known IP claims. 122 123Additions to Chapter 2 of the OpenGL Core Profile Specification, Version 4.3, 124"OpenGL Fundamentals" 125 126 Insert before the last line of Section 2.5.2, "Buffer Objects", p. 26: 127 128 Under certain circumstances, the data store of a buffer object may 129 be shared between the client and server and accessed simultaneously 130 by both. 131 132Additions to Chapter 6 of the OpenGL Core Profile Specification, Version 4.3, 133"Buffer Objects" 134 135 Modify Section 6.2, "Creating and Modifying Buffer Object Data Stores", 136 p. 57 as follows: 137 138 The data store of a buffer object is created by calling 139 140 void BufferStorage(enum target, 141 sizeiptr size, 142 const void * data, 143 bitfield flags); 144 145 with <target> set to one of the targets listed in Table 6.1, <size> set to 146 the size of the data store in basic machine units and <flags> containing 147 a bit-field describing the intended usage of the data store. The data 148 store of the buffer object bound to <target> is allocated as a result of 149 a call to this function and cannot be de-allocated until the buffer is 150 deleted with a call to DeleteBuffers. Such a store may not be 151 re-allocated through further calls to BufferStorage or BufferData. 152 153 <data> specifies the address in client memory of the data that should 154 be used to initialize the buffer's data store. If <data> is NULL, the 155 data store of the buffer is created, but contains undefined data. 156 Otherwise, <data> should point to an array of at least <size> basic 157 machine units. 158 159 <flags> is the bitwise OR of flags describing the intended usage 160 of the buffer object's data store by the application. Valid flags and 161 their meanings are as follows: 162 163 DYNAMIC_STORAGE_BIT The contents of the data store may be 164 updated after creation through calls to BufferSubData. If this bit is not 165 set, the buffer content may not be directly updated by the client. The 166 <data> argument may be used to specify the initial content of the buffer's 167 data store regardless of the presence of the DYNAMIC_STORAGE_BIT. 168 Regardless of the presence of this bit, buffers may always be updated 169 with server-side calls such as CopyBufferSubData and ClearBufferSubData. 170 171 MAP_READ_BIT The buffer's data store may be mapped by the client for 172 read access and a pointer in the client's address space obtained that may 173 be read from. 174 175 MAP_WRITE_BIT The buffer's data store may be mapped by the client for 176 write access and a pointer in the client's address space obtained that may 177 be written to. 178 179 MAP_PERSISTENT_BIT The client may request that the server read from 180 or write to the buffer while it is mapped. The client's pointer to the 181 data store remains valid so long as the data store is mapped, even during 182 execution of drawing or dispatch commands. 183 184 MAP_COHERENT_BIT Shared access to buffers that are simultaneously 185 mapped for client access and are used by the server will be coherent, so 186 long as that mapping is performed using MapBufferRange. That is, data 187 written to the store by either the client or server will be immediately 188 visible to the other with no further action taken by the application. In 189 particular: 190 191 - If MAP_COHERENT_BIT is not set and the client performs a write 192 followed by a call to one of the FlushMapped*BufferRange commands 193 with a range including the written range, then in subsequent 194 commands the server will see the writes. 195 196 - If MAP_COHERENT_BIT is set and the client performs a write, then in 197 subsequent commands the server will see the writes. 198 199 - If MAP_COHERENT_BIT is not set and the server performs a write, the 200 application must call MemoryBarrier with the 201 CLIENT_MAPPED_BUFFER_BARRIER_BIT set and then call FenceSync with 202 SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the 203 writes after the sync is complete. 204 205 - If MAP_COHERENT_BIT is set and the server does a write, the app must 206 call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the 207 CPU will see the writes after the sync is complete. 208 209 CLIENT_STORAGE_BIT When all other criteria for the buffer storage 210 allocation are met, this bit may be used by an implementation to determine 211 whether to use storage that is local to the server or to the client to 212 serve as the backing store for the buffer. 213 214 If <flags> contains MAP_PERSISTENT_BIT, it must also contain at least one 215 of MAP_READ_BIT or MAP_WRITE_BIT. 216 217 It is an error to specify MAP_COHERENT_BIT without also specifying 218 MAP_PERSISTENT_BIT. 219 220 BufferStorage deletes any existing data store, and sets the values of 221 the buffer object's state variables as shown in table 6.3. 222 223 If any portion of the buffer object is mapped in the current context or 224 any context current to another thread, it is as though UnmapBuffer (see 225 section 6.3.1) is executed in each such context prior to deleting the 226 existing data store. 227 228 Name | Value for | Value for 229 | BufferData | BufferStorage 230 -------------------------+-----------------------+--------------- 231 BUFFER_SIZE | <size> | <size> 232 BUFFER_USAGE | <usage> | DYNAMIC_DRAW 233 BUFFER_ACCESS | READ_WRITE | READ_WRITE 234 BUFFER_ACCESS_FLAGS | 0 | 0 235 BUFFER_IMMUTABLE_STORAGE | FALSE | TRUE 236 BUFFER_MAPPED | FALSE | FALSE 237 BUFFER_MAP_POINTER | NULL | NULL 238 BUFFER_MAP_OFFSET | 0 | 0 239 BUFFER_MAP_LENGTH | 0 | 0 240 BUFFER_STORAGE_FLAGS | MAP_READ_BIT | | <flags> 241 | MAP_WRITE_BIT | | 242 | DYNAMIC_STORAGE_BIT | 243 Table 6.3: Buffer object state after calling BufferData or 244 BufferStorage. 245 246 A mutable data store may be allocated for a buffer object by calling 247 248 void BufferData(...) 249 250 <include the remainder of Section 6.2 as written, and then append>. 251 252 Calling BufferData is equivalent to calling BufferStorage with 253 <target>, <size> and <data> as specified, and <flags> set to the logical 254 OR of DYNAMIC_STORAGE_BIT, MAP_READ_BIT and MAP_WRITE_BIT. The GL will 255 use the value of <usage> parameter to BufferData as a hint to further 256 determine the intended use of the buffer. However, BufferStorage allocates 257 immutable storage whereas BufferData allocates mutable storage. Thus, when 258 a buffer's data store is allocated through a call to BufferData, the 259 buffer's BUFFER_IMMUTABLE_STORAGE flags is set to FALSE. 260 261 Add the following errors: 262 263 An INVALID_OPERATION error is generated by BufferData and BufferStorage 264 if the BUFFER_IMMUTABLE_STORAGE flag of the buffer bound to <target> is 265 set to TRUE. 266 267 An INVALID_OPERATION error is generated by BufferSubData if the 268 BUFFER_IMMUTABLE_STORAGE flag of the buffer bound to <target> is TRUE 269 and the value of BUFFER_STORAGE_FLAGS for the buffer does not have 270 the DYNAMIC_STORAGE_BIT set. 271 272 The command: 273 274 void NamedBufferStorageEXT(uint buffer, 275 sizeiptr size, 276 const void * data, 277 bitfield flags); 278 279 behaves similarly to BufferStorage, except that the buffer whose storage 280 is to be defined is specified by <buffer> rather than by the current 281 binding to <target>. 282 283 Add the following error: 284 285 An INVALID_OPERATION error is generated by NamedBufferStorageEXT if 286 the BUFFER_IMMUTABLE_STORAGE flag of <buffer> is set to TRUE. 287 288 Append to Table 6.2, "Buffer object parameters and their values": 289 290 +---------------------------+---------+-----------+------------------+ 291 | | | Initial | Legal | 292 | Name | Type | Value | Values | 293 +---------------------------+---------+-----------+------------------+ 294 | BUFFER_IMMUTABLE_STORAGE | boolean | FALSE | TRUE, FALSE | 295 | BUFFER_STORAGE_FLAGS | int | 0 | See section 6.2 | 296 +---------------------------+---------+-----------+------------------+ 297 298 Append to Table 6.3, "Buffer object initial state": 299 300 +---------------------------+-------------------------------------- + 301 | Name | Value | 302 +---------------------------+---------------------------------------+ 303 | BUFFER_IMMUTABLE_STORAGE | TRUE if the buffer's storage is | 304 | | immutable, FALSE otherwise | 305 | BUFFER_STORAGE_FLAGS | 0 | 306 +---------------------------+---------------------------------------+ 307 308 Modify Section 6.3, "Mapping and Unmapping Buffer Data" 309 310 Add to the bulleted list describing flags that modify buffer mappings, 311 p.62. 312 313 * MAP_PERSISTENT_BIT indicates that it is not an error for the GL to 314 read data from or write data to the buffer while it is mapped (see 315 section 6.3.2). If this bit is set, the value of 316 BUFFER_STORAGE_FLAGS for the buffer being mapped must include 317 MAP_PERSISTENT_BIT. 318 319 * MAP_COHERENT_BIT indicates that the mapping should be performed 320 coherently. That is, such a mapping follows the rules set forth in 321 section 6.2, "Creating and Modifying Buffer Object Data Stores". 322 If the MAP_COHERENT_BIT is set and the buffer's BUFFER_STORAGE_FLAGS 323 does not include MAP_COHERENT_BIT, the error INVALID_OPERATION is 324 generated. 325 326 Modify Section 6.3.2, "Effects of Mapping Buffers on Other GL Commands" 327 to read: 328 329 An INVALID_OPERATION error is generated by most, but not all GL 330 commands when an attempt is detected by such a command to read data from 331 or write data to a mapped buffer object unless it was allocated with the 332 by a call to BufferStorage with MAP_PERSISTENT_BIT set in 333 <flags>. 334 335 Any command which does not detect these attempts, and performs such an 336 invalid read or write, has undefined results and may result in GL 337 interruption or termination. 338 339 Add the following to the description of FlushMappedBufferRange: 340 341 If a buffer range is mapped with both the MAP_PERSISTENT_BIT and 342 MAP_FLUSH_EXPLICIT_BIT set, then FlushMappedBufferRange may be called to 343 ensure that data written by the client into the flushed region becomes 344 visible to the server. Data written to a coherent store will always 345 become visible to the server after an unspecified period of time. 346 347 Modify Section 6.8, "Buffer Object State", p. 70: 348 349 Add the following required state to a buffer object: 350 351 ..., a boolean indicating whether or not buffer storage is 352 immutable, an unsigned integer storing the flags with which it was 353 allocated, ... 354 355Additions to Chapter 7 of the OpenGL Core Profile Specification, Version 4.3, 356"Programs and Shaders" 357 358 Add to the list of flags accepted by the <barriers> parameter to 359 MemoryBarrier in Section 7.12.2, "Shader Memory Access Synchronization": 360 361 * CLIENT_MAPPED_BUFFER_BARRIER_BIT: Access by the client to persistent 362 mapped regions of buffer objects will reflect data written by shaders 363 prior to the barrier. Note that this may cause additional 364 synchronization operations. 365 366New State 367 368 Append to Table 23.6, "Buffer Object State", p. 511: 369 370 +---------------------------+-----------+----------------------+-------------------+---------------------------------+------------+ 371 | Get Value | Type | Get Command | Initial Value | Description | Sec. | 372 +---------------------------+-----------+----------------------+-------------------+---------------------------------+------------+ 373 | BUFFER_IMMUTABLE_STORAGE | B | GetBufferParameteriv | FALSE | TRUE if buffer's data store is | 6 | 374 | | | | | immutable, FALSE otherwise | | 375 | BUFFER_STORAGE_FLAGS | Z+ | GetBufferParameteriv | 0 | The buffer object's storage | 6 | 376 | | | | | flags. | | 377 +---------------------------+-----------+----------------------+-------------------+---------------------------------+------------+ 378 379New Implementation Dependent State 380 381 None. 382 383Errors 384 385 INVALID_OPERATION is generated by BufferStorage if zero is bound to 386 <target>. 387 388 INVALID_OPERATION is generated by BufferStorage, NamedBufferStorageEXT 389 and BufferData if the buffer object already owns an immutable data 390 store. 391 392 INVALID_VALUE is generated by BufferStorage and NamedBufferStorageEXT 393 if <size> is less than or equal to zero. 394 395 INVALID_VALUE is generated by BufferStorage and NamedBufferStorageEXT if 396 <flags> contains MAP_PERSISTENT_BIT but does not contain 397 at least one of MAP_READ_BIT or 398 MAP_WRITE_BIT. 399 400 INVALID_VALUE is generated by BufferStorage and NamedBufferStorageEXT if 401 <flags> contains MAP_COHERENT_BIT, but does not also 402 contain MAP_PERSISTENT_BIT. 403 404 INVALID_OPERATION is generated by MapBufferRange if any of MAP_READ_BIT, 405 MAP_WRITE_BIT, MAP_PERSISTENT_BIT, or MAP_COHERENT_BIT are included in 406 <access>, but the same bit is not included in the buffer's storage 407 flags. 408 409 INVALID_OPERATION is generated by MapBufferRange if MAP_PERSISTENT_BIT 410 is included in <access> but MAP_PERSISTENT_BIT is not 411 included in the buffer's storage flags, or if MAP_COHERENT_BIT is included 412 in <access> but MAP_COHERENT_BIT is not 413 included in the buffer's storage flags. 414 415 OUT_OF_MEMORY is generated by BufferStorage and NamedBufferStorageEXT if 416 the GL is not able to allocate a data store with the properties requested 417 in <flags>. 418 419 *REMOVE* all errors generated by any command should they detect access to 420 a mapped buffer and replace with language such as: 421 422 INVALID_OPERATION is generated by <command> if the buffer is currently 423 mapped by MapBuffer{Range} unless it was mapped with the 424 MAP_PERSISTENT_BIT included in <access>. 425 426Dependencies on GL_EXT_direct_state_access 427 428 If GL_EXT_direct_state_access is not supported, remove all references to 429 NamedBufferStorageEXT. 430 431Conformance Tests 432 433 TBD 434 435Usage Examples 436 437 Example 1: Updating the content of a buffer which does not have the 438 DYNAMIC flag set: 439 440 // Allocate two buffers, one of which will be our 'staging buffer'. 441 GLuint bufs[2]; 442 glGenBuffers(2, &bufs[0]); 443 444 // Client can map this buffer for write. 445 // One could possibly make this mapping persistent. 446 glBindBuffer(GL_COPY_READ_BUFFER, bufs[0]); 447 glBufferStorage(GL_COPY_READ_BUFFER, size, NULL, 448 GL_MAP_WRITE_BIT); 449 450 // Client cannot read or write this buffer, server can do both. 451 glBindBuffer(GL_COPY_WRITE_BUFFER, bufs[1]); 452 glBufferStorage(GL_COPY_WRITE_BUFFER, size, NULL, 0); 453 454 // Now, map the staging buffer to put data into it. 455 void * data = glMapBufferRange(GL_COPY_READ_BUFFER, 0, size, 456 GL_MAP_WRITE_BIT | 457 GL_MAP_INVALIDATE_BUFFER_BIT); 458 memcpy(data, source_data, size); 459 glUnmapBuffer(GL_COPY_READ_BUFFER); 460 461 // Copy from the staging buffer to the server-side buffer. 462 glCopyBufferSubData(GL_COPY_READ_BUFFER, GL_COPY_WRITE_BUFFER, 0, 0, size); 463 464 Example 2: Read from framebuffer into a buffer mapped into client's 465 address space: 466 467 // Create buffer, allocate storage, and create a persistent map. 468 GLuint pbo; 469 glGenBuffers(1, &pbo); 470 glBindBuffer(GL_PIXEL_PACK_BUFFER, pbo); 471 glBufferStorage(GL_PIXEL_PACK_BUFFER, size, NULL, 472 GL_MAP_READ_BIT | 473 GL_MAP_PERSISTENT_BIT); 474 475 void * data = glMapBufferRange(GL_PIXEL_PACK_BUFFER, 476 GL_MAP_READ_BIT | 477 GL_MAP_PERSISTENT_BIT); 478 479 glReadPixels(0, 0, width, height, format, type, NULL); 480 glMemoryBarrier(GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT); 481 GLsync fence = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0); 482 483 // Do stuff to use time... 484 ReallyExpensiveFunction(); 485 486 glClientWaitSync(fence); 487 488 // Use the data written to the buffer 489 UseDataInMemory(data); 490 491 XXX TODO::: MORE EXAMPLES HERE 492 493Issues 494 495 1) What is the best strategy to allow 'render while mapped'? Options I 496 can think of right now are (a) Allow the application to render when a 497 buffer is mapped, so long as the MAP_PERSISTENT_BIT 498 was set when it was allocated; (b) Continue to disallow 'render while 499 mapped', but say that a client pointer obtained from MapBuffer{Range} 500 remains valid even when the buffer is not mapped, so long as it has 501 not been destroyed; (c) add a flag to glMapBufferRange's <access> 502 parameter to indicate the desire to render with it. 503 504 RESOLVED: We choose a combination of (a) and (c). The application must 505 both create the data store with MAP_PERSISTENT_BIT set 506 _and_ map it with MAP_PERSISTENT_BIT set in <access>. Did the same 507 for coherency too. 508 509 2) The new flags don't directly map to the <usage> parameter for 510 glBufferData and one cannot be expressed in terms of the other. Does 511 that matter? 512 513 RESOLVED: Most applications get <usage> wrong and they're only hints 514 anyway. The flags are hard and fast rules that must be followed. They 515 serve a different purpose. The idea here is to allow the 516 implementation to not have to second guess the application and to 517 perform less tracking, and for the application to have more control. 518 We define BufferData in terms of BufferStorage with the most liberal 519 allowed flags (essentially, anything goes), but still pass the 520 <usage> hint to the implementation to allow it to continue to second 521 guess the application. 522 523 3) Do we have all the flags we want? Are any problematic? 524 525 RESOLVED: We don't want any more flags. We don't believe any are 526 problematic. 527 528 4) Should we include MULTI_TARGET_BIT? There are legitimate use cases where 529 a buffer could be used on two or three targets. However, this bit is an 530 'all or nothing' kind of thing. 531 532 RESOLVED: No, not at this time. 533 534 5) How do you get data into a non-dynamic buffer if you can't write to it 535 from the client? 536 537 RESOLVED: The server is capable of writing to buffers that were not 538 allocated with the DYNAMIC flag set. Therefore, it is possible to 539 use CopyBufferSubData to copy from a dynamic buffer to a non-dynamic 540 buffer. It's also possible to write to it with any other server-side 541 mechanism such as transform feedback, image stores and so on. 542 543 6) If a buffer is allocated without the GL_BUFFER_STORAGE_SERVER_READ_BIT 544 (or GL_BUFFER_STORAGE_SERVER_WRITE_BIT), what happens if an attempt is 545 made use the buffer in a way that may cause the server to read 546 (or write) to the buffer? 547 548 RESOLVED: Nuked the SERVER_READ and SERVER_WRITE bits. They didn't 549 serve the purpose for which they were intended. 550 551 7) Which operations are able to update buffers that are not dynamic? 552 553 Non-dynamic buffers effectively don't allow direct transfer of data 554 from client to server (i.e., glBufferSubData). Examples of operations 555 that may write to non-dynamic buffers are transform feedback, image 556 stores, ReadPixels, GetTexImage (PBO), CopyBufferSubData, 557 ClearBufferSubData - essentially anything that doesn't transfer 558 arbitrary amounts of data from client to server. 559 560 8) Are there any restrictions on calling GetBufferSubData on a buffer 561 allocated using BufferStorage? 562 563 RESOLVED: No, there are not. 564 565 9) What is the meaning of CLIENT_STORAGE_BIT? Is it one of those 566 silly hint things? 567 568 DISCUSSION: Unfortunately, yes, it is. For some platforms, such as UMA 569 systems, it's irrelevant and all memory is both server and client 570 accessible. The issue is, that on some platforms and for certain 571 combinations of flags, there may be multiple regions of memory that 572 can satisfy the request (visible to both server and client and coherent 573 to both, for example), but may have substantially different performance 574 characteristics for access from either. This bit essentially serves 575 as a hint to say that that an application will access the store more 576 frequently from the client than from the server. In practice, 577 applications will still get it wrong (like setting it all the time or 578 never setting it at all, for example), implementations will still have 579 to second guess applications and end up full of heuristics to figure out 580 where to put data and gobs of code to move things around based on what 581 applications do, and eventually it'll make no difference whether 582 applications set it or not. But hey, we tried. 583 584 10) Do we want to add flags for MapBufferRange for PERSISTENT and/or 585 COHERENT mapping? In their absence, implementations must assume that 586 any mapping performed on a buffer whose storage flags include the 587 PERSISTENT or COHERENT flags must behave appropriately. 588 589 RESOLVED. Added. 590 591 11) Do we need language to explicitly say that flushes of non-coherent 592 mapped buffers need to occur on buffers mapped with the FLUSH_EXPLICIT 593 bit? 594 595 RESOLVED: No. The language already states that FlushMappedBufferRange 596 should be used to perform the flush, and this command requires that 597 the mapping be established with the FLUSH_EXPLICIT bit set. 598 599 12) Which functions can/cannot be used to update the content of a 600 non-DYNAMIC buffer? Can the buffer be the target of an update 601 operation at all? 602 603 RESOLVED: BufferSubData is only allowed for DYNAMIC buffers. Updates 604 through mappings are allowed so long as the STORAGE_MAP_WRITE_BIT is 605 set. Server side commands, including CopyBufferSubData, 606 ClearBufferSubData, ReadPixels, GetTexImage are allowed. Further, 607 shader writes such as image stores, SSBO, atomic counters, transform 608 feedback and so on are also allowed. 609 610 13) Why is there a gap between the MAP_WRITE_BIT and MAP_PERSISTENT_BIT 611 token values? 612 613 RESOLVED: MAP_PERSISTENT_BIT and MAP_COHERENT_BIT are allocated from 614 the bitfield used for MapBufferRange, which include values that 615 aren't relevant for BufferStorage. This allows the same tokens 616 to be used as flags for BufferStorage and MapBufferRange, hopefully 617 reducing confusion. 618 619Revision History 620 621 Rev. Date Author Changes 622 ---- -------- -------- ----------------------------------------- 623 624 1 01/16/2013 gsellers Initial draft 625 626 2 01/21/2013 gsellers Updates 627 628 3 01/22/2013 gsellers Change static->dynamic. Remove target 629 restrictions. Get a little closer to expressing 630 BufferData in terms of BufferStorage. 631 632 4 04/22/2013 gsellers Add CLIENT_MAPPED_BUFFER_ACCESS_BIT for 633 MemoryBarrier. 634 Add BUFFER_STORAGE_{READ|WRITE}_BIT and issue 6. 635 Add example usage for non-dynamic buffers. 636 Add issue 7. 637 638 5 04/23/2013 gsellers Nuked the BUFFER_STORAGE_{READ|WRITE}_BIT 639 flags again. 640 Make DYNAMIC and MAP_WRITE_BIT 641 orthogonal. 642 Rename CLIENT_MAPPED_BUFFER_ACCESS_BIT to 643 CLIENT_MAPPED_BUFFER_BARRIER_BIT. 644 Add another example. 645 Update values of tokens. 646 Add (and resolve) issue 8. 647 648 6 05/14/2013 gsellers Add BUFFER_STORAGE_SERVER_BIT. 649 Define value of <usage> for buffers allocated 650 with BufferStorage. Issue 9. 651 652 7 05/22/2013 gsellers Address several issues from bug 10246. 653 654 8 05/23/2013 gsellers Address issues from bug 10288. 655 * Change BUFFER_STORAGE_SERVER_BIT to 656 CLIENT_STORAGE_BIT (inverting its 657 sense), which makes 0 'fast'. 658 * Clarify that DYNAMIC_BIT only affects 659 BufferSubData (i.e., direct, arbitrary 660 client->server transfers). 661 * Add issues 11 + 12. 662 663 9 05/28/2013 Jon Leech Fix various typos resulting from changes 664 in token names, tweak language to match API 665 spec, some paragraph reflowing, insert some 666 questions marked by '**' inline. 667 668 10 05/29/2013 gsellers Remove <target> parameter from 669 NamedBufferStorageEXT. 670 Incorporate new rules for coherency. 671 Add COHERENT_MAP_BIT for MapBufferRange. 672 673 11 05/30/2013 Jon Leech Fix typos including COHERENT_MAP_BIT 674 -> MAP_COHERENT_BIT and PERSISTENT_MAP_BIT 675 -> MAP_PERSISTENT_BIT. 676 677 12 05/30/2013 gsellers Resolve issues 3 and 10. Fix typos. 678 Resolve issues from bug 10326. 679 Add (and resolve) issue 13. 680 681 13 05/30/2013 gsellers Change names of flags (again). 682 Use same values for MapBufferRange flags 683 and BufferStorage flags. 684 685 14 05/30/2013 Jon Leech Clean up language describing flags and 686 some indentation issues. 687 688 15 05/31/2013 Jon Leech Add BUFFER_IMMUTABLE_STORAGE to table 689 6.2 (Bug 10288). 690 691 16 06/06/2013 Jon Leech Change default BUFFER_IMMUTABLE_STORAGE 692 value in table 6.2 to FALSE, matching API 693 spec, since these are values when created 694 with BindBuffer. Fix typo from bug 10326. 695 696 17 06/27/2013 Jon Leech Add error for BufferSubData and fix 697 example code (Bug 10326) 698 699 18 07/03/2013 gsellers Fix language describing DYNAMIC_STORAGE_BIT 700 (mutated -> updated), and typo in description 701 of usage parameter when storage is allocated 702 with BufferStorage. (Bug 10471) 703 704 19 07/18/2013 gsellers Added missing values for MAP_PERSISTENT_BIT 705 and MAP_COHERENT_BIT. 706 707 20 07/18/2013 Jon Leech Add BufferStorage initial state to table 708 6.3 and add error when zero is bound to 709 <target> (Bug 10335). 710 711 21 07/19/2013 Jon Leech Clean up table 6.3 captions to match 712 API spec (Bug 10335). 713 714 22 08/15/2013 Jon Leech Remove error for BufferStorage and 715 NamedBufferStorageEXT if <flags> contains 716 MAP_WRITE_BIT but does not contain 717 DYNAMIC_STORAGE_BIT (Bug 10561, public Bug 718 925). 719 720 23 08/16/2013 mjk Better indicate DSA entrypoints 721 722 24 06/09/2014 Jon Leech Change query commands for buffer storage 723 state to GetBufferParameteriv (Bug 12307). 724 725 25 04/20/2015 Jon Leech Change description of MAP_COHERENT_BIT for 726 buffer storage so that barriers with 727 CLIENT_MAPPED_BUFFER_BARRIER_BIT do not need 728 to make CPU writes visible to the GPU in 729 this case without an explicit flush (Bug 730 13578). 731