1Name 2 3 ARB_vertex_buffer_object 4 5Name Strings 6 7 GL_ARB_vertex_buffer_object 8 GLX_ARB_vertex_buffer_object 9 10Contributors 11 12 Ben Ashbaugh 13 Bob Beretta 14 Pat Brown 15 Cass Everitt 16 Mandar Godse 17 James Jones 18 John Kessenich 19 Dale Kirkland 20 Jon Leech 21 Bill Licea-Kane 22 Barthold Lichtenbelt 23 Bimal Poddar 24 Thomas Roell 25 Ian Romanick 26 Jeremy Sandmel 27 Jon Paul Schelter 28 John Stauffer 29 Nick Triantos 30 Daniel Vogel 31 32Contact 33 34 Rick Hammerstone, AMD (rick.hammerstone 'at' amd.com) 35 Matt Craighead, NVIDIA Corporation (mcraighead 'at' nvidia.com) 36 Kurt Akeley, NVIDIA Corporation (kakeley 'at' nvidia.com) 37 38Notice 39 40 Copyright (c) 2003-2013 The Khronos Group Inc. Copyright terms at 41 http://www.khronos.org/registry/speccopyright.html 42 43Specification Update Policy 44 45 Khronos-approved extension specifications are updated in response to 46 issues and bugs prioritized by the Khronos OpenGL Working Group. For 47 extensions which have been promoted to a core Specification, fixes will 48 first appear in the latest version of that core Specification, and will 49 eventually be backported to the extension document. This policy is 50 described in more detail at 51 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 52 53IP Status 54 55 None. 56 57Status 58 59 Complete. Approved by ARB on February 12, 2003. 60 61Version 62 63 Last Modified Date: October 25, 2010 64 Revision: 0.99.6 65 66Number 67 68 ARB Extension #28 69 70Dependencies 71 72 Written based on the wording of the OpenGL 1.4 specification. 73 74 GL_ARB_vertex_blend affects the definition of this extension. 75 76 GL_ARB_vertex_program affects the definition of this extension. 77 78 GL_EXT_vertex_shader affects the definition of this extension. 79 80 GLX_ARB_create_context affects the behavior of this extension. 81 82Overview 83 84 This extension defines an interface that allows various types of data 85 (especially vertex array data) to be cached in high-performance 86 graphics memory on the server, thereby increasing the rate of data 87 transfers. 88 89 Chunks of data are encapsulated within "buffer objects", which 90 conceptually are nothing more than arrays of bytes, just like any 91 chunk of memory. An API is provided whereby applications can read 92 from or write to buffers, either via the GL itself (glBufferData, 93 glBufferSubData, glGetBufferSubData) or via a pointer to the memory. 94 95 The latter technique is known as "mapping" a buffer. When an 96 application maps a buffer, it is given a pointer to the memory. When 97 the application finishes reading from or writing to the memory, it is 98 required to "unmap" the buffer before it is once again permitted to 99 use that buffer as a GL data source or sink. Mapping often allows 100 applications to eliminate an extra data copy otherwise required to 101 access the buffer, thereby enhancing performance. In addition, 102 requiring that applications unmap the buffer to use it as a data 103 source or sink ensures that certain classes of latent synchronization 104 bugs cannot occur. 105 106 Although this extension only defines hooks for buffer objects to be 107 used with OpenGL's vertex array APIs, the API defined in this 108 extension permits buffer objects to be used as either data sources or 109 sinks for any GL command that takes a pointer as an argument. 110 Normally, in the absence of this extension, a pointer passed into the 111 GL is simply a pointer to the user's data. This extension defines 112 a mechanism whereby this pointer is used not as a pointer to the data 113 itself, but as an offset into a currently bound buffer object. The 114 buffer object ID zero is reserved, and when buffer object zero is 115 bound to a given target, the commands affected by that buffer binding 116 behave normally. When a nonzero buffer ID is bound, then the pointer 117 represents an offset. 118 119 In the case of vertex arrays, this extension defines not merely one 120 binding for all attributes, but a separate binding for each 121 individual attribute. As a result, applications can source their 122 attributes from multiple buffers. An application might, for example, 123 have a model with constant texture coordinates and variable geometry. 124 The texture coordinates might be retrieved from a buffer object with 125 the usage mode "STATIC_DRAW", indicating to the GL that the 126 application does not expect to update the contents of the buffer 127 frequently or even at all, while the vertices might be retrieved from 128 a buffer object with the usage mode "STREAM_DRAW", indicating that 129 the vertices will be updated on a regular basis. 130 131 In addition, a binding is defined by which applications can source 132 index data (as used by DrawElements, DrawRangeElements, and 133 MultiDrawElements) from a buffer object. On some platforms, this 134 enables very large models to be rendered with no more than a few 135 small commands to the graphics device. 136 137 It is expected that a future extension will allow sourcing pixel data 138 from and writing pixel data to a buffer object. 139 140Issues 141 142 What should this extension be called? 143 144 RESOLVED: By unanimous consent among the working group members, 145 the name was chosen to be "ARB_vertex_buffer_object". A large 146 number of other names were considered throughout the lifetime of 147 the proposal, especially "vertex_array_object" (originally), 148 "buffer_object" (later on), and "memory_object" (near the end), 149 but the name "vertex_buffer_object" was ultimately chosen. 150 151 In particular, this name emphasizes not only that we have created 152 a new type of object that encapsulates arbitrary data (buffer 153 objects), but also, in particular, that these objects are used in 154 this extension to source vertex data. The name also is 155 intentionally similar to "vertex buffers", although it should be 156 emphasized that there is no such thing as a "vertex buffer" in 157 the terminology of this extension. The term "buffer object" is 158 the correct noun. 159 160 How is this extension different from ATI_vertex_array_object plus 161 ATI_map_object_buffer? 162 163 The following summarizes the major differences. 164 - VAOs renamed to "buffer objects", to signify that they can be 165 used for more than just vertex data. Other renaming and API 166 changes to try to better match OpenGL conventions. 167 - The standard GL pointer APIs have been overloaded to be able to 168 refer to offsets within these buffers, rather than adding new 169 entry points. 170 - The usage modes permitted for buffers have been augmented 171 significantly, to reflect a broader class of application 172 behaviors. 173 - A new entry point allows reading back the contents of a buffer 174 object. 175 176 How is this extension different from NV_vertex_array_range? 177 178 The following summarizes the major differences. 179 - Applications are no longer responsible for memory management 180 and synchronization. 181 - Applications may still access high-performance memory, but 182 this is optional, and such access is more restricted. 183 - Buffer changes (glBindBufferARB) are generally expected to 184 be very lightweight, rather than extremely heavyweight 185 (glVertexArrayRangeNV). 186 - A platform-specific allocator such as wgl/glXAllocateMemoryNV 187 is no longer required. 188 189 How does this extension relate to NV_pixel_data_range? 190 191 A future extension could be created based on the framework 192 created here that would support analogous functionality to that 193 provided by NV_pixel_data_range. Presumably, this extension 194 would require little more than two new targets for BindBuffer, 195 named (say) UNPACK_PIXELS and PACK_PIXELS. The lists of commands 196 affected by these bindings could easily be taken verbatim out of 197 the NV_pixel_data_range specification. 198 199 Should this extension include support for allowing vertex indices 200 to be stored in buffer objects? 201 202 RESOLVED: YES. It is easily and cleanly added with just the 203 addition of a binding point for the index buffer object. Since 204 our approach of overloading pointers works for any pointer in GL, 205 no additional APIs need be defined, unlike in the various 206 *_element_array extensions. 207 208 Note that it is expected that implementations may have different 209 memory type requirements for efficient storage of indices and 210 vertices. For example, some systems may prefer indices in AGP 211 memory and vertices in video memory, or vice versa; or, on 212 systems where DMA of index data is not supported, index data must 213 be stored in (cacheable) system memory for acceptable 214 performance. As a result, applications are strongly urged to 215 put their models' vertex and index data in separate buffers, to 216 assist drivers in choosing the most efficient locations. 217 218 Should the layout of an array store be defined at array store 219 creation time? 220 221 RESOLVED: NO. This could provide better performance if the 222 client specifies a data type that the hardware doesn't support, 223 but this isn't a performance path anyways, and it adds a 224 cumbersome interface on top of the extension. 225 226 Should there be some sort of scheme for allowing applications to 227 stream vertex data efficiently? 228 229 RESOLVED: YES. Applications that generate their data on the 230 fly end up doing an extra data copy unless they are given a 231 pointer into memory that the graphics hardware can DMA from. The 232 performance win from doing this can be significant. 233 234 Should the client be able to retrieve a pointer to a buffer object? 235 236 RESOLVED: YES. This solves the previous problem. Since GL 237 vertex array formats are already user-visible, this does not 238 suffer from the sorts of formatting issues that would arise if 239 the GL allowed applications to retrieve pointers to texture 240 objects or to the framebuffer. Synchronization can be a concern, 241 but proper usage of this extension will minimize its overhead. 242 243 Should this extension sit on top of the existing vertex array 244 implementation, instead of introducing a new set of API calls? 245 246 RESOLVED: YES. This simplifies the API, and separating out the 247 buffer binding from the offset/stride within the buffer leads to 248 an elegant "BindBufferARB" command that can be used for other 249 parts of GL like the pixel path. 250 251 Should buffer object state overlap with existing vertex array pointer 252 state, or should there be new drawing commands, e.g., 253 DrawArrayObject? 254 255 RESOLVED: OVERLAP. The exponential growth in drawing commands 256 is problematic. Even without this, there is already 257 ArrayElement, DrawArrays, DrawElements, DrawRangeElements, 258 MultiDrawArrays, and MultiDrawElements. 259 260 Does the buffer binding state push/pop? 261 262 RESOLVED: YES. It pushes/pops on the client with the rest of 263 the vertex array state. Some revisions of the ATI VAO spec 264 listed a push/pop attrib "objbuf", but no new bit was defined; 265 all this has been moved into the standard "vertex-array" bit. 266 267 Note that both the user-controlled binding ARRAY_BUFFER_ARB 268 binding point and the per-array bindings push and pop. 269 270 Note that additional binding points, such as ones for pixel or 271 texture transfers, would not be part of the vertex array state, 272 and thus would likely push and pop as part of the pixel store 273 (client) state when they are defined. 274 275 How is the decision whether to use the array pointer as an offset or 276 as a real pointer made? 277 278 RESOLVED: When the default buffer object (object zero) is 279 bound, all pointers behave as real pointers. When any other 280 object is bound, all pointers are treated as offsets. 281 Conceptually, one can imagine that buffer object zero is a buffer 282 object sitting at base NULL and with an extent large enough that 283 it covers all of the system's virtual address space. 284 285 Note that this approach essentially requires that binding points 286 be client (not server) state. 287 288 Can buffer objects be shared between contexts in the same way that 289 display lists are? 290 291 RESOLVED: YES. All potentially large OpenGL objects, such as 292 display lists and textures, can be shared, and this is an 293 important capability. Note, however, that sharing requires that 294 buffer objects be server (not client) state, since it is not 295 possible to share client state. 296 297 Should buffer objects be client state or server state? 298 299 RESOLVED: Server state. Arguments for client state include: 300 301 - Buffer data are stored in client-side format, making server 302 storage complex when client and server endianness differ. 303 - Vertex arrays are client state. 304 305 These arguments are outweighed by the significant advantages 306 of server state, including: 307 308 - Server state can be shared between contexts, and this is 309 expected to be an important capability (sharing of texture 310 objects is very common). 311 - In the case of indirect rendering, performance may be 312 very significantly greater for data stored on the server 313 side of the wire. 314 315 How is synchronization enforced when buffer objects are shared by 316 multiple OpenGL contexts? 317 318 RESOLVED: It is generally the clients' responsibility to 319 synchronize modifications made to shared buffer objects. GL 320 implementations will make some effort to avoid deletion of in-use 321 buffer objects, but may not be able to ensure this handling. 322 323 What happens if a currently bound buffer object is deleted? 324 325 RESOLVED: Orphan. To avoid chasing invalid pointers OpenGL 326 implementations will attempt to defer the deletion of any buffer 327 object until that object is not bound by any client in the share 328 list. It should be possible to implement this behavior 329 efficiently in the direct rendering case, but the implementation 330 may be difficult/impossible in the indirect rendering case. 331 Since synchronization during sharing is a client responsibility, 332 this behavior is acceptable. 333 334 Should there be a way to query the data in a buffer object? 335 336 RESOLVED: YES. Almost all objects in OpenGL are fully 337 queriable, and since these objects are simply byte arrays, there 338 does not seem to be any reason to do things otherwise here. The 339 primary exceptions to GL queriability are cases where such 340 functionality would be extremely burdensome to provide, as is the 341 case with display lists. 342 343 Do buffer objects survive screen resolution changes, etc.? 344 345 RESOLVED: YES. This is not mentioned in the spec, so by 346 default they behave just like other OpenGL state, like texture 347 objects -- the data is unmodified by external events like 348 modeswitches, switching the system into standby or hibernate 349 mode, etc. 350 351 What happens to a mapped buffer when a screen resolution change or 352 other such window-system-specific system event occurs? 353 354 RESOLVED: The buffer's contents may become undefined. The 355 application will then be notified at Unmap time that the buffer's 356 contents have been destroyed. However, for the remaining 357 duration of the map, the pointer returned from Map must continue 358 to point to valid memory, in order to ensure that the application 359 cannot crash if it continues to read or write after the system 360 event has been handled. 361 362 What happens to the pointer returned by MapBufferARB after a call to 363 UnmapBufferARB? 364 365 RESOLVED: The pointer becomes totally invalid. Note that 366 drivers are free to move the underlying buffer or even unmap the 367 memory, leaving the virtual addresses in question pointing at 368 nothing. Such flexibility is necessary to enable efficient 369 implementations on systems with no virtual memory; with limited 370 control over virtual memory from graphics drivers; or where 371 virtual address space is at a premium. 372 373 Are any of these commands allowed inside Begin/End? 374 375 RESOLVED: NO, with the possible exception of BindBuffer, which 376 should not be used inside a Begin/End but will have undefined 377 error behavior, like most vertex array commands. 378 379 What happens when an attempt is made to access data outside the 380 bounds of the buffer object with a command that dereferences the 381 arrays? 382 383 RESOLVED: ALLOW PROGRAM TERMINATION. In the event of a 384 software fallback, bounds checking can become impractical. Since 385 applications don't know the actual address of the buffer object 386 and only provide an offset, they can't ever guarantee that 387 out-of-bounds offsets will fall on valid memory. So it's hard to 388 do any better than this. 389 390 Of course, such an event should not be able to bring down the 391 system, only terminate the program. 392 393 What type should <offset> and <size> arguments use? 394 395 RESOLVED: We define new types that will work well on 64-bit 396 systems, analogous to C's "intptr_t". The new type "GLintptrARB" 397 should be used in place of GLint whenever it is expected that 398 values might exceed 2 billion. The new type "GLsizeiptrARB" 399 should be used in place of GLsizei whenever it is expected 400 that counts might exceed 2 billion. Both types are defined as 401 signed integers large enough to contain any pointer value. As a 402 result, they naturally scale to larger numbers of bits on systems 403 with 64-bit or even larger pointers. 404 405 The offsets introduced in this extension are typed GLintptrARB, 406 consistent with other GL parameters that must be non-negative, 407 but are arithmetic in nature (not uint), and are not sizes; for 408 example, the xoffset argument to TexSubImage*D is of type GLint. 409 Buffer sizes are typed GLsizeiptrARB. 410 411 The idea of making these types unsigned was considered, but was 412 ultimately rejected on the grounds that supporting buffers larger 413 than 2 GB was not deemed important on 32-bit systems. 414 415 Should buffer maps be client or server state? 416 417 RESOLVED: Server. If a buffer is being shared by multiple 418 clients, it will also be desirable to share the mappings of that 419 buffer. In cases where the mapping cannot shared (for example, 420 in the case of indirect rendering) queries of the map pointer by 421 clients other than the one that created the map will return a 422 null pointer. 423 424 Should "Unmap" be treated as one word or two? 425 426 RESOLVED: One word. 427 428 Should "usage" be a parameter to BufferDataARB, or specified 429 separately using a parameter specification command, e.g., 430 BufferParameteriARB? 431 432 RESOLVED: Parameter to BufferDataARB. It is desirable for the 433 implementation to know the usage when the buffer is initialized, 434 so including it in the initialization command makes sense. This 435 avoids manpage notes such as "Please specify the usage before you 436 initialize the buffer". 437 438 Should it be possible to change the usage of an initialized buffer? 439 440 RESOLVED: NO. Unless it is shown that this flexibility is 441 necessary, it will be easier for implementations to be efficient 442 if usage cannot be changed. (Except by re-initializing the 443 buffer completely.) 444 445 Should we allow for the possibility of multiple simultaneous maps for 446 a single buffer? 447 448 RESOLVED: NO. If multiple maps are allowed, the mapping 449 semantics become very difficult to understand and to specify. 450 It is also unclear that there are any benefits to offering such 451 functionality. Therefore, only one map per buffer is permitted. 452 453 Note: the limit of one map per buffer eliminates any need for 454 "sub-region" mapping. The single map always maps the entire 455 data store of the buffer. 456 457 Should it be an error to render from a currently mapped buffer? 458 459 RESOLVED: YES. Making this an error rather than undefined makes 460 the API much more bulletproof. 461 462 Should it be possible for the application to query the "viability" of 463 the data store of a buffer? 464 465 RESOLVED: NO. UnmapBuffer can return FALSE to indicate this, but 466 there is no additional query to check whether the data has been 467 lost. In general, most/all GL state is queriable, unless there 468 is a compelling reason otherwise. However, on examination, it 469 appears that there are several compelling reasons otherwise in 470 this case. In particular, the default for this state variable is 471 non-obvious (is the data "valid" when no data has been specified 472 yet?), and it's unclear when it should be reset (BufferData only? 473 BufferSubData? A successful UnmapBuffer?). After these issues 474 came to light, the query was removed from the spec. 475 476 What should the error behavior of BufferDataARB and MapBufferARB be? 477 478 RESOLVED: BufferDataARB returns no value and sets OUT_OF_MEMORY 479 if the buffer could not be created, whereas MapBufferARB returns 480 NULL and also sets OUT_OF_MEMORY if the buffer could not be 481 mapped. 482 483 Should UnmapBufferARB return a boolean indicating data integrity? 484 485 RESOLVED: YES, since the Unmap is precisely the point at which 486 the buffer can no longer be lost. 487 488 How is unaligned data handled? 489 490 RESOLVED: All client restrictions on data alignment must be met, 491 and in addition to that, all offsets must be multiples of the 492 size of the underlying data type. So, for example, float data in 493 a buffer object must have an offset that is (typically) a 494 multiple of 4. This should make the server implementation 495 easier, since this additional rule will guarantee that no 496 alignment checking is required on most platforms. 497 498 Should MapBufferARB return the pointer to the map, or should there be 499 a separate call to ask for the pointer? 500 501 RESOLVED: BOTH. For convenience, MapBufferARB returns a pointer 502 or NULL in the event of failure; but since most/all GL state is 503 queriable, you can also query the pointer at a later point in 504 time. If the buffer is not mapped, querying the pointer should 505 return NULL. 506 507 Should there be one binding point for all arrays or several binding 508 points, one for each array? 509 510 RESOLVED: One binding point for all arrays. Index data uses a 511 separate target. 512 513 Should there be a PRESERVE/DISCARD option on BufferSubDataARB? On 514 MapBufferARB? 515 516 RESOLVED: NO, NO. ATI_vertex_array_object had this option for 517 UpdateObjectBufferATI, which is the equivalent of 518 BufferSubDataARB, but it's unclear whether this has any utility. 519 There might be some utility for MapBufferARB, but forcing the 520 user to call BufferDataARB again with a NULL data pointer has 521 some advantages of its own, such as forcing the user to respecify 522 the size. 523 524 Should there be an option for MapBufferARB that guarantees 525 nonvolatile memory? 526 527 RESOLVED: NO. On systems where volatile memory spaces are a 528 concern, there is little or no way to supply nonvolatile memory 529 without crippling performance badly. In some cases, it might 530 not even be possible to implement Map except by returning system 531 memory. Systems that do not have problems with volatility are, 532 of course, welcome to return TRUE from UnmapBufferARB all the 533 time. If applications want the ease of use that results from not 534 having to check for lost data, they can still use BufferDataARB 535 and BufferSubDataARB, so the burden is not too great. 536 537 What new usages do we need to add? 538 539 RESOLVED. We have defined a 3x3 matrix of usages. The 540 pixel-related terms draw, read, and copy are used to distinguish 541 between three basic data paths: application to GL (draw), GL to 542 application (read), and GL to GL (copy). The terms stream, 543 static, and dynamic are used to identify three data access 544 patterns: specify once and use once or perhaps only a few times 545 (stream), specify once and use many times (static), and specify 546 and use repeatedly (dynamic). 547 548 Note that the "copy" and "read" usage token values will become 549 meaningful only when pixel transfer capability is added to 550 buffer objects by a (presumed) subsequent extension. 551 552 Note that the data paths "draw", "read", and "copy" are analogous 553 in both name and meaning to the GL commands DrawPixels, 554 ReadPixels, and CopyPixels, respectively. 555 556 Is it legal C to use pointers as offsets? 557 558 We haven't come to any definitive conclusion about this. The 559 proposal is to convert to pointer as: 560 561 pointer = (char *)NULL + offset; 562 563 And convert back to offset as: 564 565 offset = (char *)pointer - (char *)NULL; 566 567 Varying opinions have been expressed as to whether this is legal, 568 although no one could provide an example of a real system where 569 any problems would occur. 570 571 Should we add new Offset commands, e.g., VertexOffset, if the pointer 572 approach has some compatibility concerns? 573 574 RESOLVED: NO. The working group voted that the existing pointer- 575 as-offset approach is acceptable. 576 577 Which commands are compiled into display lists? 578 579 RESOLVED: None of the commands in this extension are compiled 580 into display lists. The reasoning is that the server may not 581 have up-to-date buffer bindings, since BindBuffer is a client 582 command. 583 584 Just as without this extension, vertex data is dereferenced 585 when ArrayElement, etc. are compiled into a display list. 586 587 Should there be a new command "DiscardAndMapBuffer" that is 588 equivalent to BufferDataARB with NULL pointer followed by 589 MapBufferARB? 590 591 RESOLVED: NO, no one has come up with a clearly superior proposal 592 that everyone can agree on. 593 594 Are any GL commands disallowed when at least one buffer object is 595 mapped? 596 597 RESOLVED: NO. In general, applications may use whatever GL 598 commands they wish when a buffer is mapped. However, several 599 other restrictions on the application do apply: the application 600 must not attempt to source data out of, or sink data into, a 601 currently mapped buffer. Furthermore, the application may not 602 use the pointer returned by Map as an argument to a GL command. 603 (Note that this last restriction is unlikely to be enforced in 604 practice, but it violates reasonable expectations about how the 605 extension should be used, and it doesn't seem to be a very 606 interesting usage model anyhow. Maps are for the user, not for 607 the GL.) 608 609 More restrictive rules were considered (for example, "after 610 calling MapBuffer, all GL commands except for UnmapBuffer produce 611 errors"), but this was considered far too restrictive. The 612 expectation is that an application might map a buffer and start 613 filling it in a different thread, but continue to render in its 614 main thread (using a different buffer or no buffer at all). So 615 no commands are disallowed simply because a buffer happens to be 616 mapped. 617 618 Should the usage and data arguments to BufferDataARB be swapped? 619 620 RESOLVED: NO. This would be more consistent with other things in 621 GL if they were swapped, but no one seems to care. If we had 622 caught this earlier, maybe, but it's just too late. 623 624 How does MultiDrawElements work? 625 626 The language gets a little confusing, but I believe it is quite 627 clearly specified in the end. The argument <indices> to 628 MultiDrawElements, which is of type "const void **", is an 629 honest-to-goodness pointer to regular old system memory, no 630 matter whether a buffer is bound or not. That memory in turn 631 consists of an array of <primcount> pointers. If no buffer is 632 bound, each of those <primcount> pointers is a regular pointer. 633 If a buffer is bound, each of those <primcount> pointers is a 634 fake pointer that represents an offset in the buffer object. 635 636 If you wanted to put the array of <primcount> offsets in a buffer 637 object, you'd have to define a new extension with a new target. 638 639 When is the binding between a buffer object and a specific vertex array 640 (e.g., VERTEX_ARRAY_BUFFER_BINDING_ARB) established? 641 642 The array's buffer binding is set when the array pointer is specified. 643 Using the vertex array as an example, this is when VertexPointer is 644 called. At that time, the current array buffer binding is used for 645 the vertex array. The current array buffer binding is set by calling 646 BindBufferARB with a <target> of ARRAY_BUFFER_ARB. Changing the 647 current array buffer binding does not affect the bindings used by 648 already established arrays. 649 650 BindBufferARB(ARRAY_BUFFER_ARB, 1); 651 VertexPointer(...); // vertex array data points to buffer 1 652 BindBufferARB(ARRAY_BUFFER_ARB, 2); 653 // vertex array data still points to buffer 1 654 655 What happens when a single ArrayElement call within a large sequence of 656 ArrayElement calls specifies an element that is outside the range of the 657 bound buffer objects? 658 659 UNRESOLVED. The three suggestions from the ARB meeting are to either 660 ignore just that ArrayElement call, set an error bit and ignore all 661 ArrayElement calls until End, or treat the ArrayElement call as 662 ArrayElement(0). 663 664 How should EnableClientState and DisableClientState be handled when using 665 indirect rendering? 666 667 RESOLVED: EnableVertexAttribArray and DisableVertexAttribArray 668 commands are used to inform the server of new enable/disable state. 669 670 When using indirect rendering, how is DrawElements handled when the 671 element array is in a buffer object but one or more of the enabled arrays 672 are not? 673 674 RESOLVED: There are two commands that can be used to implement 675 DrawElements and related calls. If all of the data resides on the 676 server, the element pointer is set by using a BindBufferToArray 677 command with array set to ELEMENT_ARRAY_ATI. This command is 678 followed by the appropriate EnableVertexAttribArray and 679 DisableVertexAttribArray calls, making sure to enable the element 680 array, and either a DrawElements call or a DrawRangeElements call. 681 682 If any arrays reside on the client, including the element array, 683 the sequence is essentially the same except the DrawRangeElements 684 protocol must be used. If the element array resides on the 685 server, the client must issue a GetElementRange command to determine 686 the range of array data (and the values for 'start' and 'end') that 687 must be sent to the server. 688 689 Is a "provoke" flag needed in the ArrayElement command protocol to switch 690 between the case where the VERTEX_ARRAY is client-side vs. server-side? 691 692 NO. The server will know whether or not the ArrayElement command 693 will provoke a vertex because it knows whether or not a buffer object 694 is bound to VERTEX_ARRAY. 695 696 How does the server know which arrays with buffer objects bound are 697 enabled in ArrayElement? 698 699 RESOLVED: The array bindings are configured using BindBuffer and 700 BindBufferToArray commands. The arrays are enabled and disabled 701 using EnableVertexAttribArray and DisableVertexAttribArray. 702 703 Can't the server-side array bindings just be sent in a the ARRAY_INFO 704 when DrawArrays is called? 705 706 NO. The only way to do that would be to transmit the offset, type, 707 size, stride, etc. parameters and the buffer ID. However, the buffer 708 may have been deleted in the meantime. The binding information must 709 be sent when the pointer function (e.g., VertexPointer) is called. 710 711 What about byte-ordering? The format of the data, and therefore what 712 byte-swapping may need to be done, is not know when the data is 713 uploaded to the server. In fact, since it is legal (though probably 714 nonsensical) to have the same bytes in the buffer be used as multiple 715 datatypes, a single byte-ordering may not exist. What happens when 716 two clients with different byte ordering share one buffer object? Is 717 it valid to not expose the extension if the byte-ordering of the 718 client and server do not match? 719 720 RESOLVED: It is the client's responsibility to convert buffer data 721 to and from the server's byte order. Since only the client knows 722 the correct format of the data, and there may be multiple clients 723 with different byte orderings sharing a single buffer object, it is 724 unreasonable to ask the GL to handle buffer object byte-swapping. 725 To avoid errors caused by naive clients attempting to use buffer 726 objects without performing the appropriate byte swapping, clients 727 must opt in to buffer object support at context creation time using 728 the GLX_CONTEXT_ALLOW_BUFFER_BYTE_ORDER_MISMATCH_ARB context attrib. 729 If this attribute is not specified and the byte ordering of the client 730 and server differ, the VBO extension must not be exposed and the 731 maximum context version that can be reported is 1.4. 732 733 Should Enable/DisableVertexAttribArray and VertexAttribPointer handle 734 both indexed and legacy arrays? 735 736 RESOLVED: Yes. Send GL_NONE for <array> when referring to 737 indexed arrays. For all other values of <array> except 738 GL_TEXTURE??, <index> is ignored. For GL_TEXTURE??, see next 739 issue. 740 741 How is the client-side state client active texture, needed by 742 glTexCoordPointer, communicated to the server? 743 744 RESOLVED: Send the active texture index using the <index> 745 parameter normally used for indexed arrays. The value of 746 <index> will be an offset from GL_TEXTURE0. 747 748 OTHER OPTIONS CONSIDERED: Add a separate parameter to 749 VertexAttribPointer rather than alias the index parameter. 750 Only advantage is slightly improved clarity. 751 752 Add ClientActiveTexture protocol. This would cause problems 753 because the active texture is client state. If two GLX processes 754 were maintaining their own client state for one server-side 755 context, it would be hard to reliably keep the active texture 756 state in sync between the client and server. It would need to be 757 tracked per client on the server. 758 759 How are Push/PopClientAttrib handled? 760 761 RESOLVED: Specify protocol for these commands. Some state 762 affected by these commands needs to be duplicated in the server 763 now, so these operations need to be duplicated there as well. 764 765 OTHER OPTIONS CONSIDERED: Break the commands down into the 766 individual commands required to perform the operation and send the 767 appropriate protocol for those commands. This is insufficient 768 because it could cause deleted buffer objects to be destroyed by 769 the server while they are still in use by a non-current entry in 770 the client's attribute stack. 771 772 How are integer arrays differentiated from floating point or fixed 773 point arrays? 774 775 RESOLVED: Added an "is_integer" boolean field to ARRAY_INFO and 776 VertexAttribPointer. 777 778 Is separate protocol needed for MapBuffer/UnmapBuffer? 779 780 RESOLVED: Yes. Buffers can only be mapped once. Buffers need 781 not be bound for the duration of their mapping, and whether a 782 buffer is mapped or not is server state, so to properly track 783 this state and generate related errors when there are multiple 784 clients sharing the same buffer object, protocol must be sent 785 to the server to duplicate the state there. 786 787 Should the MapBuffer/UnmapBuffer protocol handle transferring of 788 the buffer data when needed, or should implementations transfer the 789 data using the BufferSubData and GetBufferSubData protocol? 790 791 RESOLVED: Using the BufferSubData and GetBufferSubData protocol. 792 This simplifies the Map and Unmap protocol and allows 793 implementations to break up large data transfers into chunks. 794 For example, the buffer data may be larger than the maximum size 795 of a GLX single command. Sending the data as part of the 796 UnmapBuffer protocol would fail, but sending it in one or more 797 BufferSubData commands would still be possible. Implementations 798 should take care to retreive the data, if needed, before mapping 799 and send it back after unmapping. This does not introduce race 800 conditions because it is already up to the application to ensure 801 proper mutexing of buffer object operations is done, and the 802 protocol will still all happen within one application-visible GL 803 command. 804 805 Should client array data sent to the server in DrawArraysNew and 806 DrawRangeElements be aligned? Should individual arrays be separately 807 aligned? Should the arrays be sent be sent in order of largest 808 element type to smallest? 809 810 RESOLVED: No. The client shall send the data as one contiguous 811 array of bytes. The server shall be responsible for aligning 812 the individual entries as they are extracted if such alignment 813 is needed. 814 815 EXT_vertex_array allows enabling/disabling vertex arrays with 816 Enable/Disable. This state needs to be intercepted by the client 817 to properly manage buffer object state. Should protocol for Enable 818 and Disable still be sent when these enums are used, or should the 819 EnableClientState/DisableClientState protocol be sent instead? 820 821 RESOLVED: Send the EnableClientState/DisableClientState protocol. 822 The server may need to take additional actions for these special 823 Enable/Disable enums. Since the client already needs to 824 intercept and handle them specially, keep the protocol separate 825 for the server's benefit. 826 827New Procedures and Functions 828 829 void BindBufferARB(enum target, uint buffer); 830 void DeleteBuffersARB(sizei n, const uint *buffers); 831 void GenBuffersARB(sizei n, uint *buffers); 832 boolean IsBufferARB(uint buffer); 833 834 void BufferDataARB(enum target, sizeiptrARB size, const void *data, 835 enum usage); 836 void BufferSubDataARB(enum target, intptrARB offset, sizeiptrARB size, 837 const void *data); 838 void GetBufferSubDataARB(enum target, intptrARB offset, 839 sizeiptrARB size, void *data); 840 841 void *MapBufferARB(enum target, enum access); 842 boolean UnmapBufferARB(enum target); 843 844 void GetBufferParameterivARB(enum target, enum pname, int *params); 845 void GetBufferPointervARB(enum target, enum pname, void **params); 846 847New Tokens 848 849 Accepted as an attribute name in the <attrib_list> parameter of 850 glXCreateContextAttribsARB: 851 852 GLX_CONTEXT_ALLOW_BUFFER_BYTE_ORDER_MISMATCH_ARB 0x2095 853 854 Accepted by the <target> parameters of BindBufferARB, BufferDataARB, 855 BufferSubDataARB, MapBufferARB, UnmapBufferARB, 856 GetBufferSubDataARB, GetBufferParameterivARB, and 857 GetBufferPointervARB: 858 859 ARRAY_BUFFER_ARB 0x8892 860 ELEMENT_ARRAY_BUFFER_ARB 0x8893 861 862 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 863 GetFloatv, and GetDoublev: 864 865 ARRAY_BUFFER_BINDING_ARB 0x8894 866 ELEMENT_ARRAY_BUFFER_BINDING_ARB 0x8895 867 VERTEX_ARRAY_BUFFER_BINDING_ARB 0x8896 868 NORMAL_ARRAY_BUFFER_BINDING_ARB 0x8897 869 COLOR_ARRAY_BUFFER_BINDING_ARB 0x8898 870 INDEX_ARRAY_BUFFER_BINDING_ARB 0x8899 871 TEXTURE_COORD_ARRAY_BUFFER_BINDING_ARB 0x889A 872 EDGE_FLAG_ARRAY_BUFFER_BINDING_ARB 0x889B 873 SECONDARY_COLOR_ARRAY_BUFFER_BINDING_ARB 0x889C 874 FOG_COORDINATE_ARRAY_BUFFER_BINDING_ARB 0x889D 875 WEIGHT_ARRAY_BUFFER_BINDING_ARB 0x889E 876 877 Accepted by the <pname> parameter of GetVertexAttribivARB: 878 879 VERTEX_ATTRIB_ARRAY_BUFFER_BINDING_ARB 0x889F 880 881 Accepted by the <usage> parameter of BufferDataARB: 882 883 STREAM_DRAW_ARB 0x88E0 884 STREAM_READ_ARB 0x88E1 885 STREAM_COPY_ARB 0x88E2 886 STATIC_DRAW_ARB 0x88E4 887 STATIC_READ_ARB 0x88E5 888 STATIC_COPY_ARB 0x88E6 889 DYNAMIC_DRAW_ARB 0x88E8 890 DYNAMIC_READ_ARB 0x88E9 891 DYNAMIC_COPY_ARB 0x88EA 892 893 Accepted by the <access> parameter of MapBufferARB: 894 895 READ_ONLY_ARB 0x88B8 896 WRITE_ONLY_ARB 0x88B9 897 READ_WRITE_ARB 0x88BA 898 899 Accepted by the <pname> parameter of GetBufferParameterivARB: 900 901 BUFFER_SIZE_ARB 0x8764 902 BUFFER_USAGE_ARB 0x8765 903 BUFFER_ACCESS_ARB 0x88BB 904 BUFFER_MAPPED_ARB 0x88BC 905 906 Accepted by the <pname> parameter of GetBufferPointervARB: 907 908 BUFFER_MAP_POINTER_ARB 0x88BD 909 910 911Additions to Chapter 2 of the 1.4 Specification (OpenGL Operation) 912 913 Add to Table 2.2: 914 915 "GL Type Minimum Description 916 Bit Width 917 ----------------------------------------------------------------- 918 intptrARB <ptrbits> signed 2's complement binary integer 919 sizeiptrARB <ptrbits> Non-negative binary integer size" 920 921 Add to the paragraph under Table 2.2: 922 923 "<ptrbits> is the number of bits required to represent a pointer 924 type; in other words, types intptrARB and sizeiptrARB must be 925 sufficiently large as to store any address." 926 927 Add a new section "Buffer Objects" between sections 2.8 and 2.9: 928 929 "2.8A Buffer Objects 930 -------------------- 931 932 The vertex data arrays described in section 2.8 are stored in client 933 memory. It is sometimes desirable to store frequently used client 934 data, such as vertex array data, in high-performance server memory. 935 GL buffer objects provide a mechanism that clients can use to 936 allocate, initialize, and render from such memory. 937 938 The name space for buffer objects is the unsigned integers, with zero 939 reserved for the GL. A buffer object is created by binding an unused 940 name to ARRAY_BUFFER_ARB. The binding is effected by calling 941 942 void BindBufferARB(enum target, uint buffer); 943 944 with <target> set to ARRAY_BUFFER_ARB and <buffer> set to the unused 945 name. The resulting buffer object is a new state vector, initialized 946 with a zero-sized memory buffer, and comprising the state values 947 listed in Table BufObj1. 948 949 Name Type Initial Value Legal Values 950 ---- ---- ------------- ------------ 951 BUFFER_SIZE_ARB integer 0 any non-negative 952 integer 953 BUFFER_USAGE_ARB enum STATIC_DRAW_ARB STREAM_DRAW_ARB, 954 STREAM_READ_ARB, 955 STREAM_COPY_ARB, 956 STATIC_DRAW_ARB, 957 STATIC_READ_ARB, 958 STATIC_COPY_ARB, 959 DYNAMIC_DRAW_ARB, 960 DYNAMIC_READ_ARB, 961 DYNAMIC_COPY_ARB 962 BUFFER_ACCESS_ARB enum READ_WRITE_ARB READ_ONLY_ARB, 963 WRITE_ONLY_ARB, 964 READ_WRITE_ARB 965 BUFFER_MAPPED_ARB boolean FALSE TRUE, FALSE 966 BUFFER_MAP_POINTER_ARB void* NULL address 967 968 Table BufObj1: Buffer object parameters and their values. 969 970 BindBufferARB may also be used to bind an existing buffer object. 971 If the bind is successful no change is made to the state of the 972 newly bound buffer object, and any previous binding to <target> is 973 broken. 974 975 While a buffer object is bound, GL operations on the target to which 976 it is bound affect the bound buffer object, and queries of the target 977 to which a buffer object is bound return state from the bound object. 978 979 In the initial state the GL-reserved name zero is bound to 980 ARRAY_BUFFER_ARB. There is no buffer object corresponding to the 981 name zero, so client attempts to modify or query buffer object state 982 for the target ARRAY_BUFFER_ARB while zero is bound will generate 983 GL errors. 984 985 Buffer objects are deleted by calling 986 987 void DeleteBuffersARB(sizei n, const uint *buffers); 988 989 <buffers> contains <n> names of buffer objects to be deleted. After 990 a buffer object is deleted it has no contents, and its name is again 991 unused. Unused names in <buffers> are silently ignored, as is the 992 value zero. 993 994 The command 995 996 void GenBuffersARB(sizei n, uint *buffers); 997 998 returns <n> previously unused buffer object names in <buffers>. 999 These names are marked as used, for the purposes of GenBuffersARB 1000 only, but they acquire buffer state only when they are first bound, 1001 just as if they were unused. 1002 1003 While a buffer object is bound, any GL operations on that object 1004 affect any other bindings of that object. If a buffer object is 1005 deleted while it is bound, all bindings to that object in the current 1006 context (i.e. in the thread that called DeleteBuffers) are reset to 1007 bindings to buffer zero. Bindings to that buffer in other contexts 1008 and other threads are not affected, but attempting to use a deleted 1009 buffer in another thread produces undefined results, including but 1010 not limited to possible GL errors and rendering corruption. Using a 1011 deleted buffer in another context or thread may not, however, result 1012 in program termination. 1013 1014 The data store of a buffer object is created and initialized by 1015 calling 1016 1017 void BufferDataARB(enum target, sizeiptrARB size, 1018 const void *data, enum usage); 1019 1020 with <target> set to ARRAY_BUFFER_ARB, <size> set to the size of the 1021 data store in basic machine units, and <data> pointing to the 1022 source data in client memory. If <data> is non-null, then the source 1023 data is copied to the buffer object's data store. If <data> is null, 1024 then the contents of the buffer object's data store are undefined. 1025 1026 <usage> is specified as one of nine enumerated values, indicating 1027 the expected application usage pattern of the data store. The 1028 values are: 1029 1030 STREAM_DRAW_ARB The data store contents will be specified once 1031 by the application, and used at most a few 1032 times as the source of a GL (drawing) command. 1033 STREAM_READ_ARB The data store contents will be specified once 1034 by reading data from the GL, and queried at 1035 most a few times by the application. 1036 STREAM_COPY_ARB The data store contents will be specified once 1037 by reading data from the GL, and used at most 1038 a few times as the source of a GL (drawing) 1039 command. 1040 STATIC_DRAW_ARB The data store contents will be specified once 1041 by the application, and used many times as the 1042 source for GL (drawing) commands. 1043 STATIC_READ_ARB The data store contents will be specified once 1044 by reading data from the GL, and queried many 1045 times by the application. 1046 STATIC_COPY_ARB The data store contents will be specified once 1047 by reading data from the GL, and used many 1048 times as the source for GL (drawing) commands. 1049 DYNAMIC_DRAW_ARB The data store contents will be respecified 1050 repeatedly by the application, and used many 1051 times as the source for GL (drawing) commands. 1052 DYNAMIC_READ_ARB The data store contents will be respecified 1053 repeatedly by reading data from the GL, and 1054 queried many times by the application. 1055 DYNAMIC_COPY_ARB The data store contents will be respecified 1056 repeatedly by reading data from the GL, and 1057 used many times as the source for GL (drawing) 1058 commands. 1059 1060 <usage> is provided as a performance hint only. The specified usage 1061 value does not constrain the actual usage pattern of the data store. 1062 1063 BufferDataARB deletes any existing data store, and sets the values of 1064 the buffer object's state variables to: 1065 1066 Name Value 1067 ---- ----- 1068 BUFFER_SIZE_ARB <size> 1069 BUFFER_USAGE_ARB <usage> 1070 BUFFER_ACCESS_ARB READ_WRITE_ARB 1071 BUFFER_MAPPED_ARB FALSE 1072 BUFFER_MAP_POINTER_ARB NULL 1073 1074 Clients must align data elements consistent with the requirements 1075 of the client platform, with an additional base-level requirement 1076 that an offset within a buffer to a datum comprising N basic machine 1077 units be a multiple of N. 1078 1079 If the GL is unable to create a data store of the requested size, 1080 the error OUT_OF_MEMORY is generated. 1081 1082 To modify some or all of the data contained in a buffer object's data 1083 store, the client may use the command 1084 1085 void BufferSubDataARB(enum target, intptrARB offset, 1086 sizeiptrARB size, const void *data); 1087 1088 with <target> set to ARRAY_BUFFER_ARB. <offset> and <size> indicate 1089 the range of data in the buffer object that is to be replaced, in 1090 terms of basic machine units. <data> specifies a region of client 1091 memory <size> basic machine units in length, containing the data that 1092 replace the specified buffer range. An error is generated if 1093 <offset> or <size> is less than zero, or if <offset> + <size> is 1094 greater than the value of BUFFER_SIZE_ARB. 1095 1096 The entire data store of a buffer object can be mapped into the 1097 client's address space by calling 1098 1099 void *MapBufferARB(enum target, enum access); 1100 1101 with <target> set to ARRAY_BUFFER_ARB. If the GL is able to map the 1102 buffer object's data store into the client's address space, 1103 MapBufferARB returns the pointer value to the data store. Otherwise 1104 MapBufferARB returns NULL, and the error OUT_OF_MEMORY is generated. 1105 <access> is specified as one of READ_ONLY_ARB, WRITE_ONLY_ARB, or 1106 READ_WRITE_ARB, indicating the operations that the client may perform 1107 on the data store through the pointer while the data store is mapped. 1108 1109 MapBufferARB sets the following buffer object state values: 1110 1111 Name Value 1112 ---- ----- 1113 BUFFER_ACCESS_ARB <access> 1114 BUFFER_MAPPED_ARB TRUE 1115 BUFFER_MAP_POINTER_ARB pointer to the data store 1116 1117 It is an INVALID_OPERATION error to map a buffer data store that is 1118 in the mapped state. 1119 1120 Non-null pointers returned by MapBufferARB may be used by the client 1121 to modify and query buffer object data, consistent with the access 1122 rules of the mapping, while the mapping remains valid. No GL error 1123 is generated if the pointer is used to attempt to modify a 1124 READ_ONLY_ARB data store, or to attempt to read from a WRITE_ONLY_ARB 1125 data store, but operation may be slow and system errors (possibly 1126 including program termination) may result. Pointer values returned 1127 by MapBufferARB may not be passed as parameter values to GL commands. 1128 For example, they may not be used to specify array pointers, or to 1129 specify or query pixel or texture image data; such actions produce 1130 undefined results, although implementations may not check for such 1131 behavior for performance reasons. 1132 1133 It is an INVALID_OPERATION error to call BufferSubDataARB to modify 1134 the data store of a mapped buffer. 1135 1136 Mappings to the data stores of buffer objects may have nonstandard 1137 performance characteristics. For example, such mappings may be 1138 marked as uncacheable regions of memory, and in such cases reading 1139 from them may be very slow. To ensure optimal performance, the 1140 client should use the mapping in a fashion consistent with the values 1141 of BUFFER_USAGE_ARB and BUFFER_ACCESS_ARB. Using a mapping in a 1142 fashion inconsistent with these values is liable to be multiple 1143 orders of magnitude slower than using normal memory. 1144 1145 After the client has specified the contents of a mapped data store, 1146 and before the data in that store are dereferenced by any GL commands, 1147 the mapping must be relinquished by calling 1148 1149 boolean UnmapBufferARB(enum target); 1150 1151 with <target> set to ARRAY_BUFFER_ARB. Unmapping a mapped buffer 1152 object invalidates the pointers to its data store and sets the 1153 object's BUFFER_MAPPED_ARB state to FALSE and its 1154 BUFFER_MAP_POINTER_ARB state to NULL. 1155 1156 UnmapBufferARB returns TRUE unless data values in the buffer's data 1157 store have become corrupted during the period that the buffer was 1158 mapped. Such corruption can be the result of a screen resolution 1159 change or other window-system-dependent event that causes system 1160 heaps such as those for high-performance graphics memory to be 1161 discarded. GL implementations must guarantee that such corruption 1162 can occur only during the periods that a buffer's data store is 1163 mapped. If such corruption has occurred, UnmapBufferARB returns 1164 FALSE, and the contents of the buffer's data store become undefined. 1165 1166 It is an INVALID_OPERATION error to explicitly unmap a buffer data 1167 store that is in the unmapped state. Unmapping that occurs as a side 1168 effect of buffer deletion or reinitialization is not an error, 1169 however." 1170 1171 1172 2.8A.1 Vertex Arrays in Buffer Objects 1173 -------------------------------------- 1174 1175 Blocks of vertex array data may be stored in buffer objects with the 1176 same format and layout options supported for client-side vertex 1177 arrays. However, it is expected that GL implementations will (at 1178 minimum) be optimized for data with all components represented as 1179 floats, as well as for color data with components represented as 1180 either floats or unsigned bytes. 1181 1182 A buffer object binding point is added to the client state associated 1183 with each vertex array type. The client does not directly specify 1184 the bindings to with these new binding points. Instead, the commands 1185 that specify the locations and organizations of vertex arrays 1186 copy the buffer object name that is bound to ARRAY_BUFFER_ARB to the 1187 binding point corresponding to the vertex array of the type being 1188 specified. For example, the NormalPointer command copies the value 1189 of ARRAY_BUFFER_BINDING_ARB (the queriable name of the buffer binding 1190 corresponding to the target ARRAY_BUFFER_ARB) to the client state 1191 variable NORMAL_ARRAY_BUFFER_BINDING_ARB. 1192 1193 If EXT_vertex_shader is defined, then the command 1194 VariantArrayEXT(uint id, ...) copies the value of 1195 ARRAY_BUFFER_BINDING_ARB to the buffer object binding point 1196 corresponding to variant array <id>. 1197 1198 If ARB_vertex_program is defined, then the command 1199 VertexAttribPointerARB(int attrib, ...) copies the value of 1200 ARRAY_BUFFER_BINDING_ARB to the buffer object binding point 1201 corresponding to vertex attrib array <attrib>. 1202 1203 If ARB_vertex_blend is defined, then the command WeightPointerARB 1204 copies the value of ARRAY_BUFFER_BINDING_ARB to 1205 WEIGHT_ARRAY_BUFFER_BINDING_ARB. 1206 1207 Rendering commands ArrayElement, DrawArrays, DrawElements, 1208 DrawRangeElements, MultiDrawArrays, and MultiDrawElements operate as 1209 previously defined, except that data for enabled vertex, variant, and 1210 attrib arrays are sourced from buffers if the array's buffer binding 1211 is non-zero. When an array is sourced from a buffer object, the 1212 pointer value of that array is used to compute an offset, in basic 1213 machine units, into the data store of the buffer object. This offset 1214 is computed by subtracting a null pointer from the pointer value, 1215 where both pointers are treated as pointers to basic machine units. 1216 1217 It is acceptable for vertex, variant, or attrib arrays to be sourced 1218 from any combination of client memory and various buffer objects 1219 during a single rendering operation. 1220 1221 It is an INVALID_OPERATION error to source data from a buffer object 1222 that is currently mapped. 1223 1224 1225 2.8B.1 Array Indices in Buffer Objects 1226 ---------------------------------------------- 1227 1228 Blocks of array indices may be stored in buffer objects with the 1229 same format options that are supported for client-side index arrays. 1230 Initially zero is bound to ELEMENT_ARRAY_BUFFER_ARB, indicating that 1231 DrawElements and DrawRangeElements are to source their indices from 1232 arrays passed as their <indices> parameters, and that 1233 MultiDrawElements is to source its indices from the array of pointers 1234 to arrays passed in as its <indices> parameter. 1235 1236 A buffer object is bound to ELEMENT_ARRAY_BUFFER_ARB by calling 1237 1238 void BindBufferARB(enum target, uint buffer); 1239 1240 with <target> set to ELEMENT_ARRAY_BUFFER_ARB, and <buffer> set to 1241 the name of the buffer object. If no corresponding buffer object 1242 exists, one is initialized as defined in Section 2.8A. 1243 1244 The commands BufferDataARB, BufferSubDataARB, MapBufferARB, and 1245 UnmapBufferARB may all be used with <target> set to 1246 ELEMENT_ARRAY_BUFFER_ARB. In such event, these commands operate in 1247 the same fashion as described in section 2.8A, but on the buffer 1248 currently bound to the ELEMENT_ARRAY_BUFFER_ARB target. 1249 1250 While a non-zero buffer object name is bound to 1251 ELEMENT_ARRAY_BUFFER_ARB, DrawElements and DrawRangeElements source 1252 their indices from that buffer object, using their <indices> 1253 parameters as offsets into the buffer object in the same fashion as 1254 described in section 2.8A1. MultiDrawElements also sources its 1255 indices from that buffer object, using its <indices> parameter as a 1256 pointer to an array of pointers that represent offsets into the 1257 buffer object. 1258 1259 Buffer objects created by binding an unused name to ARRAY_BUFFER_ARB 1260 and to ELEMENT_ARRAY_BUFFER_ARB are formally equivalent, but the GL 1261 may make different choices about storage implementation based on 1262 the initial binding. In some cases performance will be optimized 1263 by storing indices and array data in separate buffer objects, and by 1264 creating those buffer objects with the corresponding binding points." 1265 1266 1267Additions to Chapter 3 of the 1.4 Specification (Rasterization) 1268 1269 None 1270 1271 1272Additions to Chapter 4 of the 1.4 Specification (Per-Fragment 1273Operations and the Frame Buffer) 1274 1275 None 1276 1277 1278Additions to Chapter 5 of the 1.4 Specification (Special Functions) 1279 1280 Added to section 5.4, as part of the discussion of what commands 1281 are compiled into display lists: 1282 1283 "Commands that are used to create, manage, and query buffer objects 1284 are not included in display lists, but are executed immediately. 1285 These commands are BindBufferARB, DeleteBuffersARB, GenBuffersARB, 1286 IsBufferARB, BufferDataARB, BufferSubDataARB, MapBufferARB, 1287 UnmapBufferARB, GetBufferParameterivARB, GetBufferSubDataARB, 1288 and GetBufferPointervARB. 1289 1290 GL commands that source data from buffer objects dereference the 1291 buffer object data in question at display list compile time, rather 1292 than encoding the buffer ID and buffer offset into the display list. 1293 Only GL commands that are executed immediately, rather than being 1294 compiled into a display list, are permitted to use a buffer object as 1295 a data sink." 1296 1297 1298Additions to Chapter 6 of the 1.4 Specification (State and State 1299Requests) 1300 1301 Added to section 6.1 in a subsection titled Buffer Object Queries: 1302 1303 "The command 1304 1305 boolean IsBufferARB(uint buffer); 1306 1307 returns TRUE if <buffer> is the name of a buffer object. If 1308 <buffer> is zero, or if <buffer> is a non-zero value that is not 1309 the name of a buffer object, IsBufferARB return FALSE. 1310 1311 The command 1312 1313 void GetBufferSubDataARB(enum target, intptrARB offset, 1314 sizeiptrARB size, void *data); 1315 1316 queries the data contents of a buffer object. <target> is 1317 ARRAY_BUFFER_ARB. <offset> and <size> indicate the range of data 1318 in the buffer object that is to be queried, in terms of basic machine 1319 units. <data> specifies a region of client memory, <size> basic 1320 machine units in length, into which the data is to be retrieved. 1321 1322 An error is generated if GetBufferSubDataARB is executed for a buffer 1323 object that is currently mapped. 1324 1325 While the data store of a buffer object is mapped, the pointer to 1326 the data store can be queried by calling 1327 1328 void GetBufferPointervARB(enum target, enum pname, void **params); 1329 1330 with <target> set to ARRAY_BUFFER_ARB and <pname> set to 1331 BUFFER_MAP_POINTER_ARB. The single buffer map pointer is returned 1332 in <params>. GetBufferPointervARB returns the NULL pointer value if 1333 the buffer's data store is not currently mapped, or if the requesting 1334 client did not map the buffer object's data store, and the 1335 implementation is unable to support mappings on multiple clients." 1336 1337 Added to the list of queries in section 6.1.3, Enumerated Queries: 1338 1339 "void GetBufferParameterivARB(enum target, enum pname, int *params);" 1340 1341 1342Errors 1343 1344 INVALID_ENUM is generated if the <target> parameter of BindBufferARB, 1345 BufferDataARB, BufferSubDataARB, MapBufferARB, UnmapBufferARB, 1346 GetBufferSubDataARB, GetBufferParameterivARB, or GetBufferPointervARB 1347 is not ARRAY_BUFFER_ARB or ELEMENT_ARRAY_BUFFER_ARB. 1348 1349 INVALID_VALUE is generated if the <n> parameter of DeleteBuffersARB or 1350 GenBuffersARB is negative. 1351 1352 INVALID_VALUE is generated if the <size> parameter of BufferDataARB, 1353 BufferSubDataARB, or GetBufferSubDataARB is negative. 1354 1355 INVALID_OPERATION is generated if BufferDataARB, BufferSubDataARB, 1356 MapBufferARB, UnmapBufferARB, GetBufferSubDataARB, 1357 GetBufferParameterivARB, or GetBufferPointervARB is executed while 1358 zero is bound to the <target> parameter. 1359 1360 OUT_OF_MEMORY may be generated if the data store of a buffer object 1361 cannot be allocated because the <size> argument of BufferDataARB is 1362 too large. 1363 1364 OUT_OF_MEMORY may be generated when MapBufferARB is called if the 1365 data store of the buffer object in question cannot be mapped. This 1366 may occur for a variety of system-specific reasons, such as the 1367 absence of sufficient remaining virtual memory. 1368 1369 INVALID_ENUM is generated if the <usage> parameter of BufferDataARB is 1370 not STREAM_DRAW_ARB, STREAM_READ_ARB, STREAM_COPY_ARB, STATIC_DRAW_ARB, 1371 STATIC_READ_ARB, STATIC_COPY_ARB, DYNAMIC_DRAW_ARB, DYNAMIC_READ_ARB, 1372 or DYNAMIC_COPY_ARB. 1373 1374 INVALID_VALUE is generated if the <offset> parameter to BufferSubDataARB 1375 or GetBufferSubDataARB is negative. 1376 1377 INVALID_VALUE is generated if the <offset> and <size> parameters of 1378 BufferSubDataARB or GetBufferSubDataARB define a region of memory that 1379 extends beyond that allocated by BufferDataARB. 1380 1381 INVALID_OPERATION is generated if MapBufferARB is executed for a 1382 buffer that is already mapped. 1383 1384 INVALID_OPERATION is generated if UnmapBufferARB is executed for a 1385 buffer that is not currently mapped. 1386 1387 INVALID_ENUM is generated if the <access> parameter of MapBufferARB 1388 is not READ_ONLY_ARB, WRITE_ONLY_ARB, or READ_WRITE_ARB. 1389 1390 INVALID_ENUM is generated if the <pname> parameter of 1391 GetBufferParameterivARB is not BUFFER_SIZE_ARB, BUFFER_USAGE_ARB, 1392 BUFFER_ACCESS_ARB, or BUFFER_MAPPED_ARB. 1393 1394 INVALID_ENUM is generated if the <pname> parameter of 1395 GetBufferPointervARB is not BUFFER_MAP_POINTER_ARB. 1396 1397 INVALID_OPERATION may be generated if any of the commands 1398 defined in this extension is executed between the execution of Begin 1399 and the corresponding execution of End. 1400 1401 INVALID_OPERATION is generated if a buffer object that is currently 1402 mapped is used as a source of GL render data, or as a destination of 1403 GL query data. 1404 1405 INVALID_OPERATION is generated if BufferSubDataARB is used to modify 1406 the data store contents of a mapped buffer, or if GetBufferSubDataARB 1407 is used to query to data store contents of a mapped buffer. 1408 1409 1410New State 1411 1412(table 6.7, Vertex Array Data, p. 222) 1413 1414 Get Value Type Get Command Initial Value Sec Attribute 1415 --------- ---- ----------- ------------- --- --------- 1416 ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1417 VERTEX_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1418 NORMAL_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1419 COLOR_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1420 INDEX_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1421 TEXTURE_COORD_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1422 EDGE_FLAG_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1423 SECONDARY_COLOR_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1424 FOG_COORDINATE_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1425 WEIGHT_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A vertex-array 1426 ELEMENT_ARRAY_BUFFER_BINDING_ARB Z+ GetIntegerv 0 2.8A.2 vertex-array 1427 1428 VERTEX_ATTRIB_ARRAY_BUFFER_BINDING_ARB 16+ x Z+ GetVertexAttribivARB 0 2.8A vertex-array 1429 1430 XXX need to add buffer state for variant arrays 1431 1432(new table for buffer objects) 1433 1434 Get Value Type Get Command Initial Value Sec Attribute 1435 --------- ---- ----------- ------------- --- --------- 1436 (buffer data) BMU GetBufferSubDataARB 2.8A none 1437 BUFFER_SIZE_ARB Z+ GetBufferParameterivARB 0 2.8A none 1438 BUFFER_USAGE_ARB Z9 GetBufferParameterivARB STATIC_DRAW_ARB 2.8A none 1439 BUFFER_ACCESS_ARB Z3 GetBufferParameterivARB READ_WRITE_ARB 2.8A none 1440 BUFFER_MAPPED_ARB B GetBufferParameterivARB FALSE 2.8A none 1441 BUFFER_MAP_POINTER_ARB Y GetBufferPointervARB NULL 2.8A none 1442 1443 1444New Implementation Dependent State 1445 1446 (none) 1447 1448Additions to the GLX Specification 1449 1450 Add new section "2.X Buffer Objects" between sections "2.5 Texture Objects" 1451 and "2.6 Aligning Multiple Drawables". 1452 1453 "Unformatted data may be stored in the OpenGL server using named buffer 1454 objects. The storage associated with a buffer object may be used as the 1455 input or output of various commands by binding the buffer to a target 1456 associated with the command. For example, if a buffer object is bound to 1457 the GL_ARRAY_BUFFER_ARB target before calling glVertexPointer vertex 1458 data will be sourced from the buffer object's storage. 1459 1460 "Buffer objects may be shared by rendering contexts, as long as the server 1461 portion of the contexts share the same address space. (Like display lists 1462 and texture objects, buffer objects are part of the server context state.) 1463 OpenGL makes no attempt to synchronize access to buffer objects. If a 1464 buffer object is bound to more than one context, then it is up to the 1465 programmer to ensure that the contents of the object are not being changed 1466 via one context while another context is using the buffer object for 1467 rendering. The results of changing a buffer object while another context 1468 is using it are undefined. 1469 1470 "A buffer object is considered to be bound to a context if it is either 1471 currently bound to a particular target (e.g., most recently selected for a 1472 target via glBindBufferARB) or if some portion of the buffer will be 1473 accessed by a GL operation. For example, a buffer object is considered 1474 bound to a context if the most recent call of glVertexPointer was made 1475 while the buffer object was bound to the GL_ARRAY_BUFFER_ARB target. 1476 1477 "As a result, any client-state that attaches the contents of a buffer object 1478 to the GL state must be duplicated on the server. At a minimum the 1479 following client-state must be replicated on the server: 1480 1481 - All vertex array size, type, stride and pointer information. 1482 - All vertex array enables. 1483 1484 "All modifications to shared context state as a result of executing 1485 glBindBufferARB are atomic. Also, a buffer object will not be deleted 1486 until it is no longer bound to any rendering context." 1487 1488 If GLX_ARB_create_context is present, add the following between 1489 paragraphs 8 and 9 of section 3.3.7 "Rendering Contexts": 1490 1491 "The attribute name GLX_CONTEXT_ALLOW_BUFFER_BYTE_ORDER_MISMATCH_ARB 1492 specifies whether the application wishes to use buffer objects even 1493 if the byte ordering of the client and server do not match. If this 1494 attribute is True the client is responsible for byte swapping any data 1495 it stores in or reads from buffer objects. If this attribute is False 1496 and the client and server have different byte orderings, the server 1497 will not expose any extensions that require buffer object support and 1498 the maximum values allowed for GLX_CONTEXT_MAJOR_VERSION_ARB and 1499 GLX_CONTEXT_MINOR_VERSION_ARB are 1 and 4 respectively. The default 1500 value for GLX_CONTEXT_ALLOW_BUFFER_BYTE_ORDER_MISMATCH_ARB is False." 1501 1502 Add to the following paragraph to the end of section 4.3: 1503 1504 "Because the GL views buffer objects as unformatted data, the above byte 1505 swapping rules do not apply to them. Data to be stored in buffer objects 1506 must be byte swapped by the application to match the server's byte ordering 1507 before the data is presented to the GL." 1508 1509GLX Protocol 1510 1511 The following rendering commands are sent to the server as part of a 1512 glXRender request: 1513 1514 BindBufferARB 1515 2 12 rendering command length 1516 2 290 rendering command opcode 1517 4 ENUM target 1518 4 CARD32 buffer 1519 1520 VertexAttribPointer 1521 2 36 rendering command length 1522 2 291 rendering command opcode 1523 8 CARD64 offset 1524 4 ENUM array 1525 4 CARD32 index 1526 4 ENUM type 1527 4 CARD32 size 1528 4 CARD32 stride 1529 1 BOOL is_integer 1530 1 BOOL normalized 1531 2 unused 1532 1533 EnableVertexAttribArray 1534 2 12 rendering command length 1535 2 292 rendering command opcode 1536 4 ENUM array 1537 4 CARD32 index 1538 1539 DisableVertexAttribArray 1540 2 12 rendering command length 1541 2 293 rendering command opcode 1542 4 ENUM array 1543 4 CARD32 index 1544 1545 ArrayElement 1546 2 8 rendering command length 1547 2 294 rendering command opcode 1548 4 CARD32 index 1549 1550 DrawElements 1551 2 24 rendering command length 1552 2 295 rendering command opcode 1553 8 CARD64 indices_offset 1554 4 ENUM mode (GL_POINTS, etc.) 1555 4 CARD32 count 1556 4 CARD32 type 1557 1558 PushClientAttrib 1559 2 8 rendering command length 1560 2 296 rendering command opcode 1561 4 CARD32 mask 1562 1563 PopClientAttrib 1564 2 4 rendering command length 1565 2 297 rendering command opcode 1566 1567 The following rendering commands are sent to the server as part of a 1568 glXRender request, or as a glXRenderLarge request. 1569 1570 BufferDataARB 1571 2 24+n+p rendering command length 1572 2 298 rendering command opcode 1573 8 INT64 size 1574 4 ENUM target 1575 4 ENUM usage 1576 1 BOOL null_data 1577 3 unused 1578 n LISTofBYTE data 1579 p unused, p=pad(n) 1580 1581 If the command is encoded in a glXRenderLarge request, the command 1582 opcode and command length fields are expanded to 4 bytes each. 1583 1584 4 28+n+p rendering command length 1585 4 298 rendering command opcode 1586 1587 BufferSubDataARB 1588 2 24+n+p rendering command length 1589 2 299 rendering command opcode 1590 8 CARD64 offset 1591 8 CARD64 size 1592 4 ENUM target 1593 n LISTofBYTE data, where n = size 1594 p unused, p=pad(n) 1595 1596 If the command is encoded in a glXRenderLarge request, the command 1597 opcode and command length fields are expanded to 4 bytes each. 1598 1599 4 28+n+p rendering command length 1600 4 299 rendering command opcode 1601 1602 DrawArraysNew 1603 2 20+(20*m)+n+p rendering command length 1604 2 300 rendering command opcode 1605 4 ENUM mode (GL_POINTS, etc.) 1606 4 CARD32 first 1607 4 CARD32 count 1608 4 CARD32 m 1609 20*m LISTofARRAY_INFO client_array_info 1610 n LISTofBYTE client_arrays 1611 p unused, p=pad(n) 1612 1613 If the command is encoded in a glXRenderLarge request, the command 1614 opcode and command length fields are expanded to 4 bytes each. 1615 1616 4 24+(20*m)+n+p rendering command length 1617 4 300 rendering command opcode 1618 1619 Where <m> is the number of enabled vertex arrays that do not have 1620 buffer objects bound to them, <n> is <count> * <s>, and <s> is the 1621 sum of all client array element sizes, as defined below. 1622 1623 ARRAY_INFO 1624 4 ENUM data type 1625 0x1400 i=1 GL_BYTE 1626 0x1401 i=1 GL_UNSIGNED_BYTE 1627 0x1402 i=2 GL_SHORT 1628 0x1403 i=2 GL_UNSIGNED_SHORT 1629 0x1404 i=4 GL_INT 1630 0x1405 i=4 GL_UNSIGNED_INT 1631 0x1406 i=4 GL_FLOAT 1632 0x140A i=8 GL_DOUBLE 1633 0x140B i=2 GL_HALF_FLOAT 1634 4 CARD32 j (number of values in array element) 1635 4 ENUM array type 1636 0x8074 j=2/3/4 VERTEX_ARRAY 1637 0x8075 j=3 NORMAL_ARRAY 1638 0x8076 j=3/4 COLOR_ARRAY 1639 0x8077 j=1 INDEX_ARRAY 1640 0x8078 j=1/2/3/4 TEXTURE_COORD_ARRAY 1641 0x8079 j=1 EDGE_FLAG_ARRAY 1642 0x8457 j=1 FOG_COORD_ARRAY 1643 0x845E j=3 SECONDARY_COLOR_ARRAY 1644 0x0000 j=1/2/3/4 VERTEX_ATTRIB_ARRAY 1645 0x86AD j>=1 WEIGHT_ARRAY_ARB 1646 0x8844 j>=1 MATRIX_INDEX_ARRAY_ARB 1647 0x850C j=1 VERTEX_WEIGHT_ARRAY_EXT 1648 0x8768 j=1 ELEMENT_ARRAY_ATI 1649 4 CARD32 index 1650 1 BOOL normalized 1651 1 BOOL is_integer 1652 2 unused 1653 1654 For each client array, the client array element size is <i>*<j>. 1655 The <index> field is the generic attribute array index when 1656 <array type> is VERTEX_ATTRIB_ARRAY and the client active texture 1657 unit's offset from GL_TEXTURE0 when <array_type> is 1658 <TEXTURE_COORD_ARRAY>. For all other values of <array type>, 1659 <index> must be 0. 1660 1661 The DrawArraysNew protocol differs from the DrawArrays protocol 1662 defined in EXT_vertex_array in the following ways: 1663 1664 1) The ARRAY_INFO structure has been expanded to include 1665 <index>, <normalized>, and <is_integer>. 1666 1667 2) ARRAY_INFO and associated array data are only sent for arrays 1668 that do not have buffer objects bound to them. 1669 1670 3) The data for each array is sent contiguously rather than 1671 interleaved with the other arrays. 1672 1673 4) The array data is tightly packed. Rather than containing 1674 padding after each array, a single pad field is added on the 1675 end. 1676 1677 DrawRangeElements 1678 2 36+(20*m)+n+p rendering command length 1679 2 301 rendering command opcode 1680 8 CARD64 indices_offset 1681 4 ENUM mode (GL_POINTS, etc.) 1682 4 CARD32 start 1683 4 CARD32 end 1684 4 CARD32 count 1685 4 CARD32 type 1686 4 CARD32 m 1687 20*m LISTofARRAY_INFO client_array_info 1688 n LISTofBYTE client_arrays 1689 p unused, p=pad(n) 1690 1691 If the command is encoded in a glXRenderLarge request, the command 1692 opcode and command length fields are expanded to 4 bytes each. 1693 1694 4 40+(20*m)+n+p rendering command length 1695 4 301 rendering command opcode 1696 1697 Where <n> is defined as it is for DrawArraysNew. 1698 1699 The remaining commands are non-rendering commands. These commands are 1700 sent separately (i.e., not as part of a glXRender or glXRenderLarge 1701 request), using glx single requests: 1702 1703 DeleteBuffersARB 1704 1 CARD8 opcode (X assigned) 1705 1 186 GLX opcode 1706 2 3+n request length 1707 4 GLX_CONTEXT_TAG context tag 1708 4 CARD32 n 1709 n*4 LISTofCARD32 ids 1710 1711 GenBuffersARB 1712 1 CARD8 opcode (X assigned) 1713 1 187 GLX opcode 1714 2 3 request length 1715 4 GLX_CONTEXT_TAG context tag 1716 4 CARD32 n 1717 => 1718 1 1 reply 1719 1 unused 1720 2 CARD16 sequence number 1721 4 n reply length 1722 24 unused 1723 n*4 LISTofCARD32 buffers 1724 1725 IsBufferARB 1726 1 CARD8 opcode (X assigned) 1727 1 188 GLX opcode 1728 2 3 request length 1729 4 GLX_CONTEXT_TAG context tag 1730 4 CARD32 id 1731 => 1732 1 1 reply 1733 1 unused 1734 2 CARD16 sequence number 1735 4 0 reply length 1736 4 BOOL32 return value 1737 20 unused 1738 1739 GetBufferSubDataARB 1740 1 CARD8 opcode (X assigned) 1741 1 189 GLX opcode 1742 2 7 request length 1743 4 GLX_CONTEXT_TAG context tag 1744 8 CARD64 offset 1745 8 CARD64 size 1746 4 ENUM target 1747 => 1748 1 1 reply 1749 1 1 unused 1750 2 CARD16 sequence number 1751 4 m reply length, m = (n + p) / 4 1752 4 unused 1753 4 CARD32 n 1754 16 unused 1755 n LISTofBYTE buffer subdata 1756 p unused, p=pad(n) 1757 1758 GetBufferParameterivARB 1759 1 CARD8 opcode (X assigned) 1760 1 190 GLX opcode 1761 2 4 request length 1762 4 GLX_CONTEXT_TAG context tag 1763 4 ENUM target 1764 4 ENUM pname 1765 => 1766 1 1 reply 1767 1 1 unused 1768 2 CARD16 sequence number 1769 4 m reply length, m = (n == 1 ? 0 : n) 1770 4 unused 1771 4 CARD32 n (number of parameter components) 1772 1773 if (n == 1) this follows: 1774 1775 4 CARD32 params 1776 12 unused 1777 1778 otherwise this follows: 1779 1780 16 unused 1781 4*n LISTofCARD32 params 1782 1783 Note that n may be 0, indicating that a GL error occurred. 1784 1785 GetElementRange 1786 1 CARD8 opcode (X assigned) 1787 1 191 GLX opcode 1788 2 6 request length 1789 4 GLX_CONTEXT_TAG context tag 1790 8 CARD64 offset 1791 4 ENUM type 1792 4 INT32 count 1793 => 1794 1 1 reply 1795 1 unused 1796 2 CARD16 sequence number 1797 4 0 reply length 1798 8 unused 1799 4 CARD32 lowest element 1800 4 CARD32 highest element 1801 8 unused 1802 1803 GetBufferPointerv 1804 1 CARD8 opcode (X assigned) 1805 1 192 GLX opcode 1806 2 4 request length 1807 4 GLX_CONTEXT_TAG context tag 1808 4 ENUM target 1809 4 ENUM pname 1810 => 1811 1 1 reply 1812 1 unused 1813 2 CARD16 sequence number 1814 4 m reply length, m = (n==1 ? 0 : n*2) 1815 4 unused 1816 4 CARD32 n 1817 1818 if (n=1) this follows: 1819 1820 8 CARD64 params 1821 8 unused 1822 1823 otherwise this follows: 1824 1825 16 unused 1826 n*8 LISTofCARD64 params 1827 1828 Note that n may be 0, indicating that a GL error occurred. 1829 1830 MapBuffer 1831 1 CARD8 opcode (X assigned) 1832 1 193 GLX opcode 1833 2 4 request length 1834 4 GLX_CONTEXT_TAG context tag 1835 4 ENUM target 1836 4 ENUM access 1837 => 1838 1 1 reply 1839 1 unused 1840 2 CARD16 sequence number 1841 4 0 reply length 1842 4 unused 1843 4 CARD32 0 on error, otherwise 1. 1844 8 CARD64 mapping address 1845 8 unused 1846 1847 UnmapBuffer 1848 1 CARD8 opcode (X assigned) 1849 1 194 GLX opcode 1850 2 3 request length 1851 4 GLX_CONTEXT_TAG context tag 1852 4 ENUM target 1853 => 1854 1 1 reply 1855 1 unused 1856 2 CARD16 sequence number 1857 4 0 reply length 1858 4 CARD32 return value 1859 20 unused 1860 1861Usage Examples 1862 1863 These examples illustrate various usages. In all cases a rendering 1864 loop is included, and array parameters are initialized inside the 1865 loop as would be required if multiple array rendering operations 1866 were performed in the loops. (Though only one operation is shown.) 1867 1868 Convenient macro definition for specifying buffer offsets: 1869 1870 #define BUFFER_OFFSET(i) ((char *)NULL + (i)) 1871 1872 Traditional vertex arrays: 1873 1874 // Create system memory buffer 1875 data = malloc(320); 1876 1877 // Fill system memory buffer 1878 ... 1879 1880 // Frame rendering loop 1881 while (...) { 1882 1883 // Define arrays 1884 VertexPointer(4, FLOAT, 0, data); 1885 ColorPointer(4, UNSIGNED_BYTE, 0, data+256); 1886 1887 // Enable arrays 1888 EnableClientState(VERTEX_ARRAY); 1889 EnableClientState(COLOR_ARRAY); 1890 1891 // Draw arrays 1892 DrawArrays(TRIANGLE_STRIP, 0, 16); 1893 1894 // Disable arrays 1895 DisableClientState(VERTEX_ARRAY); 1896 DisableClientState(COLOR_ARRAY); 1897 1898 // Other rendering commands 1899 ... 1900 1901 } 1902 1903 // Free system memory buffer 1904 free(data); 1905 1906 1907 Vertex arrays using a buffer object: 1908 1909 // Create system memory buffer 1910 data = malloc(320); 1911 1912 // Fill system memory buffer 1913 ... 1914 1915 // Create buffer object 1916 BindBufferARB(ARRAY_BUFFER_ARB, 1); 1917 1918 // Initialize data store of buffer object 1919 BufferDataARB(ARRAY_BUFFER_ARB, 320, data, STATIC_DRAW_ARB); 1920 1921 // Free system memory buffer 1922 free(data); 1923 1924 // Frame rendering loop 1925 while (...) { 1926 1927 // Define arrays 1928 BindBufferARB(ARRAY_BUFFER_ARB, 1); 1929 VertexPointer(4, FLOAT, 0, BUFFER_OFFSET(0)); 1930 ColorPointer(4, UNSIGNED_BYTE, 0, BUFFER_OFFSET(256)); 1931 1932 // Enable arrays 1933 EnableClientState(VERTEX_ARRAY); 1934 EnableClientState(COLOR_ARRAY); 1935 1936 // Draw arrays 1937 DrawArrays(TRIANGLE_STRIP, 0, 16); 1938 1939 // Disable arrays 1940 DisableClientState(VERTEX_ARRAY); 1941 DisableClientState(COLOR_ARRAY); 1942 1943 // Other rendering commands 1944 ... 1945 1946 } 1947 1948 // Delete buffer object 1949 int buffer[1] = {1}; 1950 DeleteBuffersARB(1, buffer); 1951 1952 1953 Code that works with and without buffer objects: 1954 1955 // Create system memory buffer 1956 data = malloc(320); 1957 1958 // Fill system memory buffer 1959 ... 1960 1961 // Initialize buffer object, and null the data pointer 1962#ifdef USE_BUFFER_OBJECTS 1963 BindBufferARB(ARRAY_BUFFER_ARB, 1); 1964 BufferDataARB(ARRAY_BUFFER_ARB, 320, data, STATIC_DRAW_ARB); 1965 free(data); 1966 data = NULL; 1967#endif 1968 1969 // Frame rendering loop 1970 while (...) { 1971 1972 // Define arrays 1973#ifdef USE_BUFFER_OBJECTS 1974 BindBufferARB(ARRAY_BUFFER_ARB, 1); 1975#endif 1976 VertexPointer(4, FLOAT, 0, data); 1977 ColorPointer(4, UNSIGNED_BYTE, 0, data+256); 1978 1979 // Enable arrays 1980 EnableClientState(VERTEX_ARRAY); 1981 EnableClientState(COLOR_ARRAY); 1982 1983 // Draw arrays 1984 DrawArrays(TRIANGLE_STRIP, 0, 16); 1985 1986 // Disable arrays 1987 DisableClientState(VERTEX_ARRAY); 1988 DisableClientState(COLOR_ARRAY); 1989 1990 // Other rendering commands 1991 ... 1992 1993 } 1994 1995 // Delete buffer object 1996#ifdef USE_BUFFER_OBJECTS 1997 int buffer[1] = {1}; 1998 DeleteBuffersARB(1, buffer); 1999#else 2000 // Free system memory buffer 2001 free(data); 2002#endif 2003 2004 2005 Vertex arrays using a mapped buffer object: 2006 2007 // Frame rendering loop 2008 while (...) { 2009 2010 // Define arrays (and create buffer object in first pass) 2011 BindBufferARB(ARRAY_BUFFER_ARB, 1); 2012 VertexPointer(4, FLOAT, 0, BUFFER_OFFSET(0)); 2013 ColorPointer(4, UNSIGNED_BYTE, 0, BUFFER_OFFSET(256)); 2014 2015 // Enable arrays 2016 EnableClientState(VERTEX_ARRAY); 2017 EnableClientState(COLOR_ARRAY); 2018 2019 // Initialize data store of buffer object 2020 BufferDataARB(ARRAY_BUFFER_ARB, 320, NULL, STREAM_DRAW_ARB); 2021 2022 // Map the buffer object 2023 float *p = MapBufferARB(ARRAY_BUFFER_ARB, WRITE_ONLY); 2024 2025 // Compute and store data in mapped buffer object 2026 ... 2027 2028 // Unmap buffer object and draw arrays 2029 if (UnmapBufferARB(ARRAY_BUFFER_ARB)) { 2030 DrawArrays(TRIANGLE_STRIP, 0, 16); 2031 } 2032 2033 // Disable arrays 2034 DisableClientState(VERTEX_ARRAY); 2035 DisableClientState(COLOR_ARRAY); 2036 2037 // Other rendering commands 2038 ... 2039 2040 } 2041 2042 // Delete buffer object 2043 int buffer[1] = {1}; 2044 DeleteBuffersARB(1, buffer); 2045 2046 2047 Vertex arrays using a mapped buffer object for array data and an 2048 unmapped buffer object for indices: 2049 2050 // Create system memory buffer for indices 2051 indexdata = malloc(400); 2052 2053 // Fill system memory buffer with 100 indices 2054 ... 2055 2056 // Create index buffer object 2057 BindBufferARB(ELEMENT_ARRAY_BUFFER_ARB, 2); 2058 BufferDataARB(ELEMENT_ARRAY_BUFFER_ARB, 400, indexdata, 2059 STATIC_DRAW_ARB); 2060 2061 // Free system memory buffer 2062 free(indexdata); 2063 2064 // Frame rendering loop 2065 while (...) { 2066 2067 // Define arrays (and create buffer object in first pass) 2068 BindBufferARB(ARRAY_BUFFER_ARB, 1); 2069 VertexPointer(4, FLOAT, 0, BUFFER_OFFSET(0)); 2070 ColorPointer(4, UNSIGNED_BYTE, 0, BUFFER_OFFSET(256)); 2071 BindBufferARB(ELEMENT_ARRAY_BUFFER_ARB, 2); 2072 2073 // Enable arrays 2074 EnableClientState(VERTEX_ARRAY); 2075 EnableClientState(COLOR_ARRAY); 2076 2077 // Initialize data store of buffer object 2078 BufferDataARB(ARRAY_BUFFER_ARB, 320, NULL, STREAM_DRAW_ARB); 2079 2080 // Map the buffer object 2081 float *p = MapBufferARB(ARRAY_BUFFER_ARB, WRITE_ONLY); 2082 2083 // Compute and store data in mapped buffer object 2084 ... 2085 2086 // Unmap buffer object and draw arrays 2087 if (UnmapBufferARB(ARRAY_BUFFER_ARB)) { 2088 DrawElements(TRIANGLE_STRIP, 100, UNSIGNED_INT, 2089 BUFFER_OFFSET(0)); 2090 } 2091 2092 // Disable arrays 2093 DisableClientState(VERTEX_ARRAY); 2094 DisableClientState(COLOR_ARRAY); 2095 2096 // Other rendering commands 2097 ... 2098 2099 } 2100 2101 // Delete buffer objects 2102 int buffers[2] = {1, 2}; 2103 DeleteBuffersARB(1, buffers); 2104 2105 2106 Mapping multiple buffers simultaneously: 2107 2108 // Map buffers 2109 BindBuffer(ARRAY_BUFFER_ARB, 1); 2110 float *a = MapBuffer(ARRAY_BUFFER_ARB, WRITE_ONLY); 2111 BindBuffer(ARRAY_BUFFER_ARB, 2); 2112 float *b = MapBuffer(ARRAY_BUFFER_ARB, WRITE_ONLY); 2113 2114 // Fill buffers 2115 ... 2116 2117 // Unmap buffers 2118 BindBuffer(ARRAY_BUFFER_ARB, 1); 2119 if (!UnmapBufferARB(ARRAY_BUFFER_ARB)) { 2120 // Handle error case 2121 } 2122 BindBuffer(ARRAY_BUFFER_ARB, 2); 2123 if (!UnmapBufferARB(ARRAY_BUFFER_ARB)) { 2124 // Handle error case 2125 } 2126 2127 Revision Date Author Changes 2128 -------- ----------- ------ --------------------------------------- 2129 0.99.7 18-Jan-2012 mgodse Fixed typos. 2130 2131 0.99.6 25-Oct-2010 jrj Fixed 'context tag' location in 2132 GetBufferSubDataARB GLX protocol. 2133 2134 0.99.5 14-Apr-2010 Jon Leech Added ARB suffix to GLX token. 2135 2136 0.99.4 07-Apr-2010 jrj Added the GLX_ARB_vertex_buffer_object 2137 string to identify GLX implementations 2138 that support the new context attribute. 2139 2140 0.99.3 10-Feb-2010 jrj Fixed GetBufferSubData reply layout and 2141 cleaned up the field descriptions. 2142 Added GetBufferPointerv protocol. 2143 Added an issue describing why the 2144 MapBuffer and UnmapBuffer protocol do 2145 not transmit buffer data. 2146 2147 0.99.2 02-Feb-2010 jrj Removed <n> field from DrawArraysNew 2148 and DrawRangeElements. Its value can 2149 be computed from <m> and the data in 2150 <client_array_info>. 2151 Added more language describing 2152 DrawArraysNew fields and differences 2153 from the existing DrawArrays protocol. 2154 2155 0.99.1 15-Jan-2010 jrj Added more issues. 2156 Use 64 bits for offsets and sizes where 2157 appropriate. 2158 Added is_integer to ARRAY_INFO and 2159 VertexAttribPointer 2160 Added PushClientAttrib and 2161 PopClientAttrib protocol. 2162 Added MapBuffer/UnmapBuffer protocol. 2163 Defined VERTEX_ATTRIB_ARRAY = GL_NONE = 2164 0. 2165 Added padding to DrawArraysNew and 2166 DrawRangeElements. 2167 Changed resolution to the byte ordering 2168 issue. 2169 2170 0.99 16-May-2008 idr Added "Additions to the GLX Specification" 2171 Minor updates to protocol encoding 2172 0.98 01-Sep-2006 idr Resolved the byte-ordering issue. 2173 0.97 16-Mar-2005 idr Added 'null_data' field to BufferData. 2174 This works like the 'null_image' in 2175 TexImage3D. 2176 Removed the 'type' field from 2177 DrawRangeElements and DrawElements. 2178 Added the 'count' field to GetElementRange. 2179 0.96 09-Mar-2005 idr Modified the EnableBufferObject and 2180 DisableBufferObject commands. 2181 Changed the parameter ordering and the 2182 client-side data specification for 2183 DrawArraysNew. 2184 Replaced the existing DrawElements-type 2185 commands with DrawRangeElements and 2186 DrawElements. 2187 Added the GetElementRange query. 2188 Added a proposed resolution for the 2189 EnableClientState issue. 2190 0.95 04-Mar-2005 idr Fixed the size of BindBufferToArray. 2191 Added several issues. 2192 0.94 09-Dec-2004 idr Typo corrections. 2193 Fixed the sizes of several LISTofBYTE and 2194 BOOL elements. 2195 Removed the 'provoke' field from the 2196 ArrayElement command. 2197 Added commands to support DrawElements. 2198 0.93 08-Dec-2004 idr Added several issues. 2199 0.92 27-Oct-2004 idr Initial pass at GLX protocol. 2200