1Name 2 3 ARB_pixel_buffer_object 4 5Name Strings 6 7 GL_ARB_pixel_buffer_object 8 9Notice 10 11 Copyright (c) 2004-2013 The Khronos Group Inc. Copyright terms at 12 http://www.khronos.org/registry/speccopyright.html 13 14Specification Update Policy 15 16 Khronos-approved extension specifications are updated in response to 17 issues and bugs prioritized by the Khronos OpenGL Working Group. For 18 extensions which have been promoted to a core Specification, fixes will 19 first appear in the latest version of that core Specification, and will 20 eventually be backported to the extension document. This policy is 21 described in more detail at 22 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 23 24Status 25 26 Complete. Approved by ARB on December 7, 2004. 27 28Contributors 29 30 Ralf Biermann 31 Nick Carter 32 Derek Cornish 33 Matt Craighead 34 Mark Kilgard 35 Dale Kirkland 36 Jon Leech 37 Brian Paul 38 Thomas Roell 39 Ian Romanick 40 Jeremy Sandmel 41 Shazia Rahman 42 43Contact 44 45 Mark J. Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com) 46 Ralf Biermann, NVIDIA Corporation (rbiermann 'at' nvidia.com) 47 Derek Cornish, NVIDIA Corporation (dcornish 'at' nvidia.com) 48 49IP Status 50 51 None. 52 53Version 54 55 Last Modified Date: October 8, 2013 56 Revision: 1.2 57 58Number 59 60 ARB Extension #42 61 62Dependencies 63 64 Written based on the wording of the OpenGL 2.0 specification. 65 66 Assumes support for (at least) OpenGL 1.5 or the 67 ARB_vertex_buffer_object extension. 68 69 NV_pixel_data_range affects the definition of this extension. 70 71 EXT_pixel_buffer_object interacts with this extension. 72 73Overview 74 75 This extension expands on the interface provided by the 76 ARB_vertex_buffer_object extension (and later integrated into OpenGL 77 1.5) in order to permit buffer objects to be used not only with vertex 78 array data, but also with pixel data. The intent is to provide more 79 acceleration opportunities for OpenGL pixel commands. 80 81 While a single buffer object can be bound for both vertex arrays and 82 pixel commands, we use the designations vertex buffer object (VBO) 83 and pixel buffer object (PBO) to indicate their particular usage in 84 a given situation. 85 86 Recall that buffer objects conceptually are nothing more than arrays 87 of bytes, just like any chunk of memory. ARB_vertex_buffer_object 88 allows GL commands to source data from a buffer object by binding the 89 buffer object to a given target and then overloading a certain set of 90 GL commands' pointer arguments to refer to offsets inside the buffer, 91 rather than pointers to user memory. An offset is encoded in a 92 pointer by adding the offset to a null pointer. 93 94 This extension does not add any new functionality to buffer objects 95 themselves. It simply adds two new targets to which buffer objects 96 can be bound: GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER. When a 97 buffer object is bound to the GL_PIXEL_PACK_BUFFER target, commands 98 such as glReadPixels pack (write) their data into a buffer object. 99 When a buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target, 100 commands such as glDrawPixels and glTexImage2D unpack (read) their 101 data from a buffer object. 102 103 There are a several approaches to improve graphics performance 104 with PBOs. Some of the most interesting approaches are: 105 106 - Streaming texture updates: If the application uses 107 glMapBuffer/glUnmapBuffer to write its data for glTexSubImage into 108 a buffer object, at least one of the data copies usually required 109 to download a texture can be eliminated, significantly increasing 110 texture download performance. 111 112 - Streaming draw pixels: When glDrawPixels sources client memory, 113 OpenGL says the client memory can be modified immediately after the 114 glDrawPixels command returns without disturbing the drawn image. 115 This typically necessitates unpacking and copying the image prior 116 to glDrawPixels returning. However, when using glDrawPixels with 117 a pixel pack buffer object, glDrawPixels may return prior to image 118 unpacking because future modification of the buffer data requires 119 explicit commands (glMapBuffer, glBufferData, or glBufferSubData). 120 121 - Asynchronous glReadPixels: If an application needs to read back a 122 number of images and process them with the CPU, the existing GL 123 interface makes it nearly impossible to pipeline this operation. 124 The driver will typically send the hardware a readback command 125 when glReadPixels is called, and then wait for all of the data to 126 be available before returning control to the application. Then, 127 the application can either process the data immediately or call 128 glReadPixels again; in neither case will the readback overlap with 129 the processing. If the application issues several readbacks 130 into several buffer objects, however, and then maps each one to 131 process its data, then the readbacks can proceed in parallel with 132 the data processing. 133 134 - Render to vertex array: The application can use a fragment 135 program to render some image into one of its buffers, then read 136 this image out into a buffer object via glReadPixels. Then, it can 137 use this buffer object as a source of vertex data. 138 139Issues 140 141 1) How does this extension relate to ARB_vertex_buffer_object? 142 143 It builds on the ARB_vertex_buffer_object framework by adding 144 two new targets that buffers can be bound to. 145 146 2) How does this extension relate to NV_pixel_data_range? 147 148 This extension relates to NV_pixel_data_range in the same way 149 that ARB_vertex_buffer_object relates to NV_vertex_array_range. 150 To paraphrase the ARB_vertex_buffer_object spec, here are the 151 main differences: 152 153 - Applications are no longer responsible for memory management 154 and synchronization. 155 156 - Applications may still access high-performance memory directly, 157 but this is optional, and such access is more restricted. 158 159 - Buffer changes (glBindBuffer) are generally expected to be 160 very lightweight, rather than extremely heavyweight 161 (glPixelDataRangeNV). 162 163 - A platform-specific allocator such as wgl/glXAllocateMemoryNV 164 is no longer required. 165 166 3) Can a given buffer be used for both vertex and pixel data? 167 168 RESOLVED: YES. All buffers can be used with all buffer bindings, 169 in whatever combinations the application finds useful. Consider 170 yourself warned, however, by the following issue. 171 172 4) May implementations make use of the target as a hint to select 173 an appropriate memory space for the buffer? 174 175 RESOLVED: YES, as long as such behavior is transparent to the 176 application. Some implementations may choose, for example, that 177 they would rather stream vertex data from AGP memory, element 178 (index) data from video memory, and pixel data from video memory. 179 In fact, one can imagine arbitrarily complicated heuristics for 180 selecting the memory space, based on factors such as the target, 181 the "usage" argument, and the application's observed behavior. 182 183 While it is entirely legal to create a buffer object by binding 184 it to GL_ARRAY_BUFFER and loading it with data, then using it 185 with the GL_PIXEL_UNPACK_BUFFER_ARB or GL_PIXEL_PACK_BUFFER_ARB 186 binding, such behavior is liable to confuse the driver and may 187 hurt performance. If the driver implemented the hypothetical 188 heuristic described earlier, such a buffer might have already 189 been located in AGP memory, and so the driver would have to choose 190 between two bad options: relocate the buffer into video memory, or 191 accept lower performance caused by streaming pixel data from AGP. 192 193 5) Should all pixel path commands be supported, or just a subset 194 of them? 195 196 RESOLVED: ALL. While there is little reason to believe that, 197 say, glConvolutionFilter2D would benefit from this extension, 198 there is no reason _not_ to support it. The complete list of 199 commands affected by this extension is listed in issues 17 and 18. 200 201 6) Should glPixelMap and glGetPixelMap be supported? 202 203 RESOLVED: YES. They're not really pixel path operations, but, 204 again, there is no good reason to omit operations, and they _are_ 205 operations that pass around big chunks of pixel-related data. 206 If we support glPolygonStipple, surely we should support this. 207 208 7) How does the buffer binding state push/pop? 209 210 RESOLVED: As part of the pixel store client state. This is 211 analogous to how the ARB_vertex_buffer_object bindings 212 pushed/popped as part of the vertex array client state. 213 214 8) Should NV_pixel_data_range (PDR) be used concurrently with pixel 215 buffer objects ? 216 217 RESOLVED: NO. While it would be possible to allocate a memory 218 range for PDR, using a pointer into this memory range with one 219 of the commands affected by PBOs will not work if a pixel buffer 220 object other than zero is bound to the buffer binding point 221 affecting the command. 222 223 Pixel buffer objects always have higher precedence than PDR. 224 225 9) Should the INVALID_OPERATION error be generated if a pixel 226 command would access data outside the range of the bound PBO? 227 228 RESOLVED: YES. This requires considering the command parameters 229 (such as width/height/depth/format/type/pointer), the current 230 pixel store (pack/unpack) state, and the command operation itself 231 to determine the maximum addressed byte for the pixel command. 232 233 Brian Paul strongly recommends this behavior. 234 235 This behavior should increase the reliability of using PBO and 236 guard against programmer mistakes. 237 238 This is particularly important for glReadPixels where returning 239 data into a region outside the PBO could cause corruption of 240 application memory. 241 242 Such bounds checking is substantially more expensive for VBO 243 accesses because bounds checking on a per-vertex element basis 244 for each of multiple enabled vertex arrays prior to performing 245 the command compromises the performance justification of VBO. 246 247 10) If a pixel command with a bound PBO accesses data outside the 248 range of the PBO, thereby generating a GL_INVALID_OPERATION error, 249 can the pixel command end up being partially processed? 250 251 RESOLVED: NO. As for all GL errors excepting GL_OUT_OF_MEMORY 252 situations, "the command generating the error is ignored so that 253 it has no effect on GL state or framebuffer contents." 254 255 This means implementations must determine before the pixel command 256 is performed whether the resulting read or write operations on 257 the bound PBO will exceed the size of the PBO. 258 259 This means an implementation is NOT allowed to detect out of 260 bounds accesses in the middle of performing the command. 261 262 11) How expensive is it to predetermine whether a pixel command 263 accessing a PBO would have an out of bounds access? 264 265 See the "Appendix on Pack/Unpack Range" to see the computations 266 involved in computing the access limit. 267 268 Implementations can further specialize and optimize the check 269 to make this out of bounds checking negligible for any sizable 270 pixel payload. 271 272 12) Should feedback and select buffers output results into a 273 buffer object? 274 275 RESOLVED: That might be useful for a future extension but is 276 not appropriate for this extension. New targets (other than 277 PIXEL_PACK_BUFFER_ARB and PIXEL_UNPACK_BUFFER_ARB) make sense. 278 279 13) Should NV_pixel_data_range interactions be documented in 280 this specification? 281 282 RESOLVED: YES. Interactions with NV_pixel_data_range are 283 important to document to facilitate developers migrating to 284 the multi-vendor ARB_pixel_buffer_object extension. Discussion of 285 interactions is limited to the issues and example usage sections. 286 287 Other ARB specifications follow this policy, and Jon Leech agrees 288 with this policy. 289 290 14) Should an INVALID_OPERATION error be generated if the offset 291 within a pixel buffer to a datum comprising of N basic machine 292 units is not a multiple of N? 293 294 RESOLVED: YES. This was stated for VBOs but no error was 295 defined if the rule was violated. Perhaps this needs to be 296 better specified for VBO. 297 298 For PBO, it is reasonable and cheap to enforce the alignment rule. 299 For pixel commands it means making sure the offset is evenly 300 divisible by the component or group size in basic machine units. 301 302 This check is independent of the pixel store state because the 303 pixel store state is specified in terms of pixels (not basic 304 machine units) so pixel store addressing cannot create an 305 unaligned access as long as the base offset is aligned. 306 307 Certain commands (specifically glPolygonStipple, 308 glGetPolygonStipple, glBitmap, glCompressedTexImage1D, 309 glCompressedTexImage2D, glCompressedTexImage3D, 310 glCompressedTexSubImage1D, glCompressedTexSubImage2D, 311 glCompressedTexSubImage3D, and glGetCompressedTexImage) are not 312 affected by this error because the data accessed is addressed 313 at the granularity of basic machine units. 314 315 15) Various commands do not make explicit reference to supporting 316 packing or unpacking from a pixel buffer object but rather specify 317 that parameters are handled in the same manner as glDrawPixels, 318 glReadPixels, or the glCompressedTexImage commands. So do such 319 commands (example: glCompressedTexSubImage2D) use pixel buffers? 320 321 RESOLVED: YES. Commands that have their behavior defined based 322 on commands that read or write from pixel buffers will themselves 323 read or write from pixel buffers. Relying on this reduces the 324 amount of specification language to be updated. 325 326 16) What is the complete list of commands that can unpack (read) 327 pixels from the current pixel unpack buffer object? 328 329 glBitmap 330 glColorSubTable 331 glColorTable 332 glCompressedTexImage1D 333 glCompressedTexImage2D 334 glCompressedTexImage3D 335 glCompressedTexSubImage1D 336 glCompressedTexSubImage2D 337 glCompressedTexSubImage3D 338 glConvolutionFilter1D 339 glConvolutionFilter2D 340 glDrawPixels 341 glPixelMapfv 342 glPixelMapuiv 343 glPixelMapusv 344 glPolygonStipple 345 glSeparableFilter2D 346 glTexImage1D 347 glTexImage2D 348 glTexImage3D 349 glTexSubImage1D 350 glTexSubImage2D 351 glTexSubImage3D 352 353 17) What is the complete list of commands that can pack (write) 354 pixels into the current pixel pack buffer object? 355 356 glGetCompressedTexImage 357 glGetConvolutionFilter 358 glGetHistogram 359 glGetMinmax 360 glGetPixelMapfv 361 glGetPixelMapuiv 362 glGetPixelMapusv 363 glGetPolygonStipple 364 glGetSeparableFilter, 365 glGetTexImage 366 glReadPixels 367 368 18) How does support for pixel buffer objects affect the GLX protocol? 369 370 UNRESOLVED: See the "GLX Protocol" section. 371 372 19) Prior to this extension, passing zero for the data argument of 373 glTexImage1D, glTexImage2D, and glTexImage3D defined a texture 374 image level without supplying an image. How does this behavior 375 change with this extension? 376 377 RESOLVED: The "unspecified image" behavior of the glTexImage 378 calls only applies when bound to a zero pixel unpack buffer 379 object. 380 381 When bound to a non-zero pixel unpack buffer object, the data 382 argument to these calls is treated as an offset rather than 383 a pointer so zero is a reasonable and even likely value that 384 corresponds to the very beginning of the buffer object's data. 385 386 So to create a texture image level with unspecified image data, 387 you MUST bind to the zero pixel unpack buffer object. 388 389 See the ammended language at the end of section 3.8.1. 390 391 20) How does this extension support video frame grabbers? 392 393 RESOLVED: This extension extends buffer objects so they can 394 operate with pixel commands, rather than just vertex array 395 commands. 396 397 We anticipate that a future extension may provide a mechanism 398 for transferring video frames from video frame grabber hardware 399 or vertices from motion capture hardware (or any other source 400 of aquired real-time data) directly into a buffer object to 401 eliminate a copy. Ideally, such transfers would be possible 402 without requiring mapping of the buffer object. But this 403 extension does not provide such functionality. 404 405 We anticipate such functionality to involve binding a buffer 406 object to a new target type, configuring a source (or sink) for 407 data (video frames, motion capture vertex sets, etc.), and then 408 commands to initiate data transfers to the bound buffer object. 409 410 21) Can this ARB extension share the same enumerants with the EXT 411 version of this functionality? 412 413 RESOLVED: YES. The ARB extension is functionally compatible 414 with EXT_pixel_buffer_object except that the ARB version adds 415 additional error checks for alignment and buffer bounds checking. 416 417 The EXT behavior in the case of alignment violations and buffer 418 bounds overflow are technically undefined. The ARB extension 419 simply defines the EXT extension's undefined behavior to be an 420 OpenGL error. 421 422 Using the same enumerants with firmed up error checking (that 423 would otherwise indicate buggy usage) is preferable to two sets 424 of enumerants where the older EXT set simply allows sloppy usage. 425 426 22) The expected usage parameters (GL_STREAM_DRAW, etc.) for 427 glBufferData are not clearly specified. How can they be improved? 428 429 RESOLVED: To improve the clarity, replace the phrase "specified 430 once" with "specified once per repetition of the usage pattern" so 431 that it is clear for the STREAM_* usage modes (and the STATIC_* 432 usage modes too, just much less frequently) that the repeated 433 specification is part of a pattern and it is expected that the 434 buffer can be, and will be for the STREAM_* usage patterns, 435 specified again after being used and this is likely to repeat. 436 437 Additionally, the *_COPY and *_DRAW usage patterns can source 438 the data with "a GL drawing command" but also with image 439 specification commands so change this phrase to "a GL drawing 440 or image specification command." 441 442 23) Is this the "right" way to expose render-to-vertex-array? 443 444 DISCUSSION: You can use this extension to render an image 445 into a framebuffer, copy the pixels into a buffer object with 446 glReadPixels, and then configure vertex arrays to source the pixel 447 data as vertex attributes. This necessarily involves a copy 448 from the framebuffer to the buffer object. Future extensions 449 may provide mechanisms for copy-free render-to-vertex-array 450 capabilities but that is not a design goal of this extension. 451 452New Procedures and Functions 453 454 None. 455 456 457New Tokens 458 459 Accepted by the <target> parameters of BindBuffer, BufferData, 460 BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, 461 GetBufferParameteriv, and GetBufferPointerv: 462 463 PIXEL_PACK_BUFFER_ARB 0x88EB 464 PIXEL_UNPACK_BUFFER_ARB 0x88EC 465 466 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 467 GetFloatv, and GetDoublev: 468 469 PIXEL_PACK_BUFFER_BINDING_ARB 0x88ED 470 PIXEL_UNPACK_BUFFER_BINDING_ARB 0x88EF 471 472 473Additions to Chapter 2 of the GL Specification (OpenGL Operation) 474 475 None 476 477 -- Section 2.9 "Buffer Objects" 478 479 Replace the first two paragraphs with: 480 481 "The vertex data arrays described in section 2.8 are stored in 482 client memory. It is sometimes desirable to store frequently accessed 483 client data, such as vertex array and pixel data, in high-performance 484 server memory. GL buffer objects provide a mechanism for clients to 485 use to allocate, initialize, and access such memory." 486 487 The name space for buffer objects is the unsigned integer, with zero 488 reserved for the GL. A buffer object is created by binding an unused 489 name to a buffer target. A buffer object is bound by calling 490 491 void BindBuffer(enum target, uint buffer); 492 493 /target/ must be one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, 494 PIXEL_UNPACK_BUFFER_ARB, or PIXEL_PACK_BUFFER_ARB. The ARRAY_BUFFER 495 target is discussed in section 2.9.1 The ELEMENT_ARRAY_BUFFER target 496 is discussed in section 2.9.2. The PIXEL_UNPACK_BUFFER_ARB and 497 PIXEL_PACK_BUFFER_ARB targets are discussed later in sections 3.6, 498 4.3.2, and 6.1. If the buffer object named /buffer/ has not been 499 previously bound or has been deleted since the last binding, the 500 GL creates a new state vector, initialized with a zero-sized memory 501 buffer and comprising the state values listed in table 2.6." 502 503 Replace the 5th paragraph with: 504 505 "Initially, each buffer object target is bound to zero. There is 506 no buffer object corresponding to the name zero so client attempts 507 to modify or query buffer object state for a target bound to zero 508 generate an INVALID_OPERATION error." 509 510 Replace the phrase listing the valid targets for BufferData in the 511 9th paragraph with: 512 513 "with target set to one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, 514 PIXEL_UNPACK_BUFFER_ARB, or PIXEL_PACK_BUFFER_ARB," 515 516 In the 10th paragraph describing buffer object usage modes, replace 517 the phrase "specified once" with "specified once per repetition of 518 the usage pattern" for the STREAM_* and STATIC_* usage values. 519 520 Also in the 10th paragraph describing buffer object usage modes, 521 replace the phrases "of a GL drawing command." and "for GL drawing 522 commands." with "for GL drawing and image specification commands." for 523 the *_DRAW and *_COPY usage values. 524 525 Replace the phrase listing the valid targets for BufferSubData in 526 the 15th paragraph with: 527 528 "with target set to one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, 529 PIXEL_UNPACK_BUFFER_ARB, or PIXEL_PACK_BUFFER_ARB." 530 531 Replace the phrase listing the valid targets for MapBuffer in the 532 16th paragraph with: 533 534 "with target set to one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, 535 PIXEL_UNPACK_BUFFER_ARB, or PIXEL_PACK_BUFFER_ARB." 536 537 Replace the phrase listing the valid targets for UnmapBuffer in the 538 21st paragraph with: 539 540 "with target set to one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, 541 PIXEL_UNPACK_BUFFER_ARB, or PIXEL_PACK_BUFFER_ARB." 542 543 -- Section 2.9.2 "Array Indices in Buffer Objects" 544 545 Delete the 3rd paragraph that explains how the ELEMENT_ARRAY_BUFFER 546 target is acceptable for the commands specified in section 2.9. 547 The updated section 2.9 language already says this. 548 549 -- NEW Section 2.9.3 "Buffer Object Required State" 550 551 "The state required to support buffer objects consists of binding 552 names for the array buffer, element buffer, pixel unpack buffer, and 553 pixel pack buffer. Additionally, each vertex array has an associated 554 binding so there is a buffer object binding for each of the vertex 555 array, normal array, color array, index array, multiple texture 556 coordinate arrays, edge flag array, secondary color array, fog 557 coordinate array, and vertex attribute arrays. The initial values for 558 all buffer object bindings is zero. 559 560 The state of each buffer object consists of a buffer size in basic 561 machine units, a usage parameter, an access parameter, a mapped 562 boolean, a pointer to the mapped buffer (NULL if unmapped), and the 563 sized array of basic machine units for the buffer data." 564 565 566Additions to Chapter 3 of the 1.2.1 Specification (Rasterization) 567 568 -- Section 3.6 "Pixel Rectangles" 569 570 Replace the 1st sentence in the 2nd paragraph: 571 572 "A number of parameters control the encoding of pixels in buffer 573 object or client memory (for reading and writing) and how pixels 574 are processed before being placed in or after being read from the 575 framebuffer (for reading, writing, and copying)." 576 577 -- RENAME Section 3.6.1 "Pixel Storage Modes and Pixel Buffer Objects" 578 579 Add to the end of the section: 580 581 "In addition to storing pixel data in client memory, pixel data 582 may also be stored in buffer objects (described in section 2.9). 583 The current pixel unpack and pack buffer objects are designated 584 by the PIXEL_UNPACK_BUFFER_ARB and PIXEL_PACK_BUFFER_ARB targets 585 respectively. 586 587 Initially, zero is bound for the PIXEL_UNPACK_BUFFER_ARB, indicating 588 that image specification commands such as DrawPixels source their 589 pixels from client memory pointer parameters. However, if a non-zero 590 buffer object is bound as the current pixel unpack buffer, then 591 the pointer parameter is treated as an offset into the designated 592 buffer object." 593 594 -- Section 3.6.3 "Pixel Transfer Modes", page 116. 595 596 Replace the last phrase in the 2nd paragraph with: 597 598 "and /values/ refers to an array of size map values." 599 600 [values is no longer necessarily a pointer.] 601 602 Add the following paragraph after the third paragraph: 603 604 "If a pixel unpack buffer is bound (as indicated by a non-zero 605 value of PIXEL_UNPACK_BUFFER_BINDING_ARB), /values/ is an offset 606 into the pixel unpack buffer; otherwise, /values/ is a pointer to a 607 block client memory. All pixel storage and pixel transfer modes are 608 ignored when specifying a pixel map. n machine units are read where 609 n is the /size/ of the pixel map times the size of a float, uint, 610 or ushort datum in basic machine units, depending on the respective 611 PixelMap version. If a pixel unpack buffer object is bound and data+n 612 is greater than the size of the pixel buffer, INVALID_OPERATION 613 results. If a pixel unpack buffer object is bound and /values/ is 614 not evenly divisible into the number of basic machine units needed 615 to store in memory a float, uint, or ushort datum depending on their 616 respective PixelMap version, INVALID_OPERATION results." 617 618 -- Section 3.6.4 "Rasterization of Pixel Rectangles", page 126. 619 620 Change the 1st sentence of the 1st paragraph to read: 621 622 "The process of drawing pixels encoded in buffer objects or client 623 memory is diagrammed in figure 3.7." 624 625 Change the 4th sentence of the 2nd paragraph to read: 626 627 "/data/ refers to the data to be drawn." 628 629 [data is no longer necessarily a pointer.] 630 631 Change the initial phrase in the 1st sentence of the 1st paragraph 632 after "Unpacking" to read: 633 634 "Data are taken from the currently bound pixel unpack buffer or 635 client memory as a sequence of..." 636 637 Insert this paragraph after the 1st paragraph after "Unpacking": 638 639 "If a pixel unpack buffer is bound (as indicated by a non-zero 640 value of PIXEL_UNPACK_BUFFER_BINDING_ARB), /data/ is an offset 641 into the pixel unpack buffer and the pixels are unpacked from the 642 buffer relative to this offset; otherwise, /data/ is a pointer to 643 a block client memory and the pixels are unpacked from the client 644 memory relative to the pointer. If a pixel unpack buffer object 645 is bound and unpacking the pixel data according to the process 646 described below would access memory beyond the size of the pixel 647 unpack buffer's memory size, INVALID_OPERATION results. If a pixel 648 unpack buffer object is bound and /data/ is not evenly divisible 649 into the number of basic machine units needed to store in memory the 650 corresponding GL data type from table 3.5 for the /type/ parameter, 651 INVALID_OPERATION results." 652 653 -- Section 3.8.1 "Texture Image Specification", page 150. 654 655 Replace the last phrase in the 2nd to last sentence in the 1st 656 paragraph with: 657 658 "and a reference to the image data in the currently bound pixel unpack 659 buffer or client memory." 660 661 Replace the 1st sentence in the 13th paragraph with: 662 663 "The image itself (referred to by /data/) is a sequence of groups 664 of values." 665 666 Replace the last paragraph with: 667 668 "If the data argument of TexImage1D, TexImage2D, or TexImage3D 669 is a null pointer (a zero-valued pointer in the C implementation) 670 and the pixel unpack buffer object is zero, a one-, two-, or three- 671 dimensional texture array is created with the specified target, level, 672 internalformat, width, height, and depth border, but with unspecified 673 image contents. In this case no pixel values are access in client 674 memory, and no pixel processing is performed. Errors are generated, 675 however, exactly as though the data pointer were valid. Otherwise if 676 the pixel unpack buffer object is non-zero, the data argument is 677 treatedly normally to refer to the beginning of the pixel unpack 678 buffer object's data." 679 680 -- Section 3.8.3 "Compressed Texture Images", page 163. 681 682 Replace the 3rd sentence of the 2nd paragraph with: 683 684 "/data/ refers to compressed image data stored in the compressed 685 image format corresponding to internalformat. If a pixel 686 unpack buffer is bound (as indicated by a non-zero value of 687 PIXEL_UNPACK_BUFFER_BINDING_ARB), /data/ is an offset into the 688 pixel unpack buffer and the compressed data is read from the buffer 689 relative to this offset; otherwise, /data/ is a pointer to a block 690 client memory and the compressed data is read from the client memory 691 relative to the pointer." 692 693 Replace the 2nd sentence in the 3rd paragraph with: 694 695 "Compressed texture images are treated as an array of /imageSize/ 696 ubytes relative to /data/. If a pixel unpack buffer object is bound 697 and data+imageSize is greater than the size of the pixel buffer, 698 INVALID_OPERATION results." 699 700Additions to Chapter 4 of the 1.2.1 Specification (Per-Fragment 701Operations and the Frame Buffer) 702 703 -- Section 4.3.2 "Reading Pixels", page 219. 704 705 Replace 1st sentence of the 1st paragraph with: 706 707 "The method for reading pixels from the framebuffer and placing them in 708 pixel pack buffer or client memory is diagrammed in figure 4.2." 709 710 Add this paragraph after the 1st paragraph: 711 712 "Initially, zero is bound for the PIXEL_PACK_BUFFER_ARB, indicating 713 that image read and query commands such as ReadPixels return 714 pixels results into client memory pointer parameters. However, if 715 a non-zero buffer object is bound as the current pixel pack buffer, 716 then the pointer parameter is treated as an offset into the designated 717 buffer object." 718 719 Rename "Placement in Client Memory" to "Placement in Pixel Pack 720 Buffer or Client Memory". 721 722 Insert this paragraph after the newly renamed "Placement in Pixel 723 Pack Buffer or Client Memory" heading: 724 725 "If a pixel pack buffer is bound (as indicated by a non-zero value 726 of PIXEL_PACK_BUFFER_BINDING_ARB), /data/ is an offset into the 727 pixel pack buffer and the pixels are packed into the 728 buffer relative to this offset; otherwise, /data/ is a pointer to a 729 block client memory and the pixels are packed into the client memory 730 relative to the pointer. If a pixel pack buffer object is bound and 731 packing the pixel data according to the pixel pack storage state 732 would access memory beyond the size of the pixel pack buffer's 733 memory size, INVALID_OPERATION results. If a pixel pack buffer object 734 is bound and /data/ is not evenly divisible into the number of basic 735 machine units needed to store in memory the corresponding GL data type 736 from table 3.5 for the /type/ parameter, INVALID_OPERATION results." 737 738 739Additions to Chapter 5 of the 1.2.1 Specification (Special Functions) 740 741 None 742 743 744Additions to Chapter 6 of the 1.2.1 Specification (State and State 745Requests) 746 747 -- Section 6.1.3 "Enumerated Queries". 748 749 After the sentence in the last paragraph describing GetPixelMap, add: 750 751 "The GetPixelMapfv, GetPixelMapuiv, and GetPixelMapusv commands 752 write all the values in the named pixel map to /data/. If a 753 pixel pack buffer is bound (as indicated by a non-zero value of 754 PIXEL_PACK_BUFFER_BINDING_ARB), /data/ is an offset into the pixel 755 pack buffer; otherwise, /data/ is a pointer to a block client memory. 756 All pixel storage and pixel transfer modes are ignored when returning a 757 pixel map. n machine units are written where n is the size of the 758 pixel map times the size of FLOAT, UNSIGNED_INT, or UNSIGNED_SHORT 759 respectively in basic machine units. If a pixel pack buffer object 760 is bound and data+n is greater than the size of the pixel buffer, 761 generate INVALID_OPERATION." 762 763 -- Section 6.1.4 "Texture Queries". 764 765 Remove the mention of img in the last phrase in the last sentence 766 of the 1st paragraph so the sentence reads: 767 768 "lod is a level-of-detail number, format is a pixel format from 769 table 3.6, and type is a pixel type from table 3.5." 770 771 Replace the 3rd sentence of the 2nd paragraph with: 772 773 "These groups are then packed and placed in client or pixel buffer 774 object memory. If a pixel pack buffer is bound (as indicated by a 775 non-zero value of PIXEL_PACK_BUFFER_BINDING_ARB), /img/ is an offset 776 into the pixel pack buffer; otherwise, /img/ is a pointer to a block 777 client memory." 778 779 Add to the end of the 4th paragraph: 780 781 "If a pixel pack buffer object is bound and packing the texture 782 image into the buffer's memory would exceed the size of the buffer, 783 generate INVALID_OPERATION." 784 785 Replace the 2nd sentence of the 5th paragraph with: 786 787 "When called, GetCompressedTexImage writes n ubytes of compressed 788 image data to the pixel pack buffer or client memory pointed to by 789 ptr, where n is the texture image's TEXTURE_COMPRESSED_IMAGE_SIZE 790 value. 791 792 Add to the end of the 6th paragraph: 793 794 "If a pixel pack buffer object is bound and ptr+n is greater than 795 the size of the buffer, generate INVALID_OPERATION." 796 797 -- Section 6.1.5 "Stipple Query". 798 799 "The pattern is packed into client or pixel pack buffer memory 800 according to the procedures given in section 4.3.2 for ReadPixels; 801 ..." 802 803 -- Section 6.1.7 "Color Table Query". 804 805 "The one-dimensional color table image is returned to client or 806 pixel pack buffer memory starting at table." 807 808 -- Section 6.1.8 "Convolution Query". 809 810 "The one-dimensional or two-dimensional image is returned to client 811 or pixel pack buffer memory starting at image." 812 813 "The row and column images are returned to client or pixel pack 814 buffer memory starting at row and column respectively." 815 816 -- Section 6.1.9 "Histogram Query". 817 818 "The one-dimensional histogram table image is returned to client or 819 pixel pack buffer memory starting at values." 820 821 -- Section 6.1.10 "Minmax Query". 822 823 "A one-dimensional image of width 2 is returned to client or pixel 824 pack buffer memory starting at values." 825 826 -- Section 6.1.13 "Buffer Object Queries". 827 828 Change the 2nd sentence of the 2nd paragraph to read: 829 830 "target is ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, PIXEL_PACK_BUFFER_ARB, 831 or PIXEL_UNPACK_BUFFER_ARB." 832 833 Change the last phrase in the 1st sentence of the 4th paragraph to: 834 835 "with target set to ARRAY_BUFFER, ELMENT_ARRAY_BUFFER, 836 PIXEL_PACK_BUFFER_ARB, or PIXEL_UNPACK_BUFFER_ARB and pname set 837 to BUFFER_MAP_POINTER." 838 839 840GLX Protocol 841 842 Pixel buffers, like texture objects and display lists, are server-side 843 state. 844 845 Prior to pixel buffer objects, pixel storage state for image packing 846 and unpacking was considered client-side state. However, pixel 847 buffers create the new situation where the server performs packing 848 and unpacking into server-side pixel buffers. 849 850 Fortunately, the GLX protocol, through foresight or oversight, 851 has GLX protocol and non-rendering command opcodes (109 and 110) 852 assigned for glPixelStoref and glPixelStorei respectively. 853 854 It is better to use the existing protocol to send glPixelStorei and 855 glPixelStoref GLX commands. This solves the problem of server-side 856 pixel state the same way for both pack and unpack state. It may also 857 allow implementations to minimize validation overhead for pixel 858 commands because the pixel store modes are stateful rather than 859 being parameters sent with every pixel command. 860 861 When bound to a pixel unpack buffer object, the pixel payload for a 862 pixel command with no reply (for exmaple, glTexImage2D) is not sent. 863 Instead, the pointer itself is sent as a 64-bit offset. 864 Pixel storage modes are also not included in non-reply pixel commands. 865 866 Therefore, the following new protocol for pixel commands that use the 867 currently bound pixel unpack buffer object is specified: 868 869 BitmapPBO 870 ColorSubTablePBO 871 ColorTablePBO 872 CompressedTexImage1DPBO 873 CompressedTexImage2DPBO 874 CompressedTexImage3DPBO 875 CompressedTexSubImage1DPBO 876 CompressedTexSubImage2DPBO 877 CompressedTexSubImage3DPBO 878 ConvolutionFilter1DPBO 879 ConvolutionFilter2DPBO 880 DrawPixelsPBO 881 PixelMapfvPBO 882 PixelMapuivPBO 883 PixelMapusvPBO 884 PolygonStipplePBO 885 SeparableFilter2DPBO 886 TexImage1DPBO 887 TexImage2DPBO 888 TexImage3DPBO** 889 TexSubImage1DPBO 890 TexSubImage2DPBO 891 TexSubImage3DPBO 892 893 When bound to a pixel pack buffer object, the reply for pixel commands 894 that return pixel data (for example, glReadPixels) is not required 895 since the pixel data is actually transferred to the server-side pixel 896 pack buffer object. Indeed, forcing an unnecessary reply would hinder 897 the performance advantages of using pixel buffer objects 898 899 Therefore, protocol for "no reply" version of the following commands 900 is specified: 901 902 GetColorTablePBO 903 GetCompressedTexImagePBO 904 GetConvolutionFilterPBO 905 GetHistogramPBO 906 GetMinmaxPBO 907 GetPixelMapfvPBO 908 GetPixelMapuivPBO 909 GetPixelMapusvPBO 910 GetPolygonStipplePBO 911 GetSeparableFilterPBO 912 GetTexImagePBO 913 ReadPixelsPBO 914 915 If a "no reply" command is sent when the current pixel pack 916 buffer object binding is zero, a GLXBadContextState error should 917 be generated by the server. 918 919 920 The following rendering commands are sent to the server as part of a 921 glXRender request: 922 923 BitmapPBO 924 925 2 36 rendering command length 926 2 311 rendering command opcode 927 8 CARD64 bitmap 928 4 CARD32 width 929 4 CARD32 height 930 4 FLOAT32 xorig 931 4 FLOAT32 yorig 932 4 FLOAT32 xmove 933 4 FLOAT32 ymove 934 935 ColorSubTablePBO 936 937 2 32 rendering command length 938 2 312 rendering command opcode 939 8 CARD64 table 940 4 ENUM target 941 4 CARD32 start 942 4 CARD32 count 943 4 ENUM apiFormat 944 4 ENUM apiType 945 946 ColorTablePBO 947 948 2 32 rendering command length 949 2 313 rendering command opcode 950 8 CARD64 table 951 4 ENUM target 952 4 ENUM internalformat 953 4 CARD32 width 954 4 ENUM apiFormat 955 4 ENUM apiType 956 957 CompressedTexImage1DPBO 958 959 2 36 rendering command length 960 2 314 rendering command opcode 961 8 CARD64 data 962 4 ENUM target 963 4 CARD32 level 964 4 ENUM internalFormat 965 4 CARD32 width 966 4 CARD32 border 967 4 CARD32 imageSize 968 969 CompressedTexImage2DPBO 970 971 2 40 rendering command length 972 2 315 rendering command opcode 973 8 CARD64 data 974 4 ENUM target 975 4 CARD32 level 976 4 ENUM internalFormat 977 4 CARD32 width 978 4 CARD32 height 979 4 CARD32 border 980 4 CARD32 imageSize 981 982 CompressedTexImage3DPBO 983 984 2 44 rendering command length 985 2 316 rendering command opcode 986 8 CARD64 data 987 4 ENUM target 988 4 CARD32 level 989 4 ENUM internalFormat 990 4 CARD32 width 991 4 CARD32 height 992 4 CARD32 depth 993 4 CARD32 border 994 4 CARD32 imageSize 995 996 CompressedTexSubImage1DPBO 997 998 2 36 rendering command length 999 2 317 rendering command opcode 1000 8 CARD64 data 1001 4 ENUM target 1002 4 CARD32 level 1003 4 CARD32 xoffset 1004 4 CARD32 width 1005 4 ENUM apiFormat 1006 4 CARD32 imageSize 1007 1008 CompressedTexSubImage2DPBO 1009 1010 2 44 rendering command length 1011 2 318 rendering command opcode 1012 8 CARD64 data 1013 4 ENUM target 1014 4 CARD32 level 1015 4 CARD32 xoffset 1016 4 CARD32 yoffset 1017 4 CARD32 width 1018 4 CARD32 height 1019 4 ENUM apiFormat 1020 4 CARD32 imageSize 1021 1022 CompressedTexSubImage3DPBO 1023 1024 2 52 rendering command length 1025 2 319 rendering command opcode 1026 8 CARD64 data 1027 4 ENUM target 1028 4 CARD32 level 1029 4 CARD32 xoffset 1030 4 CARD32 yoffset 1031 4 CARD32 zoffset 1032 4 CARD32 width 1033 4 CARD32 height 1034 4 CARD32 depth 1035 4 ENUM apiFormat 1036 4 CARD32 imageSize 1037 1038 ConvolutionFilter1DPBO 1039 1040 2 32 rendering command length 1041 2 320 rendering command opcode 1042 8 CARD64 image 1043 4 ENUM target 1044 4 ENUM internalformat 1045 4 CARD32 width 1046 4 ENUM apiFormat 1047 4 ENUM apiType 1048 1049 ConvolutionFilter2DPBO 1050 1051 2 36 rendering command length 1052 2 321 rendering command opcode 1053 8 CARD64 image 1054 4 ENUM target 1055 4 ENUM internalformat 1056 4 CARD32 width 1057 4 CARD32 height 1058 4 ENUM apiFormat 1059 4 ENUM apiType 1060 1061 DrawPixelsPBO 1062 1063 2 28 rendering command length 1064 2 322 rendering command opcode 1065 8 CARD64 image 1066 4 CARD32 width 1067 4 CARD32 height 1068 4 ENUM apiFormat 1069 4 ENUM apiType 1070 1071 PixelMapfvPBO 1072 1073 2 20 rendering command length 1074 2 323 rendering command opcode 1075 8 CARD64 values 1076 4 ENUM map 1077 4 CARD32 mapsize 1078 1079 PixelMapuivPBO 1080 1081 2 20 rendering command length 1082 2 324 rendering command opcode 1083 8 CARD64 values 1084 4 ENUM map 1085 4 CARD32 mapsize 1086 1087 PixelMapusvPBO 1088 1089 2 20 rendering command length 1090 2 325 rendering command opcode 1091 8 CARD64 values 1092 4 ENUM map 1093 4 CARD32 mapsize 1094 1095 PolygonStipplePBO 1096 1097 2 12 rendering command length 1098 2 326 rendering command opcode 1099 8 CARD64 mask 1100 1101 SeparableFilter2DPBO 1102 1103 2 44 rendering command length 1104 2 327 rendering command opcode 1105 8 CARD64 row 1106 8 CARD64 column 1107 4 ENUM target 1108 4 ENUM internalFormat 1109 4 CARD32 width 1110 4 CARD32 height 1111 4 ENUM apiFormat 1112 4 ENUM apiType 1113 1114 TexImage1DPBO 1115 1116 2 40 rendering command length 1117 2 328 rendering command opcode 1118 8 CARD64 image 1119 4 ENUM target 1120 4 CARD32 level 1121 4 CARD32 components 1122 4 CARD32 width 1123 4 CARD32 border 1124 4 ENUM apiFormat 1125 4 ENUM apiType 1126 1127 TexImage2DPBO 1128 1129 2 44 rendering command length 1130 2 329 rendering command opcode 1131 8 CARD64 image 1132 4 ENUM target 1133 4 CARD32 level 1134 4 CARD32 components 1135 4 CARD32 width 1136 4 CARD32 height 1137 4 CARD32 border 1138 4 ENUM apiFormat 1139 4 ENUM apiType 1140 1141 TexImage3DPBO 1142 1143 2 48 rendering command length 1144 2 330 rendering command opcode 1145 8 CARD64 image 1146 4 ENUM target 1147 4 CARD32 level 1148 4 CARD32 components 1149 4 CARD32 width 1150 4 CARD32 height 1151 4 CARD32 depth 1152 4 CARD32 border 1153 4 ENUM apiFormat 1154 4 ENUM apiType 1155 1156 TexSubImage1DPBO 1157 1158 2 36 rendering command length 1159 2 331 rendering command opcode 1160 8 CARD64 image 1161 4 ENUM target 1162 4 CARD32 level 1163 4 CARD32 xoffset 1164 4 CARD32 width 1165 4 ENUM apiFormat 1166 4 ENUM apiType 1167 1168 TexSubImage2DPBO 1169 1170 2 44 rendering command length 1171 2 332 rendering command opcode 1172 8 CARD64 image 1173 4 ENUM target 1174 4 CARD32 level 1175 4 CARD32 xoffset 1176 4 CARD32 yoffset 1177 4 CARD32 width 1178 4 CARD32 height 1179 4 ENUM apiFormat 1180 4 ENUM apiType 1181 1182 TexSubImage3DPBO 1183 1184 2 52 rendering command length 1185 2 333 rendering command opcode 1186 8 CARD64 image 1187 4 ENUM target 1188 4 CARD32 level 1189 4 CARD32 xoffset 1190 4 CARD32 yoffset 1191 4 CARD32 zoffset 1192 4 CARD32 width 1193 4 CARD32 height 1194 4 CARD32 depth 1195 4 ENUM apiFormat 1196 4 ENUM apiType 1197 1198 GetColorTablePBO 1199 1200 2 24 rendering command length 1201 2 334 rendering command opcode 1202 8 CARD64 table 1203 4 ENUM target 1204 4 ENUM apiFormat 1205 4 ENUM apiType 1206 1207 GetCompressedTexImagePBO 1208 1209 2 20 rendering command length 1210 2 335 rendering command opcode 1211 8 CARD64 img 1212 4 ENUM target 1213 4 CARD32 lod 1214 1215 GetConvolutionFilterPBO 1216 1217 2 24 rendering command length 1218 2 336 rendering command opcode 1219 8 CARD64 image 1220 4 ENUM target 1221 4 ENUM apiFormat 1222 4 ENUM apiType 1223 1224 GetHistogramPBO 1225 1226 2 28 rendering command length 1227 2 337 rendering command opcode 1228 8 CARD64 values 1229 4 ENUM target 1230 4 ENUM apiFormat 1231 4 ENUM apiType 1232 1 BOOL reset 1233 3 unused 1234 1235 GetMinmaxPBO 1236 1237 2 28 rendering command length 1238 2 338 rendering command opcode 1239 8 CARD64 values 1240 4 ENUM target 1241 4 ENUM apiFormat 1242 4 ENUM apiType 1243 1 BOOL reset 1244 3 unused 1245 1246 GetPixelMapfvPBO 1247 1248 2 16 rendering command length 1249 2 339 rendering command opcode 1250 8 CARD64 values 1251 4 ENUM map 1252 1253 GetPixelMapuivPBO 1254 1255 2 16 rendering command length 1256 2 340 rendering command opcode 1257 8 CARD64 values 1258 4 ENUM map 1259 1260 GetPixelMapusvPBO 1261 1262 2 16 rendering command length 1263 2 341 rendering command opcode 1264 8 CARD64 values 1265 4 ENUM map 1266 1267 GetPolygonStipplePBO 1268 1269 2 12 rendering command length 1270 2 342 rendering command opcode 1271 8 CARD64 mask 1272 1273 GetSeparableFilterPBO 1274 1275 2 40 rendering command length 1276 2 343 rendering command opcode 1277 8 CARD64 row 1278 8 CARD64 column 1279 8 CARD64 span 1280 4 ENUM target 1281 4 ENUM apiFormat 1282 4 ENUM apiType 1283 1284 GetTexImagePBO 1285 1286 2 28 rendering command length 1287 2 344 rendering command opcode 1288 8 CARD64 texels 1289 4 ENUM target 1290 4 CARD32 level 1291 4 ENUM apiFormat 1292 4 ENUM apiType 1293 1294 ReadPixelsPBO 1295 1296 2 36 rendering command length 1297 2 345 rendering command opcode 1298 8 CARD64 pixels 1299 4 CARD32 x 1300 4 CARD32 y 1301 4 CARD32 width 1302 4 CARD32 height 1303 4 ENUM apiFormat 1304 4 ENUM apiType 1305 1306 1307Errors 1308 1309 INVALID_ENUM is generated if the <target> parameter of 1310 BindBuffer, BufferData, BufferSubData, MapBuffer, UnmapBuffer, 1311 GetBufferSubData, GetBufferParameteriv, or GetBufferPointerv is not 1312 one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, PIXEL_PACK_BUFFER_ARB, 1313 or PIXEL_UNPACK_BUFFER_ARB. 1314 1315 INVALID_OPERATION is generated if Bitmap, ColorSubTable, ColorTable, 1316 CompressedTexImage1D, CompressedTexImage2D, CompressedTexImage3D, 1317 CompressedTexSubImage1D, CompressedTexSubImage2D, 1318 CompressedTexSubImage3D, ConvolutionFilter1D, ConvolutionFilter2D, 1319 DrawPixels, PixelMapfv, PixelMapuiv, PixelMapusv, PolygonStipple, 1320 SeparableFilter2D, TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, 1321 TexSubImage2D, or TexSubImage3D would unpack (read) data from the 1322 currently bound PIXEL_UNPACK_BUFFER_ARB buffer object such that 1323 the memory reads required for the command would exceed the memory 1324 (data store) size of the buffer object. 1325 1326 INVALID_OPERATION is generated if GetColorTable, 1327 GetCompressedTexImage, GetConvolutionFilter, GetHistogram, GetMinmax, 1328 GetPixelMapfv, GetPixelMapuiv, GetPixelMapusv, GetPolygonStipple, 1329 GetSeparableFilter, GetTexImage, or ReadPixels would pack (write) data 1330 to the currently bound PIXEL_PACK_BUFFER_ARB buffer object such that 1331 the memory writes required for the command would exceed the memory 1332 (data store) size of the buffer object. 1333 1334 INVALID_OPERATION is generated by GetColorTable, GetConvolutionFilter, 1335 GetHistogram, GetMinmax, GetSeparableFilter, GetTexImage and ReadPixels 1336 if the current PIXEL_PACK_BUFFER_BINDING_ARB value is non-zero and the 1337 table/image/values/span/img/data parameter is not evenly divisible 1338 into the number of basic machine units needed to store in memory a 1339 datum indicated by the type parameter. 1340 1341 INVALID_OPERATION is generated by ColorTable, ColorSubTable, 1342 ConvolutionFilter2D, ConvolutionFilter1D, SeparableFilter2D, 1343 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, 1344 TexSubImage2D, TexSubImage3D, and DrawPixels if the current 1345 PIXEL_UNPACK_BUFFER_BINDING_ARB value is non-zero and the data 1346 parameter is not evenly divisible into the number of basic machine 1347 units needed to store in memory a datum indicated by the type 1348 parameter. 1349 1350 INVALID_OPERATION is generated by GetPixelMapfv if the current 1351 PIXEL_PACK_BUFFER_BINDING_ARB value is non-zero and the data parameter 1352 is not evenly divisible into the number of basic machine units needed 1353 to store in memory a float datum. 1354 1355 INVALID_OPERATION is generated by GetPixelMapuiv if the current 1356 PIXEL_PACK_BUFFER_BINDING_ARB value is non-zero and the data parameter 1357 is not evenly divisible into the number of basic machine units needed 1358 to store in memory a uint datum. 1359 1360 INVALID_OPERATION is generated by GetPixelMapusv if the current 1361 PIXEL_PACK_BUFFER_BINDING_ARB value is non-zero and the data parameter 1362 is not evenly divisible into the number of basic machine units needed 1363 to store in memory a ushort datum. 1364 1365 INVALID_OPERATION is generated by PixelMapfv if the current 1366 PIXEL_UNPACK_BUFFER_BINDING_ARB value is non-zero and the data 1367 parameter is not evenly divisible into the number of basic machine 1368 units needed to store in memory a float datum. 1369 1370 INVALID_OPERATION is generated by PixelMapuiv if the current 1371 PIXEL_UNPACK_BUFFER_BINDING_ARB value is non-zero and the data 1372 parameter is not evenly divisible into the number of basic machine 1373 units needed to store in memory a uint datum. 1374 1375 INVALID_OPERATION is generated by PixelMapusv if the current 1376 PIXEL_UNPACK_BUFFER_BINDING_ARB value is non-zero and the data 1377 parameter is not evenly divisible into the number of basic machine 1378 units needed to store in memory a ushort datum. 1379 1380 1381Dependencies on EXT_pixel_buffer_object 1382 1383 When this extension is supported, the EXT_pixel_buffer_object 1384 functionality adopts the tighter alignment and buffer bounds overflow 1385 error generation behavior of ARB_pixel_buffer_object (previously, 1386 EXT_pixel_buffer_object was not explicit about what happened in 1387 these situations). This is because the two extensions share the 1388 same enumerants. 1389 1390Dependencies on NV_pixel_data_range 1391 1392 A non-zero pixel pack buffer binding takes priority over the 1393 READ_PIXEL_DATA_RANGE_NV enable. 1394 1395 A non-zero pixel unpack buffer binding takes priority over the 1396 WRITE_PIXEL_DATA_RANGE_NV enable. 1397 1398 1399New State 1400 1401(table 6.20, Pixels, p. 235) 1402 1403 Initial 1404 Get Value Type Get Command Value Sec Attribute 1405 ------------------------------- ---- ----------- ------- ------ ----------- 1406 PIXEL_PACK_BUFFER_BINDING_ARB Z+ GetIntegerv 0 4.3.5 pixel-store 1407 PIXEL_UNPACK_BUFFER_BINDING_ARB Z+ GetIntegerv 0 6.1.13 pixel-store 1408 1409 1410New Implementation Dependent State 1411 1412 (none) 1413 1414 1415Usage Examples 1416 1417 Convenient macro definition for specifying buffer offsets: 1418 1419 #define BUFFER_OFFSET(i) ((char *)NULL + (i)) 1420 1421 Example 1: Render to vertex array: 1422 1423 const int numberVertices = 100; 1424 1425 // Create a buffer object for a number of vertices consisting of 1426 // 4 float values per vertex 1427 glGenBuffers(1, vertexBuffer); 1428 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, vertexBuffer); 1429 glBufferData(GL_PIXEL_PACK_BUFFER_ARB, numberVertices*4, 1430 NULL, GL_DYNAMIC_DRAW); 1431 1432 // Render vertex data into 100x1 strip of framebuffer using a 1433 // fragment program 1434 glBindProgram(FRAGMENT_PROGRAM_ARB, fragmentProgram); 1435 glDrawBuffer(GL_BACK); 1436 renderVertexData(); 1437 glBindProgramARB(FRAGMENT_PROGRAM_ARB, 0); 1438 1439 // Read the vertex data back from framebuffer 1440 glReadBuffer(GL_BACK); 1441 glReadPixels(0, 0, numberVertices, 1, GL_BGRA, GL_FLOAT, 1442 BUFFER_OFFSET(0)); 1443 1444 // Change the binding point of the buffer object to 1445 // the vertex array binding point 1446 glBindBuffer(GL_ARRAY_BUFFER, vertexBuffer); 1447 1448 glEnableClientState(VERTEX_ARRAY); 1449 glVertexPointer(4, GL_FLOAT, 0, BUFFER_OFFSET(0)); 1450 glDrawArrays(TRIANGLE_STRIP, 0, numberVertices); 1451 1452 1453 Example 2: Streaming textures 1454 1455 Streaming textures using NV_pixel_data_range: 1456 1457 const int texWidth = 256; 1458 const int texHeight = 256; 1459 const int texsize = texWidth * texHeight * 4; 1460 void *pdrMemory, *texData; 1461 1462 pdrMemory = glAllocateMemoryNV(texsize, 0.0, 1.0, 1.0); 1463 1464 glPixelDataRangeNV(GL_WRITE_PIXEL_DATA_RANGE_NV, texsize, 1465 pdrMemory); 1466 1467 glEnableClientState(GL_WRITE_PIXEL_DATA_RANGE_NV); 1468 1469 // Define texture level (without an image) 1470 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, texWidth, texHeight, 0, 1471 GL_BGRA, GL_UNSIGNED_BYTE, NULL); 1472 // Setup texture environment 1473 ... 1474 1475 texData = getNextImage(); 1476 1477 while (texData) { 1478 1479 memcpy(pdrMemory, texData, texsize); 1480 1481 glFlushPixelDataRangeNV(GL_WRITE_PIXEL_DATA_RANGE_NV); 1482 1483 glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, texWidth, texHeight, 1484 GL_BGRA, GL_UNSIGNED_BYTE, pdrMemory); 1485 1486 // Draw textured geometry 1487 glBegin(GL_QUADS); 1488 ... 1489 glEnd(); 1490 1491 texData = getNextImage(); 1492 } 1493 1494 glDisableClientState(GL_WRITE_PIXEL_DATA_RANGE_NV); 1495 1496 glFreeMemoryNV(pdrMemory); 1497 1498 1499 Streaming textures using pixel buffer objects: 1500 1501 const int texWidth = 256; 1502 const int texHeight = 256; 1503 const int texsize = texWidth * texHeight * 4; 1504 void *pboMemory, *texData; 1505 1506 // Define texture level zero (without an image); notice the 1507 // explicit bind to the zero pixel unpack buffer object so that 1508 // pass NULL for the image data leaves the texture image 1509 // unspecified. 1510 glBindBuffer(GL_PIXEL_UNPACK_BUFFER_ARB, 0); 1511 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, texWidth, texHeight, 0, 1512 GL_BGRA, GL_UNSIGNED_BYTE, NULL); 1513 1514 // Create and bind texture image buffer object 1515 glGenBuffers(1, &texBuffer); 1516 glBindBuffer(GL_PIXEL_UNPACK_BUFFER_ARB, texBuffer); 1517 1518 // Setup texture environment 1519 ... 1520 1521 texData = getNextImage(); 1522 1523 while (texData) { 1524 1525 // Reset the contents of the texSize-sized buffer object 1526 glBufferData(GL_PIXEL_UNPACK_BUFFER_ARB, texSize, NULL, 1527 GL_STREAM_DRAW); 1528 1529 // Map the texture image buffer (the contents of which 1530 // are undefined due to the previous glBufferData) 1531 pboMemory = glMapBuffer(GL_PIXEL_UNPACK_BUFFER_ARB, 1532 GL_WRITE_ONLY); 1533 1534 // Modify (sub-)buffer data 1535 memcpy(pboMemory, texData, texsize); 1536 1537 // Unmap the texture image buffer 1538 glUnmapBuffer(GL_PIXEL_UNPACK_BUFFER_ARB); 1539 1540 // Update (sub-)teximage from texture image buffer 1541 glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, texWidth, texHeight, 1542 GL_BGRA, GL_UNSIGNED_BYTE, BUFFER_OFFSET(0)); 1543 1544 // Draw textured geometry 1545 glBegin(GL_QUADS); 1546 ... 1547 glEnd(); 1548 1549 texData = getNextImage(); 1550 } 1551 1552 glBindBuffer(GL_PIXEL_UNPACK_BUFFER_ARB, 0); 1553 1554 1555 Example 3: Asynchronous glReadPixels 1556 1557 Traditional glReadPixels: 1558 1559 const int imagewidth = 640; 1560 const int imageheight = 480; 1561 GLubyte readBuffer[imagewidth*imageheight*4]; 1562 1563 // Render to framebuffer 1564 glDrawBuffer(GL_BACK); 1565 renderScene() 1566 1567 // Read image from framebuffer 1568 glReadBuffer(GL_BACK); 1569 glReadPixels(0, 0, imagewidth, imageheight, GL_BGRA, 1570 GL_UNSIGNED_BYTE, readBuffer); 1571 1572 // Process image when glReadPixels returns after reading the 1573 // whole buffer 1574 processImage(readBuffer); 1575 1576 1577 Asynchronous glReadPixels: 1578 1579 const int imagewidth = 640; 1580 const int imageheight = 480; 1581 const int imageSize = imagewidth*imageheight*4; 1582 1583 glGenBuffers(2, imageBuffers); 1584 1585 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[0]); 1586 glBufferData(GL_PIXEL_PACK_BUFFER_ARB, imageSize / 2, NULL, 1587 GL_STREAM_READ); 1588 1589 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[1]); 1590 glBufferData(GL_PIXEL_PACK_BUFFER_ARB, imageSize / 2, NULL, 1591 GL_STREAM_READ); 1592 1593 // Render to framebuffer 1594 glDrawBuffer(GL_BACK); 1595 renderScene(); 1596 1597 // Bind two different buffer objects and start the glReadPixels 1598 // asynchronously. Each call will return directly after 1599 // starting the DMA transfer. 1600 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[0]); 1601 glReadPixels(0, 0, imagewidth, imageheight/2, GL_BGRA, 1602 GL_UNSIGNED_BYTE, BUFFER_OFFSET(0)); 1603 1604 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[1]); 1605 glReadPixels(0, imageheight/2, imagewidth, imageheight/2, GL_BGRA, 1606 GL_UNSIGNED_BYTE, BUFFER_OFFSET(0)); 1607 1608 // Process partial images. Mapping the buffer waits for 1609 // outstanding DMA transfers into the buffer to finish. 1610 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[0]); 1611 pboMemory1 = glMapBuffer(GL_PIXEL_PACK_BUFFER_ARB, 1612 GL_READ_ONLY); 1613 processImage(pboMemory1); 1614 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[1]); 1615 pboMemory2 = glMapBuffer(GL_PIXEL_PACK_BUFFER_ARB, 1616 GL_READ_ONLY); 1617 processImage(pboMemory2); 1618 1619 // Unmap the image buffers 1620 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[0]); 1621 glUnmapBuffer(GL_PIXEL_PACK_BUFFER_ARB); 1622 glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, imageBuffers[1]); 1623 glUnmapBuffer(GL_PIXEL_PACK_BUFFER_ARB); 1624 1625 1626Appendix on Pack/Unpack Range 1627 1628 The complexity of OpenGL's pixel pack/unpack state makes it difficult 1629 to express succinctly what range of a pixel buffer object will be 1630 accessed by a pixel command. 1631 1632 The following code, following the conventions of the SGI OpenGL 1633 Sample Implementation, returns the limit (one byte more than the 1634 maximum allowed offset into the buffer object) for the memory a 1635 pixel command will read/write. 1636 1637 /* 1638 ** Compute offset limit into user's data considering all pixel 1639 ** store modes. This offset limit is ONE MORE than the largest byte 1640 ** offset for the image. 1641 */ 1642 static GLsizeiptr OffsetLimitImage3D(__GLpixelStoreMode *pixelStoreMode, 1643 GLsizei width, GLsizei height, 1644 GLsizei depth, 1645 GLenum format, GLenum type, 1646 const void *userdata, 1647 GLint skip_images) 1648 { 1649 const GLint line_length = pixelStoreMode->lineLength; 1650 const GLint image_height = pixelStoreMode->imageHeight; 1651 const GLint alignment = pixelStoreMode->alignment; 1652 const GLint skip_pixels = pixelStoreMode->skipPixels; 1653 const GLint skip_lines = pixelStoreMode->skipLines; 1654 1655 GLsizeiptr offsetLimit = (GLsizeiptr) userdata; 1656 1657 GLint rowsize; 1658 GLint padding; 1659 GLint imagesize; 1660 1661 assert(width > 0); 1662 assert(height > 0); 1663 assert(depth > 0); 1664 1665 assert(line_length >= 0); 1666 assert(image_height >= 0); 1667 1668 assert(skip_pixels >= 0); 1669 assert(skip_lines >= 0); 1670 assert(skip_images >= 0); 1671 1672 assert((alignment == 1) || 1673 (alignment == 2) || 1674 (alignment == 4) || 1675 (alignment == 8)); 1676 1677 /* All formats except GL_BITMAP fall out trivially */ 1678 if (type == GL_BITMAP) { 1679 const GLint groups_per_line = (line_length > 0) ? 1680 line_length : width; 1681 const GLint rows_per_image = (image_height > 0) ? 1682 image_height : height; 1683 1684 assert(1 == __glElementsPerGroup(format, type)); 1685 1686 rowsize = (groups_per_line + 7) / 8; 1687 padding = rowsize & (alignment-1); 1688 if (padding) { 1689 rowsize += alignment - padding; 1690 } 1691 imagesize = rows_per_image * rowsize; 1692 1693 offsetLimit += imagesize * (skip_images + depth-1); 1694 offsetLimit += rowsize * (skip_lines + height-1); 1695 offsetLimit += (skip_pixels + width+7)/8; 1696 } else { 1697 const GLint components = __glElementsPerGroup(format, type); 1698 const GLint element_size = __glBytesPerElement(type); 1699 const GLint group_size = element_size * components; 1700 1701 if (0 == (line_length | image_height | skip_pixels | 1702 skip_lines | skip_pixels)) { 1703 // Fast path: when above pixel store modes are all zero. 1704 rowsize = width * group_size; 1705 // Default alignment is 4 so allow arbitrary alignment 1706 // on fast path. 1707 padding = rowsize & (alignment-1); 1708 if (padding) { 1709 rowsize += alignment - padding; 1710 } 1711 imagesize = depth * height * rowsize; 1712 offsetLimit += imagesize; 1713 } else { 1714 // General path: when one or more non-zero pixel store modes. 1715 const GLint groups_per_line = (line_length > 0) ? 1716 line_length : width; 1717 const GLint rows_per_image = (image_height > 0) ? 1718 image_height : height; 1719 1720 rowsize = groups_per_line * group_size; 1721 padding = rowsize & (alignment-1); 1722 if (padding) { 1723 rowsize += alignment - padding; 1724 } 1725 imagesize = rows_per_image * rowsize; 1726 1727 offsetLimit += imagesize * (skip_images + depth-1); 1728 offsetLimit += rowsize * (skip_lines + height-1); 1729 offsetLimit += group_size * (skip_pixels + width); 1730 } 1731 } 1732 return offsetLimit; 1733 } 1734 1735 GLsizeiptr __glOffsetLimitImage3D(__GLpixelStoreMode *pixelStoreMode, 1736 GLsizei width, GLsizei height, 1737 GLsizei depth, 1738 GLenum format, GLenum type, 1739 const void *userdata) 1740 { 1741 return OffsetLimitImage3D(pixelStoreMode, 1742 width, height, depth, format, type, 1743 userdata, 1744 pixelStoreMode->skipImages); 1745 } 1746 1747 GLsizeiptr __glOffsetLimitImage(__GLpixelStoreMode *pixelStoreMode, 1748 GLsizei width, GLsizei height, 1749 GLenum format, GLenum type, 1750 const void *userdata) 1751 { 1752 /* NOTE: Non-3D image max offset computations ignore (treat as zero) 1753 the unpackModes.skipImages state! */ 1754 return OffsetLimitImage3D(pixelStoreMode, 1755 width, height, 1, format, type, 1756 userdata, 1757 0); // Treat skipImages as zero. 1758 } 1759 1760 1761Revision History 1762 1763 revision 0.3: mjk 1764 1765 Numbered issues. 1766 1767 Add issues 14 through 18. 1768 1769 Remove all gl/GL prefix/suffixing in specification sections. Use 1770 gl/GL prefix/suffixing in sections other than the specification 1771 sections. Leaving off prefixes in non-specification sections is 1772 ambiguous, particularly within example source code. 1773 1774 Base specification language updates on OpenGL 2.0 specification. 1775 1776 Add buffer object required state section. 1777 1778 Added GL_INVALID_OPERATION when an offset accessed (read or 1779 written) for a pixel command from/to a pixel buffer object would 1780 exceed the size of the buffer object. 1781 1782 Added GL_INVALID_OPERATION when for misaligned offsets. 1783 1784 Added "Appendix on Pack/Unpack Range". 1785 1786 Add GLX protocol discussion. 1787 1788 revision 0.4: mjk 1789 1790 Fixed grammar issues from Brian Paul. 1791 1792 Improved example code and fixed grammar from Nick Carter. 1793 1794 Explain how a NULL data parameter to glTexImage commands works. 1795 1796 revision 0.5: mjk 1797 1798 Clarify that glBufferData usage modes apply to drawing _and_ 1799 image specification commands. 1800 1801 revision 0.6: mjk 1802 1803 Add "streaming draw pixels" to the list of interesting approaches 1804 for this extension in the Overview. 1805 1806 Add issue discussing the relationship of this extension to data 1807 aquisition hardware. 1808 1809 revision 0.7: mjk 1810 1811 Assign enumerant values to match the EXT_pixel_buffer_object values. 1812 1813 Add issue explaining why the ARB extension shares enums with 1814 EXT_pixel_buffer_object. 1815 1816 Apply Dale's suggestion to improve the clarity of the usage 1817 pattern parameters to glBufferData. 1818 1819 revision 0.8 mjk 1820 1821 Typo fixes from Ian Romanick and Nick Carter. 1822 1823 revision 1.0 mjk 1824 1825 Add issue 23 for Jeremy about render-to-vertex-array. Move 1826 render-to-vertex-array justification in overview to bottom of 1827 the list. 1828 1829 revision 1.1 srahman 1830 1831 Add GLX protocol support. 1832 1833 revision 1.2 Jon Leech 1834 1835 Change GLvoid -> void (Bug 10412). 1836