1Name 2 3 ARB_framebuffer_object 4 5Name Strings 6 7 GL_ARB_framebuffer_object 8 9Contributors 10 11 Kurt Akeley 12 Jason Allen 13 Rob Barris 14 Bob Beretta 15 Pat Brown 16 Matt Craighead 17 Alex Eddy 18 Cass Everitt 19 Mark Galvan 20 Michael Gold 21 Evan Hart 22 Jeff Juliano 23 John Kessenich 24 Mark Kilgard 25 Dale Kirkland 26 Daniel Koch 27 Jon Leech 28 Bill Licea-Kane 29 Barthold Lichtenbelt 30 Kent Lin 31 Rob Mace 32 Teri Morrison 33 Chris Niederauer 34 Brian Paul 35 Paul Puey 36 Ian Romanick 37 John Rosasco 38 R. Jason Sams 39 Jeremy Sandmel 40 Mark Segal 41 Avinash Seetharamaiah 42 Folker Schamel 43 Eskil Steenberg 44 Daniel Vogel 45 Eric Werness 46 Cliff Woolley 47 48Contacts 49 50 Rob Barris (rbarris 'at' gmail.com) 51 Daniel Koch, TransGaming Inc. 52 53Notice 54 55 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 56 http://www.khronos.org/registry/speccopyright.html 57 58Specification Update Policy 59 60 Khronos-approved extension specifications are updated in response to 61 issues and bugs prioritized by the Khronos OpenGL Working Group. For 62 extensions which have been promoted to a core Specification, fixes will 63 first appear in the latest version of that core Specification, and will 64 eventually be backported to the extension document. This policy is 65 described in more detail at 66 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 67 68Status 69 70 Approved by the ARB on August 4, 2008 71 72Version 73 74 Last Modified Date: October 6, 2016 75 Revision: #38 76 77Number 78 79 ARB Extension #45 80 81Dependencies 82 83 OpenGL 1.1 is required. 84 85 WGL_ARB_make_current_read affects the definition of this extension. 86 87 GLX 1.3 / GLX_SGI_make_current_read affects the definition of this 88 extension. 89 90 ATI_draw_buffers affects the definition of this extension. 91 92 ARB_draw_buffers affects the definition of this extension. 93 94 ARB_fragment_program affects the definition of this extension. 95 96 ARB_fragment_shader affects the definition of this extension. 97 98 ARB_texture_rectangle affects the definition of this extension. 99 100 ARB_vertex_shader affects the definition of this extension. 101 102 NV_float_buffer affects the definition of this extension. 103 104 ARB_color_buffer_float affects the definition of this extension. 105 106 NV_texture_shader affects the definition of this extension. 107 108 This extension modifies NV_packed_depth_stencil. 109 110 ARB_depth_texture affects the definition of this extension. 111 112 SGIX_depth_texture affects the definition of this extension. 113 114 ARB_texture_rg affects the definition of this extension. 115 116 EXT_texture_array affects the definition of this extension. 117 118 EXT_texture_integer affects the definition of this extension. 119 120 ARB_framebuffer_sRGB affects the definition of this extension. 121 122 Written based on the wording of the OpenGL 2.1 specification. 123 124Overview 125 126 ARB_framebuffer_object is an extension intended to address the following 127 goals: 128 129 - Reflect FBO-related functionality found in the OpenGL 3.0 specification. 130 131 - Integrate multiple disjoint extensions into a single ARB extension. 132 These extensions are: 133 134 EXT_framebuffer_object 135 EXT_framebuffer_blit 136 EXT_framebuffer_multisample 137 EXT_packed_depth_stencil 138 139 - Where appropriate, relax some of the constraints expressed by previous 140 FBO-related extensions. In particular the requirement of matching 141 attachment dimensions and component sizes has been relaxed, to allow 142 implementations the freedom to support more flexible usages where 143 possible. 144 145 146 ARB_framebuffer_object defines an interface for drawing to rendering 147 destinations other than the buffers provided to the GL by the 148 window-system. 149 150 In this extension, these newly defined rendering destinations are 151 known collectively as "framebuffer-attachable images". This 152 extension provides a mechanism for attaching framebuffer-attachable 153 images to the GL framebuffer as one of the standard GL logical 154 buffers: color, depth, and stencil. (Attaching a 155 framebuffer-attachable image to the accum logical buffer is left for 156 a future extension to define). When a framebuffer-attachable image 157 is attached to the framebuffer, it is used as the source and 158 destination of fragment operations as described in Chapter 4. 159 160 By allowing the use of a framebuffer-attachable image as a rendering 161 destination, this extension enables a form of "offscreen" rendering. 162 Furthermore, "render to texture" is supported by allowing the images 163 of a texture to be used as framebuffer-attachable images. A 164 particular image of a texture object is selected for use as a 165 framebuffer-attachable image by specifying the mipmap level, cube 166 map face (for a cube map texture), and layer (for a 3D texture) 167 that identifies the image. The "render to texture" semantics of 168 this extension are similar to performing traditional rendering to 169 the framebuffer, followed immediately by a call to CopyTexSubImage. 170 However, by using this extension instead, an application can achieve 171 the same effect, but with the advantage that the GL can usually 172 eliminate the data copy that would have been incurred by calling 173 CopyTexSubImage. 174 175 This extension also defines a new GL object type, called a 176 "renderbuffer", which encapsulates a single 2D pixel image. The 177 image of renderbuffer can be used as a framebuffer-attachable image 178 for generalized offscreen rendering and it also provides a means to 179 support rendering to GL logical buffer types which have no 180 corresponding texture format (stencil, accum, etc). A renderbuffer 181 is similar to a texture in that both renderbuffers and textures can 182 be independently allocated and shared among multiple contexts. The 183 framework defined by this extension is general enough that support 184 for attaching images from GL objects other than textures and 185 renderbuffers could be added by layered extensions. 186 187 To facilitate efficient switching between collections of 188 framebuffer-attachable images, this extension introduces another new 189 GL object, called a framebuffer object. A framebuffer object 190 contains the state that defines the traditional GL framebuffer, 191 including its set of images. Prior to this extension, it was the 192 window-system which defined and managed this collection of images, 193 traditionally by grouping them into a "drawable". The window-system 194 API's would also provide a function (i.e., wglMakeCurrent, 195 glXMakeCurrent, aglSetDrawable, etc.) to bind a drawable with a GL 196 context (as is done in the WGL_ARB_pbuffer extension). In this 197 extension however, this functionality is subsumed by the GL and the 198 GL provides the function BindFramebufferARB to bind a framebuffer 199 object to the current context. Later, the context can bind back to 200 the window-system-provided framebuffer in order to display rendered 201 content. 202 203 Previous extensions that enabled rendering to a texture have been 204 much more complicated. One example is the combination of 205 ARB_pbuffer and ARB_render_texture, both of which are window-system 206 extensions. This combination requires calling MakeCurrent, an 207 operation that may be expensive, to switch between the window and 208 the pbuffer drawables. An application must create one pbuffer per 209 renderable texture in order to portably use ARB_render_texture. An 210 application must maintain at least one GL context per texture 211 format, because each context can only operate on a single 212 pixelformat or FBConfig. All of these characteristics make 213 ARB_render_texture both inefficient and cumbersome to use. 214 215 ARB_framebuffer_object, on the other hand, is both simpler to use 216 and more efficient than ARB_render_texture. The 217 ARB_framebuffer_object API is contained wholly within the GL API and 218 has no (non-portable) window-system components. Under 219 ARB_framebuffer_object, it is not necessary to create a second GL 220 context when rendering to a texture image whose format differs from 221 that of the window. Finally, unlike the pbuffers of 222 ARB_render_texture, a single framebuffer object can facilitate 223 rendering to an unlimited number of texture objects. 224 225 This extension differs from EXT_framebuffer_object by splitting the 226 framebuffer object binding point into separate DRAW and READ 227 bindings (incorporating functionality introduced by 228 EXT_framebuffer_blit). This allows copying directly from one 229 framebuffer to another. In addition, a new high performance blit 230 function is added to facilitate these blits and perform some data 231 conversion where allowed. 232 233 This extension also enables usage of multisampling in conjunction with 234 renderbuffers (incorporating functionality from 235 EXT_packed_depth_stencil), as follows: 236 237 The new operation RenderbufferStorageMultisample() allocates 238 storage for a renderbuffer object that can be used as a multisample 239 buffer. A multisample render buffer image differs from a 240 single-sample render buffer image in that a multisample image has a 241 number of SAMPLES that is greater than zero. No method is provided 242 for creating multisample texture images. 243 244 All of the framebuffer-attachable images attached to a framebuffer 245 object must have the same number of SAMPLES or else the framebuffer 246 object is not "framebuffer complete". If a framebuffer object with 247 multisample attachments is "framebuffer complete", then the 248 framebuffer object behaves as if SAMPLE_BUFFERS is one. 249 250 In traditional multisample rendering, where 251 DRAW_FRAMEBUFFER_BINDING is zero and SAMPLE_BUFFERS is one, the 252 GL spec states that "the color sample values are resolved to a 253 single, displayable color each time a pixel is updated." There are, 254 however, several modern hardware implementations that do not 255 actually resolve for each sample update, but instead postpones the 256 resolve operation to a later time and resolve a batch of sample 257 updates at a time. This is OK as long as the implementation behaves 258 "as if" it had resolved a sample-at-a-time. Unfortunately, however, 259 honoring the "as if" rule can sometimes degrade performance. 260 261 In contrast, when DRAW_FRAMEBUFFER_BINDING is an 262 application-created framebuffer object, MULTISAMPLE is enabled, and 263 SAMPLE_BUFFERS is one, there is no implicit per-sample-update 264 resolve. Instead, the application explicitly controls when the 265 resolve operation is performed. The resolve operation is affected 266 by calling BlitFramebuffer where the source is a multisample 267 application-created framebuffer object and the destination is a 268 single-sample framebuffer object (either application-created or 269 window-system provided). 270 271 This design for multisample resolve more closely matches current 272 hardware, but still permits implementations which choose to resolve 273 a single sample at a time. If hardware that implements the 274 multisample resolution "one sample at a time" exposes 275 ARB_framebuffer_object, it could perform the implicit resolve 276 to a driver-managed hidden surface, then read from that surface when 277 the application calls BlitFramebuffer. 278 279 Another motivation for granting the application explicit control 280 over the multisample resolve operation has to do with the 281 flexibility afforded by ARB_framebuffer_object. Previously, a 282 drawable (window or pbuffer) had exclusive access to all of its 283 buffers. There was no mechanism for sharing a buffer across 284 multiple drawables. Under ARB_framebuffer_object, however, a 285 mechanism exists for sharing a framebuffer-attachable image across 286 several framebuffer objects, as well as sharing an image between a 287 framebuffer object and a texture. If we had retained the "implicit" 288 resolve from traditional multisampled rendering, and allowed the 289 creation of "multisample" format renderbuffers, then this type of 290 sharing would have lead to two problematic situations: 291 292 * Two contexts, which shared renderbuffers, might perform 293 competing resolve operations into the same single-sample buffer 294 with ambiguous results. 295 296 * It would have introduced the unfortunate ability to use the 297 single-sample buffer as a texture while MULTISAMPLE is ENABLED. 298 299 Using BlitFramebuffer as an explicit resolve to serialize access to 300 the multisampled contents and eliminate the implicit per-sample 301 resolve operation, we avoid both of these problems. 302 303 This extension also enables usage of packed depth-stencil formats in 304 renderbuffers (incorporating functionality from 305 EXT_packed_depth_stencil), as follows: 306 307 Many OpenGL implementations have chosen to interleave the depth and 308 stencil buffers into one buffer, often with 24 bits of depth 309 precision and 8 bits of stencil data. 32 bits is more than is 310 needed for the depth buffer much of the time; a 24-bit depth buffer, 311 on the other hand, requires that reads and writes of depth data be 312 unaligned with respect to power-of-two boundaries. On the other 313 hand, 8 bits of stencil data is more than sufficient for most 314 applications, so it is only natural to pack the two buffers into a 315 single buffer with both depth and stencil data. OpenGL never 316 provides direct access to the buffers, so the OpenGL implementation 317 can provide an interface to applications where it appears the one 318 merged buffer is composed of two logical buffers. 319 320 One disadvantage of this scheme is that OpenGL lacks any means by 321 which this packed data can be handled efficiently. For example, 322 when an application reads from the 24-bit depth buffer, using the 323 type GL_UNSIGNED_SHORT will lose 8 bits of data, while 324 GL_UNSIGNED_INT has 8 too many. Both require expensive format 325 conversion operations. A 24-bit format would be no more suitable, 326 because it would also suffer from the unaligned memory accesses that 327 made the standalone 24-bit depth buffer an unattractive proposition 328 in the first place. 329 330 Many applications, such as parallel rendering applications, may also 331 wish to draw to or read back from both the depth and stencil buffers 332 at the same time. Currently this requires two separate operations, 333 reducing performance. Since the buffers are interleaved, drawing to 334 or reading from both should be no more expensive than using just 335 one; in some cases, it may even be cheaper. 336 337 This extension provides a new data format, GL_DEPTH_STENCIL, 338 that can be used with the glDrawPixels, glReadPixels, and 339 glCopyPixels commands, as well as a packed data type, 340 GL_UNSIGNED_INT_24_8, that is meant to be used with 341 GL_DEPTH_STENCIL. No other data types are supported with 342 GL_DEPTH_STENCIL. If ARB_depth_texture or SGIX_depth_texture is 343 supported, GL_DEPTH_STENCIL/GL_UNSIGNED_INT_24_8 data can 344 also be used for textures; this provides a more efficient way to 345 supply data for a 24-bit depth texture. 346 347 GL_DEPTH_STENCIL data, when passed through the pixel path, 348 undergoes both depth and stencil operations. The depth data is 349 scaled and biased by the current GL_DEPTH_SCALE and GL_DEPTH_BIAS, 350 while the stencil data is shifted and offset by the current 351 GL_INDEX_SHIFT and GL_INDEX_OFFSET. The stencil data is also put 352 through the stencil-to-stencil pixel map. 353 354 glDrawPixels of GL_DEPTH_STENCIL data operates similarly to that 355 of GL_STENCIL_INDEX data, bypassing the OpenGL fragment pipeline 356 entirely, unlike the treatment of GL_DEPTH_COMPONENT data. The 357 stencil and depth masks are applied, as are the pixel ownership and 358 scissor tests, but all other operations are skipped. 359 360 glReadPixels of GL_DEPTH_STENCIL data reads back a rectangle 361 from both the depth and stencil buffers. 362 363 glCopyPixels of GL_DEPTH_STENCIL data copies a rectangle from 364 both the depth and stencil buffers. Like glDrawPixels, it applies 365 both the stencil and depth masks but skips the remainder of the 366 OpenGL fragment pipeline. 367 368 glTex[Sub]Image[1,2,3]D of GL_DEPTH_STENCIL data loads depth and 369 stencil data into a depth_stencil texture. glGetTexImage of 370 GL_DEPTH_STENCIL data can be used to retrieve depth and stencil 371 data from a depth/stencil texture. 372 373 In addition, a new base internal format, GL_DEPTH_STENCIL, can 374 be used by both texture images and renderbuffer storage. When an 375 image with a DEPTH_STENCIL internal format is attached to both 376 the depth and stencil attachment points of a framebuffer object, 377 then it becomes both the depth and stencil 378 buffers of the framebuffer. This fits nicely with hardware that 379 interleaves both depth and stencil data into a single buffer. When 380 a texture with DEPTH_STENCIL data is bound for texturing, only 381 the depth component is accessible through the texture fetcher. The 382 stencil data can be written with TexImage or CopyTexImage, and can 383 be read with GetTexImage. When a DEPTH_STENCIL image is 384 attached to the stencil attachment of the bound framebuffer object, 385 the stencil data can be accessed through any operation that reads 386 from or writes to the framebuffer's stencil buffer. 387 388 389Glossary of Helpful Terms 390 391 logical buffer: 392 One of the color, depth, or stencil buffers of the 393 framebuffer. 394 395 framebuffer: 396 The collection of logical buffers and associated state 397 defining where the output of GL rendering is directed. 398 399 texture: 400 an object which consists of one or more 2D arrays of pixel 401 images and associated state that can be used as a source of 402 data during the texture-mapping process described in section 403 3.8. 404 405 texture image: 406 one of the 2D arrays of pixels that are part of a texture 407 object as defined in section 3.8. Texture images contain 408 and define the texels of the texture object. 409 410 renderbuffer: 411 A new type of storage object which contains a single 2D 412 array of pixels and associated state that can be used as a 413 destination for pixel data written during the rendering 414 process described in Chapter 4. 415 416 renderbuffer image: 417 The 2D array of pixels that is part of a renderbuffer 418 object. A renderbuffer image contains and defines the 419 pixels of the renderbuffer object. 420 421 framebuffer-attachable image: 422 A 2D pixel image that can be attached to one of the logical 423 buffer attachment points of a framebuffer object. Texture 424 images and renderbuffer images are two examples of 425 framebuffer-attachable images. 426 427 attachment point: 428 The set of state which references a specific 429 framebuffer-attachable image, and allows that 430 framebuffer-attachable image to be used to store the 431 contents of a logical buffer of a framebuffer object. There 432 is an attachment point state vector for each color, depth, 433 and stencil buffer of a framebuffer. 434 435 attach: 436 The act of connecting one object to another object. 437 438 An "attach" operation is similar to a "bind" operation in 439 that both represent a reference to the attached or bound 440 object for the purpose of managing object lifetimes and both 441 enable manipulation of the state of the attached or bound 442 object. 443 444 However, an "attach" is also different from a "bind" in that 445 "binding" an unused object creates a new object, while 446 "attaching" does not. Additionally, "bind" establishes a 447 connection between a context and an object, while "attach" 448 establishes a connection between two objects. 449 450 Finally, if object "A" is attached to object "B" and object 451 "B" is bound to context "C", then in most respects, we treat 452 "A" as if it is <implicitly> bound to "C". 453 454 framebuffer attachment completeness: 455 Similar to texture "mipmap" or "cube" completeness from 456 section 3.8.10, defines a minimum set of criteria for 457 framebuffer attachment points. (for complete definition, 458 see section 4.4.4.1) 459 460 framebuffer completeness: 461 Similar to texture "mipmap cube completeness", defines a 462 composite set of "completeness" requirements and 463 relationships among the attached framebuffer-attachable 464 images. (for complete definition, see section 4.4.4.2) 465 466 467New Procedures and Functions 468 469 boolean IsRenderbuffer(uint renderbuffer); 470 void BindRenderbuffer(enum target, uint renderbuffer); 471 void DeleteRenderbuffers(sizei n, const uint *renderbuffers); 472 void GenRenderbuffers(sizei n, uint *renderbuffers); 473 474 void RenderbufferStorage(enum target, enum internalformat, 475 sizei width, sizei height); 476 477 void RenderbufferStorageMultisample(enum target, sizei samples, 478 enum internalformat, 479 sizei width, sizei height); 480 481 void GetRenderbufferParameteriv(enum target, enum pname, int *params); 482 483 boolean IsFramebuffer(uint framebuffer); 484 void BindFramebuffer(enum target, uint framebuffer); 485 void DeleteFramebuffers(sizei n, const uint *framebuffers); 486 void GenFramebuffers(sizei n, uint *framebuffers); 487 488 enum CheckFramebufferStatus(enum target); 489 490 void FramebufferTexture1D(enum target, enum attachment, 491 enum textarget, uint texture, int level); 492 void FramebufferTexture2D(enum target, enum attachment, 493 enum textarget, uint texture, int level); 494 void FramebufferTexture3D(enum target, enum attachment, 495 enum textarget, uint texture, 496 int level, int layer); 497 void FramebufferTextureLayer(enum target,enum attachment, 498 uint texture,int level,int layer); 499 500 void FramebufferRenderbuffer(enum target, enum attachment, 501 enum renderbuffertarget, uint renderbuffer); 502 503 void GetFramebufferAttachmentParameteriv(enum target, enum attachment, 504 enum pname, int *params); 505 506 void BlitFramebuffer(int srcX0, int srcY0, int srcX1, int srcY1, 507 int dstX0, int dstY0, int dstX1, int dstY1, 508 bitfield mask, enum filter); 509 510 void GenerateMipmap(enum target); 511 512 513New Types 514 515 None. 516 517 518New Tokens 519 520 Accepted by the <target> parameter of BindFramebuffer, 521 CheckFramebufferStatus, FramebufferTexture{1D|2D|3D}, 522 FramebufferRenderbuffer, and 523 GetFramebufferAttachmentParameteriv: 524 525 FRAMEBUFFER 0x8D40 526 READ_FRAMEBUFFER 0x8CA8 527 DRAW_FRAMEBUFFER 0x8CA9 528 529 Accepted by the <target> parameter of BindRenderbuffer, 530 RenderbufferStorage, and GetRenderbufferParameteriv, and 531 returned by GetFramebufferAttachmentParameteriv: 532 533 RENDERBUFFER 0x8D41 534 535 Accepted by the <internalformat> parameter of 536 RenderbufferStorage: 537 538 STENCIL_INDEX1 0x8D46 539 STENCIL_INDEX4 0x8D47 540 STENCIL_INDEX8 0x8D48 541 STENCIL_INDEX16 0x8D49 542 543 Accepted by the <pname> parameter of GetRenderbufferParameteriv: 544 545 RENDERBUFFER_WIDTH 0x8D42 546 RENDERBUFFER_HEIGHT 0x8D43 547 RENDERBUFFER_INTERNAL_FORMAT 0x8D44 548 RENDERBUFFER_RED_SIZE 0x8D50 549 RENDERBUFFER_GREEN_SIZE 0x8D51 550 RENDERBUFFER_BLUE_SIZE 0x8D52 551 RENDERBUFFER_ALPHA_SIZE 0x8D53 552 RENDERBUFFER_DEPTH_SIZE 0x8D54 553 RENDERBUFFER_STENCIL_SIZE 0x8D55 554 RENDERBUFFER_SAMPLES 0x8CAB 555 556 Accepted by the <pname> parameter of 557 GetFramebufferAttachmentParameteriv: 558 559 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE 0x8CD0 560 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME 0x8CD1 561 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL 0x8CD2 562 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE 0x8CD3 563 FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER 0x8CD4 564 FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING 0x8210 565 FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE 0x8211 566 FRAMEBUFFER_ATTACHMENT_RED_SIZE 0x8212 567 FRAMEBUFFER_ATTACHMENT_GREEN_SIZE 0x8213 568 FRAMEBUFFER_ATTACHMENT_BLUE_SIZE 0x8214 569 FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE 0x8215 570 FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE 0x8216 571 FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE 0x8217 572 573 Returned in <params> by GetFramebufferAttachmentParameteriv: 574 575 SRGB 0x8C40 576 UNSIGNED_NORMALIZED 0x8C17 577 FRAMEBUFFER_DEFAULT 0x8218 578 INDEX 0x8222 579 580 Accepted by the <attachment> parameter of 581 FramebufferTexture{1D|2D|3D}, FramebufferRenderbuffer, and 582 GetFramebufferAttachmentParameteriv 583 584 COLOR_ATTACHMENT0 0x8CE0 585 COLOR_ATTACHMENT1 0x8CE1 586 COLOR_ATTACHMENT2 0x8CE2 587 COLOR_ATTACHMENT3 0x8CE3 588 COLOR_ATTACHMENT4 0x8CE4 589 COLOR_ATTACHMENT5 0x8CE5 590 COLOR_ATTACHMENT6 0x8CE6 591 COLOR_ATTACHMENT7 0x8CE7 592 COLOR_ATTACHMENT8 0x8CE8 593 COLOR_ATTACHMENT9 0x8CE9 594 COLOR_ATTACHMENT10 0x8CEA 595 COLOR_ATTACHMENT11 0x8CEB 596 COLOR_ATTACHMENT12 0x8CEC 597 COLOR_ATTACHMENT13 0x8CED 598 COLOR_ATTACHMENT14 0x8CEE 599 COLOR_ATTACHMENT15 0x8CEF 600 DEPTH_ATTACHMENT 0x8D00 601 STENCIL_ATTACHMENT 0x8D20 602 DEPTH_STENCIL_ATTACHMENT 0x821A 603 604 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 605 GetFloatv, and GetDoublev: 606 607 MAX_SAMPLES 0x8D57 608 FRAMEBUFFER_BINDING 0x8CA6 // alias DRAW_FRAMEBUFFER_BINDING 609 DRAW_FRAMEBUFFER_BINDING 0x8CA6 610 READ_FRAMEBUFFER_BINDING 0x8CAA 611 RENDERBUFFER_BINDING 0x8CA7 612 MAX_COLOR_ATTACHMENTS 0x8CDF 613 MAX_RENDERBUFFER_SIZE 0x84E8 614 615 616 Returned by CheckFramebufferStatus(): 617 618 FRAMEBUFFER_COMPLETE 0x8CD5 619 FRAMEBUFFER_INCOMPLETE_ATTACHMENT 0x8CD6 620 FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT 0x8CD7 621 FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER 0x8CDB 622 FRAMEBUFFER_INCOMPLETE_READ_BUFFER 0x8CDC 623 FRAMEBUFFER_UNSUPPORTED 0x8CDD 624 FRAMEBUFFER_INCOMPLETE_MULTISAMPLE 0x8D56 625 FRAMEBUFFER_UNDEFINED 0x8219 626 627 Returned by GetError(): 628 629 INVALID_FRAMEBUFFER_OPERATION 0x0506 630 631 Accepted by the <format> parameter of DrawPixels, ReadPixels, 632 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, 633 TexSubImage3D, and GetTexImage, by the <type> parameter of 634 CopyPixels, by the <internalformat> parameter of TexImage1D, 635 TexImage2D, TexImage3D, CopyTexImage1D, CopyTexImage2D, and 636 RenderbufferStorage, and returned in the <data> parameter of 637 GetTexLevelParameter and GetRenderbufferParameteriv: 638 639 DEPTH_STENCIL 0x84F9 640 641 Accepted by the <type> parameter of DrawPixels, ReadPixels, 642 TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, 643 TexSubImage3D, and GetTexImage: 644 645 UNSIGNED_INT_24_8 0x84FA 646 647 Accepted by the <internalformat> parameter of TexImage1D, 648 TexImage2D, TexImage3D, CopyTexImage1D, CopyTexImage2D, and 649 RenderbufferStorage, and returned in the <data> parameter of 650 GetTexLevelParameter and GetRenderbufferParameteriv: 651 652 DEPTH24_STENCIL8 0x88F0 653 654 Accepted by the <value> parameter of GetTexLevelParameter: 655 656 TEXTURE_STENCIL_SIZE 0x88F1 657 658 659Additions to Chapter 2 of the 2.1 Specification (OpenGL Operation) 660 661 "The GL interacts with two classes of framebuffers: window 662 system-provided and application-created. There is at most one window 663 system-provided framebuffer at any time, referred to as the <default 664 framebuffer>. Application-created framebuffers, referred to as 665 <framebuffer objects>, may be created as desired. These two types of 666 framebuffer are distinguished primarily by the interface for configuring 667 and managing their state. 668 669 The effects of GL commands on the default framebuffer are ultimately 670 controlled by the window system, which allocates framebuffer resources, 671 determines what portions of the default framebuffer the GL may access at 672 any given time, and communicates to the GL how those portions are 673 structured. Therefore, there are no GL commands to initialize a GL 674 context or configure the default framebuffer. Similarly, display of 675 framebuffer contents on a physical display device (including the 676 transformation of individual framebuffer values by such techniques as 677 gamma correction) is not addressed by the GL. 678 679 Allocation and configuration of the default framebuffer occurs outside 680 of the GL in conjunction with the window system, using companion APIs 681 such as GLX, WGL, and AGL for GL implementations running on the X Window 682 System, Microsoft Windows, and MacOS X respectively. 683 684 Allocation and initialization of GL contexts is also done using these 685 companion APIs. GL contexts can typically be associated with different 686 default framebuffers, and some context state is determined at the time 687 this association is performed. 688 689 It is possible to use a GL context <without> a default framebuffer, in 690 which case a framebuffer object must be used to perform all rendering. 691 This is useful for applications needing to perform <offscreen 692 rendering>." 693 694 695 Add to table 2.3, "Summary of GL errors": 696 697 Error Description Offending command 698 ignored? 699 ----------------------------- ------------------ ----------------- 700 ... 701 INVALID_FRAMEBUFFER_OPERATION Framebuffer object Yes 702 is not complete 703 704 705 Append the following to section 2.6.1 "Begin and End": 706 707 "Calling Begin will result in an INVALID_FRAMEBUFFER_OPERATION 708 error if the object bound to DRAW_FRAMEBUFFER_BINDING is not 709 "framebuffer complete" (see section 4.4.4.2)." 710 711 Update the bulleted list in section 2.15.4 "Shader Execution" in 712 the subsection titled "Texture Access" to say: 713 714 "* The sampler used in a texture lookup function is not one of 715 the shadow sampler types, the texture object's base internal 716 format is DEPTH_COMPONENT or DEPTH_STENCIL, and the 717 TEXTURE_COMPARE_MODE is not NONE. 718 719 * The sampler used in a texture lookup function is one of the 720 shadow sampler types, the texture object's base 721 internal format is DEPTH_COMPONENT or DEPTH_STENCIL, and the 722 TEXTURE_COMPARE_MODE is NONE. 723 724 * The sampler used in a texture lookup function is one of the 725 shadow sampler types, and the texture object's base 726 internal format is not DEPTH_COMPONENT or DEPTH_STENCIL. 727 728 The stencil index texture internal component is ignored if the base 729 internal format is DEPTH_STENCIL. 730 731 If a vertex shader uses..." 732 733 734Additions to Chapter 3 of the OpenGL 2.1 Specification (Rasterization) 735 736 Update section 3.6.3 "Pixel Transfer Modes", the first paragraph of 737 the subsection "Color Table Specification", in the definition of 738 ColorTable, to say: 739 740 "... The <formats> COLOR_INDEX, DEPTH_COMPONENT, DEPTH_STENCIL, 741 and STENCIL_INDEX and the <type> BITMAP are not allowed." 742 743 Update section 3.6.3 "Pixel Transfer Modes", the third paragraph of 744 the subsection "Color Table Specification", in the definition of 745 ColorTable, to say: 746 747 "... <internalformat> must be one of the formats in table 3.15 or 748 table 3.16, other than the DEPTH_COMPONENT or DEPTH_STENCIL 749 formats in those tables." 750 751 Add to section 3.6.3 "Pixel Transfer Modes", at the end of the 752 subsection titled "Alternate Color Table Specification Commands": 753 754 "Calling CopyColorTable or CopyColorSubTable will result in an 755 INVALID_FRAMEBUFFER_OPERATION error if the object bound to 756 READ_FRAMEBUFFER_BINDING is not "framebuffer complete" 757 (see section 4.4.4.2)." 758 759 In section 3.6.3 "Pixel Transfer Modes", the subsection "Covolution 760 Filter Specification", update the first paragraph in the definition 761 of ConvolutionFilter2D to say: 762 763 "... The formats COLOR_INDEX, DEPTH_COMPONENT, DEPTH_STENCIL, 764 and STENCIL_INDEX and the type BITMAP are not allowed." 765 766 In section 3.6.3 "Pixel Transfer Modes", update the third paragraph 767 of the subsection "Convolution Filter Specification", in the definition 768 of ConvolutionFilter2D, to say: 769 770 "... <internalformat> accepts the same values as the corresponding 771 argument of ColorTable." 772 773 Add to section 3.6.3 "Pixel Transfer Modes", at the end of the 774 subsection titled "Alternate Convolution Filter Specification Commands": 775 776 "Calling CopyConvolutionFilter1D or CopyConvolutionFilter2D will 777 result in an INVALID_FRAMEBUFFER_OPERATION error if the object 778 bound to READ_FRAMEBUFFER_BINDING is not "framebuffer 779 complete" (see section 4.4.4.2)." 780 781 In section 3.6.3 "Pixel Transfer Modes", update the third paragraph 782 of the "Histogram Table Specification" subsection , in the definition of 783 Histogram, to say: 784 785 "... is too large for the implementation. <internalformat> accepts the 786 same values as the corresponding argument of ColorTable, with the 787 exception of the values 1, 2, 3, and 4." 788 789 In section 3.6.3 "Pixel Transfer Modes", update the second paragraph 790 in the subsection titled "Minmax Table Specification", in the definition 791 of Minmax to say: 792 793 "<internalformat> accepts the same values as the corresponding argument 794 of ColorTable, with the exception of the values 1, 2, 3, and 4, as well 795 as the INTENSITY base and sized internal formats." 796 797 In section 3.6.4 "Rasterization of Pixel Rectangles", modify the final 798 paragraph of the definition of DrawPixels as follows: 799 800 "... If the GL is in color index mode and <format> is not one of 801 COLOR_INDEX, STENCIL_INDEX, DEPTH_COMPONENT, or DEPTH_STENCIL, 802 then the error INVALID_OPERATION occurs. If <type> is BITMAP and 803 <format> is not COLOR_INDEX or STENCIL_INDEX then the error 804 INVALID_ENUM occurs. If <format> is DEPTH_STENCIL and <type> is 805 not UNSIGNED_INT_24_8 then the error INVALID_ENUM occurs. Some 806 additional constraints on the combinations of <format> and <type> 807 values that are accepted is discussed below. 808 809 "Calling DrawPixels 810 will result in an INVALID_FRAMEBUFFER_OPERATION error if the 811 object bound to DRAW_FRAMEBUFFER_BINDING is not 812 "framebuffer complete" (see section 4.4.4.2)." 813 814 Add a row to Table 3.5, in section 3.6.4: 815 816 type Parameter GL Type Special 817 --------------------------- ------- ------- 818 ... ... ... 819 UNSIGNED_INT_2_10_10_10_REV uint Yes 820 UNSIGNED_INT_24_8 uint Yes 821 822 Add a row to Table 3.6, in section 3.6.4: 823 824 Format Name Element Meaning and Order Target Buffer 825 --------------- ------------------------- ----------------- 826 ... ... ... 827 DEPTH_COMPONENT Depth Depth 828 DEPTH_STENCIL Depth and Stencil Index Depth and Stencil 829 ... ... ... 830 831 In section 3.6.4 "Rasterization of Pixel Rectangles", in the subsection 832 titled "Unpacking", update the last paragraph on page 131 to say: 833 834 "Calling DrawPixels with a <type> matching one of the types in table 3.8 835 is a special case in which all the components of each group are packed 836 into a single unsigned byte, unsigned short, or unsigned int, depending 837 on the type. The number of components..." 838 839 Add a row to Table 3.8, in section 3.6.4: 840 841 type Parameter GL Type Components Pixel Formats 842 --------------------------- ------- ---------- ------------- 843 ... ... ... ... 844 UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA 845 UNSIGNED_INT_24_8 uint 2 DEPTH_STENCIL 846 847 Add the following diagram to Table 3.11, in section 3.6.4: 848 849 UNSIGNED_INT_24_8 850 851 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 852 +----------------------------------+---------------+ 853 | 1st Component | 2nd Component | 854 +----------------------------------+---------------+ 855 856 Add a row to Table 3.12, in section 3.6.4: 857 858 Format | 1st 2nd 3rd 4th 859 --------------+------------------------------- 860 ... | ... ... ... ... 861 BGRA | blue green red alpha 862 DEPTH_STENCIL | depth stencil N/A N/A 863 864 In section 3.6.4 "Rasterization of Pixel Rectangles", add the 865 following sentence to the end of the first paragraph in "Conversion 866 to floating-point": 867 868 "For groups containing both components and indices, such as 869 DEPTH_STENCIL, the indices are not converted." 870 871 In section 3.6.4 "Rasterization of Pixel Rectangles", update the 872 last paragraph in the section "Conversion to Fragments" to say: 873 874 "... Groups arising from DrawPixels with a <format> of STENCIL_INDEX 875 or DEPTH_STENCIL are treated specially and are described in 876 section 4.3.1." 877 878 Update the first paragraph of section 3.6.5 "Pixel Transfer 879 Operations" to say: 880 881 "The GL defines five kinds of pixel groups: 882 883 1. RGBA component: Each group comprises four color components: 884 red, green, blue, and alpha. 885 2. Depth component: Each group comprises a single depth 886 component. 887 3. Color index: Each group comprises a single color index. 888 4. Stencil index: Each group comprises a single stencil index. 889 5. Depth/stencil: Each group comprises a single depth component 890 and a single stencil index." 891 892 In section 3.6.5 "Pixel Transfer Operations" update the first paragraph 893 in the subsection "Arithmetic on Components" to say: 894 895 "This step applies only to RGBA component and depth component 896 groups, and to the depth components in depth/stencil groups. ..." 897 898 In section 3.6.5 "Pixel Transfer Operations" update the first paragraph 899 in the subsection "Arithmetic on Indices" to say: 900 901 "This step applies only to color index and stencil index groups, and 902 to the stencil indices in depth/stencil groups. ..." 903 904 In section 3.6.5 "Pixel Transfer Operations" update the first paragraph 905 in the subsection "Stencil Index Lookup" to say: 906 907 "This step applies only to stencil index groups and to the stencil 908 indices in depth/stencil groups. ..." 909 910 Add the following to section 3.7 "Bitmaps", following the description of 911 Bitmap: 912 913 "Calling Bitmap will result in an 914 INVALID_FRAMEBUFFER_OPERATION error if the object bound to 915 DRAW_FRAMEBUFFER_BINDING is not "framebuffer complete" 916 (see section 4.4.4.2)." 917 918 In section 3.8.1 "Texture Image Specification", update the following 919 paragraphs as follows: 920 921 Update the fourth paragraph to say: 922 923 "The selected groups are processed exactly as for DrawPixels, 924 stopping just before final conversion. Each R, G, B, A, or depth 925 value so generated is clamped to [0, 1], while the stencil index 926 values are masked by 2^n-1, where n is the number of stencil bits in 927 the internal format resolution (see below). If the base internal 928 format is DEPTH_STENCIL and <format> is not DEPTH_STENCIL, 929 then the values of the stencil index texture component are 930 undefined." 931 932 Update the fifth paragraph to say: 933 934 "Components are then selected from the resulting R, G, B, A, depth, 935 or stencil index values to obtain a texture with the base internal 936 format specified by (or derived from) <internalformat>. Table 3.15 937 summarizes the mapping of R, G, B, A, depth, or stencil values to 938 texture components, as a function of the base internal format of the 939 texture image. <internalformat> may be specified as one of the 940 eight internal format symbolic constants listed in table 3.15, as 941 one of ..." 942 943 Update the sixth paragraph to say: 944 945 "Textures with a base internal format of DEPTH_COMPONENT or 946 DEPTH_STENCIL are supported by texture image specification 947 commands only if <target> is TEXTURE_1D, TEXTURE_2D, 948 PROXY_TEXTURE_1D or PROXY_TEXTURE_2D. Using these formats in 949 conjunction with any other <target> will result in an 950 INVALID_OPERATION error." 951 952 Update the seventh paragraph to say: 953 954 Textures with a base internal format of DEPTH_COMPONENT or 955 DEPTH_STENCIL require either depth component data or 956 depth/stencil component data. Textures with other base internal 957 formats require RGBA component data. The error INVALID_OPERATION is 958 generated if one of the base internal format and <format> 959 is DEPTH_COMPONENT or DEPTH_STENCIL, and the other is neither 960 of these values." 961 962 Update the tenth paragraph to say: 963 964 "...the mapping of the R, G, B, A, depth and stencil values to 965 texture components..." 966 967 Add a row to table 3.15 in section 3.8.1, and update the title of the 968 second column: 969 970 Base Internal Format RGBA and Depth and Stencil Values Internal Components 971 -------------------- --------------------------------- ------------------- 972 ... ... ... 973 DEPTH_STENCIL Depth,Stencil D,S 974 ... ... ... 975 976 Update the caption for table 3.15 977 978 "Table 3.15: Conversion from RGBA, depth, and stencil pixel 979 components to internal texture, table, or filter components. See 980 section 3.8.13 for a description of the texture components R, G, B, 981 A, L, I, D, and S." 982 983 Add a new column to table 3.16, in section 3.8.1, labeled "S bits". The 984 value of this column is blank for all rows except a new row: 985 986 Sized Base R G B A L I D S 987 Internal Format InternalFormat bits bits bits bits bits bits bits bits 988 ---------------- -------------- ---- ---- ---- ---- ---- ---- ---- ---- 989 ... ... ... ... ... ... ... ... ... ... 990 DEPTH24_STENCIL8 DEPTH_STENCIL 24 8 991 ... ... ... ... ... ... ... ... ... ... 992 993 In section 3.8.2 "Alternate Texture Image Specification Commands", 994 update the second paragraph, in the definition of CopyTexImage2D, to 995 say: 996 997 "...The image is taken from the framebuffer exactly as if these 998 arguments were passed to CopyPixels with argument type set to COLOR 999 DEPTH, or DEPTH_STENCIL, depending on <internalformat>, stopping 1000 after pixel transfer processing is complete. RGBA data is taken 1001 from the current color buffer, while depth component and stencil 1002 index data are taken from the depth and stencil buffers, 1003 respectively. If depth component data is required and no depth 1004 buffer is present, or if stencil index data is required and there is 1005 no stencil buffer, the error INVALID_OPERATION is generated. 1006 Subsequent processing is identical to that described for TexImage2D, 1007 beginning with clamping of the R, G, B, A, or depth values, and 1008 masking of the stencil index value, from the resulting pixel 1009 groups..." 1010 1011 Update the third paragraph to say: 1012 1013 "Subsequent processing is identical to that described for TexImage2D, 1014 beginning with clamping of the R, G, B, A, or depth values, and masking 1015 of the stencil index values from the resulting pixel groups..." 1016 1017 In section 3.8.2 "Alternate Texture Image Specification Commands", 1018 update the seventh paragraph, in the description of the 1019 CopyTexSubImage{2|3}D arguments, to say: 1020 1021 "...except that the assignment of R, G, B, A, depth, and stencil 1022 pixel group values to the texture components is controlled by the 1023 internalformat of the texture array, not by an argument to the 1024 command..." 1025 1026 Append the following to section 3.8.2 "Alternate Texture Image 1027 Specification Commands": 1028 1029 "Calling CopyTexSubImage3D, CopyTexImage2D, 1030 CopyTexSubImage2D, CopyTexImage1D or CopyTexSubImage1D will result 1031 in an INVALID_FRAMEBUFFER_OPERATION error if the object bound 1032 to READ_FRAMEBUFFER_BINDING is not "framebuffer complete" 1033 (see section 4.4.4.2)." 1034 1035 Update section 3.8.5 "Depth Component Textures" to say: 1036 1037 "Depth textures and the depth components of depth/stencil textures 1038 can be treated as LUMINANCE, INTENSITY or ALPHA textures during 1039 texture filtering and application. The initial state for depth and 1040 depth/stencil textures treats them as LUMINANCE textures." 1041 1042 In section 3.8.8 "Texture Minification", add the following text 1043 immediately before the subsection "Mipmapping": 1044 1045 "If all of the following conditions are satisfied, then the value of 1046 the selected Tau(ijk), Tau(ij), or Tau(i) in the above equations is 1047 undefined instead of referring to the value of the texel at location 1048 (i), (i,j), or (i,j,k). See Chapter 4 for discussion of framebuffer 1049 objects and their attachments. 1050 1051 * The current DRAW_FRAMEBUFFER_BINDING names an application-created 1052 framebuffer object <F>. 1053 1054 * The texture is attached to one of the attachment points, <A>, of 1055 framebuffer object <F>. 1056 1057 * The value of TEXTURE_MIN_FILTER is NEAREST or LINEAR, and the value 1058 of FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL for attachment point <A> 1059 is equal to the value of TEXTURE_BASE_LEVEL 1060 1061 -or- 1062 1063 The value of TEXTURE_MIN_FILTER is NEAREST_MIPMAP_NEAREST, 1064 NEAREST_MIPMAP_LINEAR, LINEAR_MIPMAP_NEAREST, or 1065 LINEAR_MIPMAP_LINEAR, and the value of 1066 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL for attachment point 1067 <A> is within the inclusive range from TEXTURE_BASE_LEVEL to q." 1068 1069 In subsection "Automatic Mipmap Generation" to section 3.8.8, 1070 replace the first paragraph with the following text and footnote: 1071 1072 "If the value of texture parameter GENERATE MIPMAP is TRUE and a 1073 change is made to the interior or border texels of the level_base 1074 array of a mipmap by one of the texture image specification 1075 operations defined in sections 3.8.1 through 3.8.3, then a complete 1076 set of mipmap arrays (as defined in section 3.8.10) will be 1077 computed. Array levels level_base + 1 through p are replaced with 1078 arrays derived from the modified level_base, regardless of their 1079 previous contents. All other mipmap arrays, including the 1080 level_base array, are left unchanged by this computation[fn1]." 1081 1082 "[fn1] Automatic mipmap generation is not performed for changes 1083 resulting from rendering operations targeting a texture array 1084 bound as a color buffer of a framebuffer object." 1085 1086 1087 Add a new subsection "Manual Mipmap Generation" to section 3.8.8, 1088 after "Automatic Mipmap Generation": 1089 1090 "Manual Mipmap Generation 1091 1092 Mipmaps can be generated manually with the command 1093 1094 void GenerateMipmap(enum target); 1095 1096 where <target> is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_CUBE_MAP, or 1097 TEXTURE_3D. Mipmap generation affects the texture image attached to 1098 <target>. For cube map textures, an INVALID_OPERATION error is generated 1099 if the texture bound to <target> is not cube complete, as defined in 1100 section 3.8.10. 1101 1102 Mipmap generation replaces texture array levels level_base + 1 1103 through q with arrays derived from the level_base array, as 1104 described above under Automatic Mipmap Generation. All other mipmap 1105 arrays, including the level_base array, are left unchanged by this 1106 computation. For arrays in the range level_base+1 through q, 1107 inclusive, automatic and manual mipmap generation generate the same 1108 derived arrays, given identical level_base arrays." 1109 1110 Add a new section between sections 3.8.9 and 3.8.10: 1111 1112 "3.8.10 DEPTH_STENCIL Textures 1113 1114 If the texture image has a base internal format of 1115 DEPTH_STENCIL, then the stencil index texture component is 1116 ignored. The texture value Tau does not include a stencil index 1117 component, but includes only the depth component." 1118 1119 Update the first paragraph of section 3.8.11 "Texture State and 1120 Proxy State" to say: 1121 1122 "...eight integer values describing the resolutions of each of the 1123 red, green, blue, alpha, luminance, intensity, depth, and stencil 1124 components of the image..." 1125 1126 Update the second paragraph of section 3.8.11 "Texture State and 1127 Proxy State" to say: 1128 1129 "... and internal format state values, as well as state for the red, 1130 green, blue, alpha, luminance, intensity, depth, and stencil 1131 component resolutions." 1132 1133 Modify the definition of DeleteTextures in section 3.8.12 "Texture 1134 Objects", to read: 1135 1136 "Texture objects are deleted by calling 1137 1138 void DeleteTextures( sizei n, uint *textures ); 1139 1140 textures contains n names of texture objects to be deleted. After a 1141 texture object is deleted, it has no contents or dimensionality, and 1142 its name is again unused. If a texture that is currently bound to 1143 one of the targets TEXTURE 1D, TEXTURE 2D, TEXTURE 3D, or TEXTURE 1144 CUBE MAP is deleted, it is as though BindTexture had been executed 1145 with the same target and texture zero. Additionally, special care 1146 must be taken when deleting a texture if any of the images of the 1147 texture are attached to a framebuffer object. See section 4.4.2.3 1148 for details. 1149 1150 Unused names in textures are silently ignored, as is the value 1151 zero." 1152 1153 In section 3.8.14 "Texture Comparison Modes", update the first 1154 paragraph of "Depth Texture Comparison Mode" subsection to say: 1155 1156 "If the currently bound texture's base internal format is 1157 DEPTH_COMPONENT or DEPTH_STENCIL..." 1158 1159 In the section 3.8.16 "Texture Application", update the first 1160 paragraph of to say: 1161 1162 "...Otherwise, a texture value is found according to the parameter 1163 values of the currently bound texture image of the appropriate 1164 dimensionality using the rules given in sections 3.8.6 through 1165 3.8.9. Note that the texture value may contain R, G, B, A, L, I, or 1166 D components, but it does not contain an S component. If the 1167 texture's base internal format is DEPTH_STENCIL, for the 1168 purposes of texture application, it is as if the base internal 1169 format were DEPTH_COMPONENT..." 1170 1171 In section 3.11.2 "Shader Execution", in the bulleted list 1172 in the "Texture Access" subsection to say: 1173 1174 "* The sampler used in a texture lookup function is not one of the 1175 shadow sampler types, the texture object's base internal 1176 format is DEPTH_COMPONENT or DEPTH_STENCIL, and the 1177 TEXTURE_COMPARE_MODE is not NONE. 1178 1179 * The sampler used in a texture lookup function is one of the 1180 shadow sampler types, the texture object's base 1181 internal format is DEPTH_COMPONENT or DEPTH_STENCIL, and the 1182 TEXTURE_COMPARE_MODE is NONE. 1183 1184 * The sampler used in a texture lookup function is one of the 1185 shadow sampler types, and the texture object's base 1186 internal format is not DEPTH_COMPONENT or DEPTH_STENCIL. 1187 1188 The stencil index texture internal component is ignored if the base 1189 internal format is DEPTH_STENCIL. 1190 1191 If a fragment shader uses..." 1192 1193 1194Additions to Chapter 4 of the OpenGL 2.1 Specification (Per-Fragment 1195Operations and the Framebuffer) 1196 1197 In the introduction to chapter 4, modify the first 1198 three paragraphs to read as follows: 1199 1200 "The framebuffer, whether it is the default framebuffer or a framebuffer 1201 object (see section 2.1), consists of a set of pixels arranged as a 1202 two-dimensional array. 1203 For purposes of this 1204 discussion, each pixel in the framebuffer is simply a set of some 1205 number of bits. The number of bits per pixel may vary 1206 depending on the GL implementation, the type of framebuffer 1207 selected, and parameters specified when the framebuffer was created. 1208 Creation and management of the default framebuffer is outside the scope 1209 of this specification, while creation and management of framebuffer 1210 objects is described in detail in section 4.4 1211 1212 Corresponding bits from each pixel in the framebuffer are grouped 1213 together into a <bitplane>; each bitplane contains a single bit from 1214 each pixel. These bitplanes are grouped into several <logical 1215 buffers>. These are the color, accumulation, depth, and stencil 1216 buffers. The color buffer actually consists of a number of buffers, 1217 and these color buffers serve related but slightly different 1218 purposes depending on whether the GL is bound to the default 1219 framebuffer or a framebuffer object. 1220 1221 For the default framebuffer, the color buffers are the <front left> 1222 buffer, the <front right> buffer, the <back left> buffer, the <back 1223 right> buffer, and some number of <auxiliary> buffers. Typically, the 1224 contents of the front buffers are displayed on a color monitor while the 1225 contents of the back buffers are invisible. (Monoscopic contexts display 1226 only the front left buffer; stereoscopic contexts display both the front 1227 left and the front right buffers.) The contents of the auxiliary buffers 1228 are never visible. All color buffers must have the same number of 1229 bitplanes, although an implementation or context may choose not to 1230 provide right buffers, back buffers, or auxiliary buffers at all. 1231 Further, an implementation or context may choose not to provide 1232 accumulation, depth, or stencil buffers. If no default framebuffer is 1233 associated with the GL context, the framebuffer is incomplete except 1234 when a framebuffer object is bound (see sections 4.4.1 and 4.4.4). 1235 1236 Framebuffer objects are not visible, and do not have any of the color 1237 buffers present in the default framebuffer. Instead, the buffers of an 1238 framebuffer object are specified by attaching individual textures or 1239 renderbuffers (see section 4.4) to a set of attachment points. A 1240 framebuffer object has an array of color buffer attachment points, 1241 numbered zero through <n>, a depth buffer attachment point, and a 1242 stencil buffer attachment point. In order to be used for rendering, a 1243 framebuffer object must be complete, as described in section 4.4.4. Not 1244 all attachments of a framebuffer object need to be populated. 1245 1246 Each pixel in a color buffer consists of either an unsigned integer 1247 color index or of up to four color components. The four color components 1248 are named R, G, B, and A, in that order; color buffers are not required 1249 to have all four color components. R, G, B, and A components may be 1250 represented as signed or unsigned normalized fixed-point, 1251 floating-point, or signed or unsigned integer values; all components 1252 must have the same representation. Each pixel in a depth buffer consists 1253 of a single unsigned integer value in the format described in section 1254 2.12.1 or a floating-point value. Each pixel in a stencil buffer 1255 consists of a single unsigned integer value. Each pixel in an 1256 accumulation buffer consists of up to four color components. If an 1257 accumulation buffer is present, it must have at least as many bitplanes 1258 per component as in the color buffers. 1259 1260 The number of bitplanes in the accumulation, color, depth, and stencil 1261 buffers is dependent on the currently bound framebuffer. For the default 1262 framebuffer, the number of bitplanes is fixed. For framebuffer objects, 1263 the number of bitplanes in a given logical buffer may change if the 1264 image attached to the corresponding attachment point changes. 1265 1266 The GL has two active framebuffers; the <draw framebuffer> is the 1267 destination for rendering operations, and the <read framebuffer> is the 1268 source for readback operations. The same framebuffer may be used for 1269 both drawing and reading. Section 4.4.1 describes the mechanism for 1270 controlling framebuffer usage." 1271 1272 The default framebuffer is initially used as the draw and read 1273 framebuffer [fn1], and the initial state of all provided bitplanes is 1274 undefined. The format and encoding of buffers in the draw and read 1275 framebuffers can be queried as described in section 6.1.3. 1276 [fn1] The window system binding API may allow associating a GL 1277 context with two separate ``default framebuffers'' provided by 1278 the window system as the draw and read framebuffers, but if 1279 so, both default framebuffers are referred to by the name zero 1280 at their respective binding points. 1281 1282 Add a new paragraph to the end of section 4.1.1 "Pixel Ownership Test": 1283 1284 "If the draw framebuffer is a framebuffer object (see section 4.2.1), 1285 the pixel ownership test always passes, since the pixels of framebuffer 1286 objects are owned by the GL, not the window system. If the draw 1287 framebuffer is the default framebuffer, the window system controls pixel 1288 ownership." 1289 1290 Change section 4.1.5 "Stencil Test", the fifth paragraph, 1291 the second and third sentences, to read as follows: 1292 1293 "<ref> is an integer reference value that is used in the unsigned 1294 stencil comparison. Stencil comparison operations and queries of 1295 of <ref> clamp its value to the range [0,(2^s)-1], where <s> is the 1296 number of bits in the stencil buffer attached to the draw framebuffer. 1297 1298 Replace the first three sentences of 4.1.10 "Logical Operation": 1299 1300 "Finally, a logical operation is applied between the incoming 1301 fragment's color or index values and the color or index values 1302 stored at the corresponding location in the framebuffer. The result 1303 replaces the values in the framebuffer at the fragment's (x[w], 1304 y[w]) coordinates. If the selected draw buffers refer to the same 1305 framebuffer-attachable image more than once, then the values stored 1306 in that image are undefined." 1307 1308 Change section 4.2.1 "Selecting a Buffer for Writing", to read as follows: 1309 1310 "The first such operation is controlling the buffers into which each of 1311 the fragment color values is written. This is accomplished with either 1312 DrawBuffer or DrawBuffers. The command 1313 1314 void DrawBuffer( enum buf ); 1315 1316 defines the set of color buffers to which fragment color zero is 1317 written. <buf> must be one of the values from tables 4.4 or 10.nnn. In 1318 addition, acceptable values for <buf> depend on whether the GL is using 1319 the default framebuffer (i.e., DRAW_FRAMEBUFFER_BINDING is zero), or a 1320 framebuffer object (i.e., DRAW_FRAMEBUFFER_BINDING is non-zero). In the 1321 initial state, the GL is bound to the default framebuffer. For more 1322 information about framebuffer objects, see section 4.4. 1323 1324 If the GL is bound to the default framebuffer, then 1325 <buf> must be one the values listed in table 4.4, which summarizes 1326 the constants and the buffers they indicate. In this case, <buf> is 1327 a symbolic constant specifying zero, one, two, or four buffers for 1328 writing. These constants refer to the four potentially visible 1329 buffers front left, front right, back left, and back right, and to 1330 the auxiliary buffers. Arguments other than AUXi that omit 1331 reference to LEFT or RIGHT refer to both left and right buffers. 1332 Arguments other than AUXi that omit reference to FRONT or BACK refer 1333 to both front and back buffers. AUXi enables drawing only to 1334 auxiliary buffer i. Each AUXi adheres to AUXi = AUX0 + i, 1335 and i must be in the range 0 to the value of AUX_BUFFERS minus one. 1336 1337 If the GL is bound to a framebuffer object, 1338 <buf> must be one of the values listed in table 10.nnn, which 1339 summarizes the constants and the buffers they indicate. In this 1340 case, <buf> is a symbolic constant specifying a single color buffer 1341 for writing. Specifying COLOR_ATTACHMENTi enables drawing only 1342 to the image attached to the framebuffer at COLOR_ATTACHMENTi. 1343 Each COLOR_ATTACHMENTi adheres to COLOR_ATTACHMENTi = 1344 COLOR_ATTACHMENT0 + i. The initial value of DRAW_BUFFER for 1345 application-created framebuffer objects is COLOR_ATTACHMENT0. 1346 1347 1348 Symbolic Constant Meaning 1349 ----------------- ------- 1350 NONE no buffer 1351 COLOR_ATTACHMENTi (see caption) output fragment color to image attached 1352 at color attachment point i 1353 ------------------------------------------------------------------- 1354 Table 10.nnn: Arguments to DrawBuffer(s) and ReadBuffer when the 1355 context is bound to a framebuffer object, and 1356 the buffers they indicate. i in COLOR_ATTACHMENTi may range from 1357 zero to the value of MAX_COLOR_ATTACHMENTS - 1. 1358 1359 If the GL is bound to the default framebuffer and 1360 DrawBuffer is supplied with a constant (other than NONE) that does 1361 not indicate any of the color buffers allocated to the GL context, 1362 the error INVALID_OPERATION results. 1363 1364 If the GL is bound to a framebuffer object and <buf> is one of the 1365 constants from table 4.4, then the error INVALID_OPERATION results. 1366 If <buf> is COLOR_ATTACHMENT<m> and <m> is greater than or equal to 1367 the value of MAX_COLOR_ATTACHMENTS, then the error INVALID_VALUE 1368 results. 1369 1370 If DrawBuffer is supplied with a constant that is neither legal for 1371 the default framebuffer nor a framebuffer object, then the error 1372 INVALID_ENUM results. 1373 1374 DrawBuffer will set the draw buffer for fragment colors other than 1375 zero to NONE. 1376 1377 The command 1378 1379 void DrawBuffers( sizei n, const enum *bufs ); 1380 1381 defines the draw buffers to which all fragment colors are written. 1382 <n> specifies the number of buffers in <bufs>. <bufs> is a pointer 1383 to an array of symbolic constants specifying the buffer to which 1384 each fragment color is written. 1385 1386 Each buffer listed in <bufs> must be one of the values from tables 1387 10.nnn or 11.nnn. Otherwise, an INVALID_ENUM error is generated. 1388 Further, acceptable values for the constants in <bufs> depend on 1389 whether the GL is using the default 1390 framebuffer (i.e., DRAW_FRAMEBUFFER_BINDING is zero), or an 1391 framebuffer object (i.e., 1392 DRAW_FRAMEBUFFER_BINDING is non-zero). For more information about 1393 framebuffer objects, see section 4.4. 1394 1395 1396 symbolic front front back back aux 1397 constant left right left right i 1398 -------- ----- ----- ---- ----- --- 1399 NONE 1400 FRONT LEFT X 1401 FRONT RIGHT X 1402 BACK LEFT X 1403 BACK RIGHT X 1404 AUXi X 1405 -------------------------------------------------- 1406 Table 11.nnn: Arguments to DrawBuffers, when the context is bound 1407 to the default framebuffer, and the buffers that they indicate. 1408 1409 If the GL is bound to the default 1410 framebuffer, then each of the constants must be one of the 1411 values listed in table 11.nnn. 1412 1413 If the GL is bound to a framebuffer object, 1414 then each of the constants must be one of the values listed in table 1415 10.nnn. 1416 1417 In both cases, the draw buffers being defined correspond in order to 1418 the respective fragment colors. The draw buffer for fragment colors 1419 beyond <n> is set to NONE. 1420 1421 The maximum number of draw buffers is implementation dependent and 1422 must be at least 1. The number of draw buffers supported can be 1423 queried by calling GetIntegerv with the symbolic constant 1424 MAX_DRAW_BUFFERS. An INVALID_VALUE error is generated if <n> is 1425 greater than MAX_DRAW_BUFFERS. 1426 1427 Except for NONE, a buffer may not appear more then once in the array 1428 pointed to by <bufs>. Specifying a buffer more then once will 1429 result in the error INVALID_OPERATION. 1430 1431 If fixed-function fragment shading is being performed, DrawBuffers 1432 specifies a set of draw buffers into which the fragment color is 1433 written. 1434 1435 If a fragment shader writes to "gl_FragColor", DrawBuffers specifies 1436 a set of draw buffers into which the single fragment color defined 1437 by "gl_FragColor" is written. If a fragment shader writes to 1438 "gl_FragData", DrawBuffers specifies a set of draw buffers into which 1439 each of the multiple fragment colors defined by "gl_FragData" are 1440 separately written. If a fragment shader writes to neither 1441 "gl_FragColor" nor "gl_FragData", the values of the fragment colors 1442 following shader execution are undefined, and may differ for each 1443 fragment color. 1444 1445 For both the default framebuffer and framebuffer objects, 1446 the constants FRONT, BACK, LEFT, RIGHT, and 1447 FRONT_AND_BACK are not valid in the <bufs> array passed to 1448 DrawBuffers, and will result in the error INVALID_OPERATION. This 1449 restriction is because these constants may themselves refer to 1450 multiple buffers, as shown in table 4.4. 1451 1452 If the GL is bound to the default framebuffer and 1453 DrawBuffers is supplied with a constant (other than NONE) that does 1454 not indicate any of the color buffers allocated to the GL context by 1455 the window system, the error INVALID_OPERATION will be generated. 1456 1457 If the GL is bound to a framebuffer object and 1458 DrawBuffers is supplied with a constant from table 11.nnn, or 1459 COLOR_ATTACHMENTm where m is greater than or equal to the value of 1460 MAX_COLOR_ATTACHMENTS, then the error INVALID_OPERATION results. 1461 1462 Indicating a buffer or buffers using DrawBuffer or DrawBuffers 1463 causes subsequent pixel color value writes to affect the indicated 1464 buffers. 1465 1466 Specifying NONE as the draw buffer for a fragment color will inhibit 1467 that fragment color from being written to any buffer. 1468 1469 Monoscopic contexts include only left buffers, while stereoscopic 1470 contexts include both left and right buffers. Likewise, single 1471 buffered contexts include only front buffers, while double buffered 1472 contexts include both front and back buffers. The type of context 1473 is selected at GL initialization. 1474 1475 The state required to handle color buffer selection for each 1476 framebuffer is an integer 1477 for each supported fragment color. For the default 1478 framebuffer, in the initial state, the draw 1479 buffer for fragment color zero is FRONT if there are no back 1480 buffers; otherwise it is BACK. For framebuffer 1481 objects, in the initial state the draw buffer for fragment color zero is 1482 COLOR_ATTACHMENT0. For both the default 1483 framebuffer and framebuffers objects, the initial state 1484 of draw buffers for fragment colors other then zero is NONE. 1485 1486 The value of the draw buffer selected for fragment color <i> can be 1487 queried by calling GetIntegerv with the symbolic constant DRAW_BUFFERi. 1488 DRAW_BUFFER is equivalent to DRAW_BUFFER0." 1489 1490 In section 4.2.2 "Fine Control of Buffer Updates", modify the beginning 1491 of the paragraph defining <mask> for StencilMask and StencilMaskSeparate 1492 as follows: 1493 1494 Modify the second to last paragraph of section 4.2.4 "The Accumulation 1495 Buffer" as follows: 1496 1497 "If there is no accumulation buffer, or if the DRAW_FRAMEBUFFER 1498 and READ_FRAMEBUFFER bindings (see section 4.4.4.2) do not refer to 1499 the same object, or if the GL is in color index mode, Accum 1500 generates the error INVALID_OPERATION." 1501 1502 Replace section 4.3.1 "Writing to the Stencil Buffer" with the following: 1503 1504 "4.3.1 Writing to the Stencil Buffer or to the Depth and Stencil 1505 Buffers 1506 1507 The operation of DrawPixels was described in section 3.6.4, except 1508 if the <format> argument was STENCIL_INDEX or DEPTH_STENCIL. In 1509 this case, all operations described for DrawPixels take place, but 1510 window (x,y) coordinates, each with the corresponding stencil index, 1511 or depth value and stencil index, are produced in lieu of fragments. 1512 Each coordinate-data pair is sent directly to the per-fragment 1513 operations, bypassing the texture, fog, and antialiasing application 1514 stages of rasterization. Each pair is then treated as a fragment 1515 for purposes of the pixel ownership and scissor tests; all other 1516 per-fragment operations are bypassed. Finally, each stencil index 1517 is written to its indicated location in the framebuffer, subject to 1518 the current front stencil mask (set with StencilMask or 1519 StencilMaskSeparate). If a depth component is present, and if the 1520 setting of DepthMask is not FALSE, the depth component is also 1521 written to the framebuffer; the setting of DepthTest is ignored. 1522 1523 The error INVALID_OPERATION results if the <format> argument is 1524 STENCIL_INDEX and there is no stencil buffer, or if <format> is 1525 DEPTH_STENCIL and there is not both a depth buffer and a stencil 1526 buffer." 1527 1528 Add to 4.3.2 "Reading Pixels", right before the subsection titled 1529 "Obtaining Pixels from the Framebuffer": 1530 1531 "ReadPixels generates an INVALID_OPERATION error 1532 if READ_FRAMEBUFFER_BINDING 1533 (see section 4.4) is non-zero, the read framebuffer is framebuffer 1534 complete, and the value of SAMPLE_BUFFERS for the read framebuffer 1535 is greater than zero." 1536 1537 In section 4.3.2 "Reading Pixels", add the following paragraph 1538 after the second paragraph of the section "Obtaining Pixels from 1539 the Framebuffer": 1540 1541 "If the <format> is DEPTH_STENCIL, then values are taken from 1542 both the depth buffer and the stencil buffer. If there is no depth 1543 buffer or if there is no stencil buffer, then the error 1544 INVALID_OPERATION occurs. If the <type> parameter is not 1545 UNSIGNED_INT_24_8, then the error INVALID_ENUM occurs. 1546 1547 If there is a multisample buffer, then values are obtained from the 1548 depth and stencil samples in this buffer. It is recommended that the 1549 depth and stencil values of the centermost sample be used, though 1550 implementations may choose any function of the depth and stencil 1551 sample values at each pixel." 1552 1553 In section 4.3.2 "Reading Pixels" in the subsection "Obtaining Pixels 1554 from the Framebuffer", modify the first two paragraphs of the 1555 definition of ReadBuffer to read as follows: 1556 1557 "The command 1558 1559 void ReadBuffer( enum src ); 1560 1561 takes a symbolic constant as argument. <src> must be one of the 1562 values from tables 4.4 or 10.nnn. Otherwise, INVALID_ENUM is 1563 generated. Further, the acceptable values for <src> depend on 1564 whether the GL is using the default 1565 framebuffer (i.e., READ_FRAMEBUFFER_BINDING is zero), or a 1566 framebuffer object (i.e., 1567 READ_FRAMEBUFFER_BINDING is non-zero). For more information about 1568 framebuffer objects, see section 4.4. 1569 1570 If the object bound to READ_FRAMEBUFFER_BINDING is not <framebuffer 1571 complete> (as defined in section 4.4.4.2), then ReadPixels generates 1572 the error INVALID_FRAMEBUFFER_OPERATION. If ReadBuffer is 1573 supplied with a constant that is neither legal for the default 1574 framebuffer, nor legal for a 1575 framebuffer object, then the error INVALID_ENUM results. 1576 1577 When READ_FRAMEBUFFER_BINDING is zero, i.e. the default framebuffer, 1578 <src> must be one of the values listed in table 4.4, including NONE. 1579 FRONT_AND_BACK, FRONT, and LEFT refer to the front left buffer, BACK 1580 refers to the back left buffer, and RIGHT refers to the front right 1581 buffer. The other constants correspond directly to the buffers that they 1582 name. If the requested buffer is missing, then the error 1583 INVALID_OPERATION is generated. For the default framebuffer, the initial 1584 setting for ReadBuffer is FRONT if there is no back buffer and BACK 1585 otherwise. 1586 1587 When the GL is using a framebuffer object, <src> must be one of the 1588 values listed in table 10.nnn, including NONE. In a manner analogous to 1589 how the DRAW_BUFFERs state is handled, specifying COLOR_ATTACHMENTi 1590 enables reading from the image attached to the framebuffer at 1591 COLOR_ATTACHMENTi. For framebuffer objects, the initial setting for 1592 ReadBuffer is COLOR_ATTACHMENT0. 1593 1594 ReadPixels generates an INVALID_OPERATION error if it attempts to select 1595 a color buffer while READ_BUFFER is NONE. 1596 1597 ReadPixels obtains values from the selected buffer from each pixel 1598 with lower left hand corner at (x+i, y+j) for (0 <= i < width) and 1599 (0 <= j < height); this pixel is said to be the ith pixel in the jth 1600 row. If any of these pixels lies outside of the window allocated to 1601 the current GL context, or outside of the image attached to the 1602 currently bound framebuffer object, then the values obtained for 1603 those pixels are undefined. When READ_FRAMEBUFFER_BINDING is zero, 1604 results are also undefined for individual pixels that are not owned 1605 by the current context. Otherwise, ReadPixels obtains values from 1606 the selected buffer, regardless of how those values were placed 1607 there." 1608 1609 In section 4.3.2 "Reading Pixels", modify the last paragraph of the 1610 subsection "Obtaining Pixels from the Framebuffer", to say: 1611 1612 "... If the GL is in color index mode, and <format> is not 1613 DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL, then the color 1614 index is obtained at each pixel location." 1615 1616 In section 4.3.2 "Reading Pixels", add a paragraph at the end of the 1617 subsection "Obtaining Pixels from the Framebuffer" immediately before 1618 "Conversion of RGBA values": 1619 1620 "When READ_FRAMEBUFFER_BINDING is non-zero, the red, green, blue, and 1621 alpha values are obtained by first reading the internal component 1622 values of the corresponding value in the image attached to the 1623 selected logical buffer. Internal components are converted to an 1624 RGBA color by taking each R, G, B, and A component present according 1625 to the base internal format of the buffer (as shown in table 3.15). 1626 If G, B, or A values are not present in the internal format, they 1627 are taken to be zero, zero, and one respectively. 1628 1629 In section 4.3.2 "Reading Pixels", update the first sentence of the 1630 subsection "Conversion of RGBA values" to say: 1631 1632 "This step applies only if the GL is in RGBA mode, and then only if 1633 <format> is neither STENCIL_INDEX, DEPTH_COMPONENT, nor 1634 DEPTH_STENCIL." 1635 1636 In section 4.3.2 "Reading Pixels", update the section "Conversion 1637 of Depth values" to say: 1638 1639 "This step applies only if <format> is DEPTH_COMPONENT or 1640 DEPTH_STENCIL. Each element taken from the depth buffer is 1641 taken to be a fixed-point value in [0,1] with m bits, where m is the 1642 number of bits in the depth buffer (see section 2.11.1)." 1643 1644 Add a row to Table 4.6, in section 4.3.2 "Reading Pixels": 1645 1646 type Parameter Index Mask 1647 ----------------- ---------- 1648 ... ... 1649 INT 2^31-1 1650 UNSIGNED_INT_24_8 2^8-1 1651 1652 Modify the first sentence of section 4.3.3 "Copying Pixels" as follows: 1653 1654 "CopyPixels transfers a rectangle of pixel values from one region 1655 of the read framebuffer to another in the draw framebuffer." 1656 1657 In section 4.3.3 "Copying Pixels", update the second and third 1658 paragraphs to say: 1659 1660 "<type> is a symbolic constant that must be one of COLOR, STENCIL, 1661 DEPTH, or DEPTH_STENCIL, indicating that the values to be 1662 transferred are colors, stencil values, depth values, or 1663 depth/stencil values, respectively. The first four arguments have the 1664 same interpretation as the corresponding arguments to ReadPixels. 1665 1666 Values are obtained from the framebuffer, converted (if 1667 appropriate), then subjected to the pixel transfer operations 1668 described in section 3.6.5, just as if ReadPixels were called with 1669 the corresponding arguments. If the <type> is STENCIL or DEPTH, 1670 then it is as if the <format> for ReadPixels were STENCIL_INDEX, or 1671 DEPTH_COMPONENT, respectively. If the <type> is DEPTH_STENCIL, 1672 then it is as if the <format> for ReadPixels were specified as 1673 described in table 4.6b. If the <type> is COLOR, then if the GL is 1674 in RGBA mode, it is as if the <format> were RGBA, while if the GL is 1675 in color index mode, it is as if the <format> were COLOR_INDEX." 1676 1677 Add Table 4.6b: 1678 1679 DEPTH_BITS STENCIL_BITS format 1680 ---------- ------------ --------------- 1681 zero zero DEPTH_STENCIL 1682 zero non-zero DEPTH_COMPONENT 1683 non-zero zero STENCIL_INDEX 1684 non-zero non-zero DEPTH_STENCIL 1685 1686 Table 4.6b: Effective ReadPixels format for DEPTH_STENCIL 1687 CopyPixels operation. 1688 1689 Add a row to Table 4.7 (page 224): 1690 1691 type Parameter GL Type Component Conversion ... 1692 --------------------------- ------- --------------------------- 1693 ... ... ... 1694 UNSIGNED_INT_2_10_10_10_REV uint c = (2^N - 1)f 1695 UNSIGNED_INT_24_8 uint c = (2^N - 1)f (depth only) 1696 1697 Add the following text to section 4.3.3 "Copying Pixels", inside the 1698 definition of CopyPixels: 1699 1700 "Finally, the behavior of several GL operations is specified "as if 1701 the arguments were passed to CopyPixels." These operations include: 1702 CopyTex{Sub}Image*, CopyColor{Sub}Table, and CopyConvolutionFilter*. 1703 An INVALID_FRAMEBUFFER_OPERATION error will be generated if an attempt is 1704 made to execute one of these operations, or CopyPixels, while the 1705 object bound to READ_FRAMEBUFFER_BINDING (see section 4.4) is not 1706 "framebuffer complete" (as defined in section 4.4.4.2). 1707 An INVALID_OPERATION error will be generated if the object bound to 1708 READ_FRAMEBUFFER_BINDING is "framebuffer complete" and the value 1709 of SAMPLE_BUFFERS is greater than zero. 1710 1711 CopyPixels will generate an INVALID_FRAMEBUFFER_OPERATION error 1712 if the object bound to DRAW_FRAMEBUFFER_BINDING (see section 1713 4.4) is not "framebuffer complete". 1714 1715 Append to section 4.3.3 "Copying Pixels": 1716 1717 "The command 1718 1719 BlitFramebuffer(int srcX0, int srcY0, int srcX1, int srcY1, 1720 int dstX0, int dstY0, int dstX1, int dstY1, 1721 bitfield mask, enum filter); 1722 1723 transfers a rectangle of pixel values from one 1724 region of the read framebuffer to another in the draw framebuffer. 1725 There are some important distinctions from CopyPixels, as 1726 described below. 1727 1728 <mask> is the bitwise OR of a number of values indicating which 1729 buffers are to be copied. The values are COLOR_BUFFER_BIT, 1730 DEPTH_BUFFER_BIT, and STENCIL_BUFFER_BIT, which are described in 1731 section 4.2.3. The pixels corresponding to these buffers are 1732 copied from the source rectangle bounded by the locations (srcX0, 1733 srcY0) and (srcX1, srcY1), to the destination rectangle bounded by 1734 the locations (dstX0, dstY0) and (dstX1, dstY1). The lower bounds 1735 of the rectangle are inclusive, while the upper bounds are 1736 exclusive. 1737 1738 When the color buffer is transferred, values are taken from the read 1739 buffer of the read framebuffer and written to each of the draw buffers 1740 of the draw framebuffer, just as with CopyPixels. 1741 1742 The actual region taken from the read framebuffer is limited to the 1743 intersection of the source buffers being transferred, which may include 1744 the color buffer selected by the read buffer, the depth buffer, and/or 1745 the stencil buffer depending on <mask>. 1746 The actual region written to the draw framebuffer is limited to the 1747 intersection of the destination buffers being written, which may include 1748 multiple draw buffers, the depth buffer, and/or the stencil buffer 1749 depending on <mask> 1750 Whether or not the source or destination regions are altered due to 1751 these limits, the scaling and offset applied to pixels being transferred 1752 is performed as though no such limits were present. 1753 1754 If the source and destination rectangle dimensions do not match, 1755 the source image is stretched to fit the destination 1756 rectangle. <filter> must be LINEAR or NEAREST and specifies the 1757 method of interpolation to be applied if the image is 1758 stretched. LINEAR filtering is allowed only for the color buffer; 1759 if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, and 1760 filter is not NEAREST, no copy is performed and an 1761 INVALID_OPERATION error is generated. If the source and 1762 destination dimensions are identical, no filtering is applied. If 1763 either the source or destination rectangle specifies a negative 1764 width or height (X1 < X0 or Y1 < Y0), 1765 the image is reversed in the corresponding direction. 1766 If both the source and destination rectangles specify a negative 1767 dimension for the same direction, no reversal is performed. 1768 If a linear filter is selected and the rules of LINEAR sampling 1769 would require sampling outside the bounds of a source buffer, it is 1770 as though CLAMP_TO_EDGE texture sampling were being performed. If a 1771 linear filter is selected and sampling would be required outside the 1772 bounds of the specified source region, but within the bounds of a 1773 source buffer, the implementation may choose to clamp while sampling 1774 or not. 1775 1776 If the source and destination buffers are identical, and the 1777 source and destination rectangles overlap, the result of the blit 1778 operation is undefined. 1779 1780 Blit operations bypass the fragment pipeline. The only fragment 1781 operations which affect a blit are the pixel ownership test and 1782 the scissor test. 1783 1784 If a buffer is specified in <mask> and does not exist in both the 1785 read and draw framebuffers, the corresponding bit is silently 1786 ignored. 1787 1788 If the color formats of the read and draw framebuffers do not 1789 match, and <mask> includes COLOR_BUFFER_BIT, pixel groups are 1790 converted to match the destination format as in CopyPixels. 1791 However, no pixel transfer operations are applied, and clamping 1792 behaves as if CLAMP_FRAGMENT_COLOR_ARB is set to FIXED_ONLY_ARB. 1793 Format conversion is not supported for all data types. If the read 1794 buffer contains floating-point values and any draw buffer does not 1795 contain floating-point values, or if the read buffer contains 1796 non-floating-point values and any draw buffer contains 1797 floating-point values, an INVALID_OPERATION error is generated. 1798 1799 Calling BlitFramebuffer will result in an 1800 INVALID_FRAMEBUFFER_OPERATION error if the objects bound to 1801 DRAW_FRAMEBUFFER_BINDING and READ_FRAMEBUFFER_BINDING are 1802 not "framebuffer complete" (see section 4.4.4.2)." 1803 1804 Calling BlitFramebuffer will result in an INVALID_OPERATION 1805 error if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT 1806 and the source and destination depth and stencil buffer formats do 1807 not match. 1808 1809 If SAMPLE_BUFFERS for the read framebuffer is greater than zero and 1810 SAMPLE_BUFFERS for the draw framebuffer is zero, the samples 1811 corresponding to each pixel location in the source are converted to 1812 a single sample before being written to the destination. 1813 1814 If SAMPLE_BUFFERS for the read framebuffer is zero and 1815 SAMPLE_BUFFERS for the draw framebuffer is greater than zero, the 1816 value of the source sample is replicated in each of the destination 1817 samples. 1818 1819 If SAMPLE_BUFFERS for both the read and draw framebuffers are 1820 greater than zero, and the values of SAMPLES for the read and draw 1821 framebuffers are identical, the samples are copied without 1822 modification from the read framebuffer to the draw framebuffer. 1823 Otherwise, no copy is performed and an INVALID_OPERATION error is 1824 generated. Note that the samples in the draw buffer are not 1825 guaranteed to be at the same sample location as the read buffer, 1826 so rendering using this newly created buffer can potentially 1827 have geometry cracks or incorrect antialiasing. This may occur 1828 if the sizes of the framebuffers do not match, if the 1829 formats differ, or if the source and destination rectangles are 1830 not defined with the same (X0,Y0) and (X1,Y1) bounds. 1831 1832 If SAMPLE_BUFFERS for either the read framebuffer or 1833 draw framebuffer is greater than zero, no copy is performed and an 1834 INVALID_OPERATION error is generated if the dimensions of the source 1835 and destination rectangles provided to BlitFramebuffer are not 1836 identical, or if the formats of the read and draw framebuffers are 1837 not identical. 1838 1839 1840 Add a new section "Framebuffer Objects" after section 4.3: 1841 1842 "4.4 Framebuffer Objects 1843 1844 As described in chapters 1 and 2, GL renders into (and reads values 1845 from) a framebuffer. GL defines two classes of framebuffers: 1846 window-system-provided framebuffers and application-created 1847 framebuffers. For each GL context, there is a single framebuffer 1848 provided by the window-system, and there may also be one or more 1849 framebuffer objects created and managed by the application. 1850 1851 By default, the GL uses the window-system-provided framebuffer. The 1852 storage, dimensions, allocation, and format of the images attached 1853 to this framebuffer are managed entirely by the window-system. 1854 Consequently, the state of the window-system-provided framebuffer, 1855 including its images, can not be changed by the GL, nor can the 1856 window-system-provided framebuffer itself, or its images, be deleted 1857 by the GL. 1858 1859 The routines described in the following sections, however, can be 1860 used to create, destroy, and modify the state and attachments of 1861 application-created framebuffer objects. 1862 1863 Application-created framebuffer objects encapsulate the state of a 1864 framebuffer in a similar manner to the way texture objects 1865 encapsulate the state of a texture. In particular, a framebuffer 1866 object encapsulates state necessary to describe a collection of 1867 color, depth, and stencil logical buffers (accumulation and 1868 auxiliary buffers are not allowed). For each 1869 logical buffer, a framebuffer-attachable image can be attached to 1870 the framebuffer to store the rendered output for that logical 1871 buffer. Examples of framebuffer-attachable images include texture 1872 images and renderbuffer images. Renderbuffers are described further 1873 in section 4.4.2.1 1874 1875 By allowing the images of a renderbuffer to be attached to a 1876 framebuffer, the GL provides a mechanism to support "off-screen" 1877 rendering. Further, by allowing the images of a texture to be 1878 attached to a framebuffer, the GL provides a mechanism to support 1879 "render to texture". 1880 1881 4.4.1 Binding and Managing Framebuffer Objects 1882 1883 The default framebuffer for rendering and readback operations is 1884 provided by the window system. In addition, named framebuffer 1885 objects can be created and operated upon. The namespace for 1886 framebuffer objects is the unsigned integers, with zero reserved 1887 by the GL for the default framebuffer. 1888 1889 A framebuffer object is created by binding 1890 a name returned by GenFramebuffers (see below) to 1891 DRAW_FRAMEBUFFER or READ_FRAMEBUFFER. The binding is 1892 effected by calling 1893 1894 void BindFramebuffer(enum target, uint framebuffer); 1895 1896 with <target> set to the desired framebuffer target and 1897 <framebuffer> set to the framebuffer object name. 1898 The resulting framebuffer 1899 object is a new state vector, comprising all the state values 1900 listed in table 4.nnn, as well as one set of the state values 1901 listed in table 5.nnn for each attachment point of the 1902 framebuffer, set to the same initial values. There are 1903 MAX_COLOR_ATTACHMENTS color attachment points, plus one each 1904 for the depth and stencil attachment points. 1905 1906 BindFramebuffer may also be used to bind an existing 1907 framebuffer object to DRAW_FRAMEBUFFER or 1908 READ_FRAMEBUFFER. If the bind is successful no change is made 1909 to the state of the bound framebuffer object, and any previous 1910 binding to <target> is broken. 1911 1912 BindFramebuffer fails and an INVALID_OPERATION error is generated if 1913 <framebuffer> is not zero or a name returned from a previous call to 1914 GenFramebuffers, or if such a name has since been deleted with 1915 DeleteFramebuffers. 1916 1917 If a framebuffer object is bound to DRAW_FRAMEBUFFER or 1918 READ_FRAMEBUFFER, it becomes the target for rendering or 1919 readback operations, respectively, until it is deleted or another 1920 framebuffer is bound to the corresponding bind point. Calling 1921 BindFramebuffer with <target> set to FRAMEBUFFER binds the 1922 framebuffer to both the draw and read targets. 1923 1924 While a framebuffer object is bound, GL operations on the target 1925 to which it is bound affect the images attached to the bound 1926 framebuffer object, and queries of the target to which it is bound 1927 return state from the bound object. Queries of the values 1928 specified in table 6.31 (Implementation Dependent Pixel Depths) 1929 and table 8.nnn (Framebuffer-Dependent State Variables) are 1930 derived from the framebuffer object bound to DRAW_FRAMEBUFFER. 1931 1932 The initial state of DRAW_FRAMEBUFFER and READ_FRAMEBUFFER 1933 refers to the default framebuffer. 1934 In order that access to the default framebuffer is not 1935 lost, it is treated as a framebuffer object with the name of zero. 1936 The default framebuffer is therefore rendered to and read from 1937 while zero is bound to the corresponding targets. On some 1938 implementations, the properties of the default framebuffer can 1939 change over time (e.g., in response to window system events 1940 such as attaching the context to a new window system drawable.) 1941 1942 Framebuffer objects (those with a non-zero 1943 name) differ from the default framebuffer in 1944 a few important ways. First and foremost, unlike the 1945 default framebuffer, framebuffer objects 1946 have modifiable attachment points for each logical buffer in the 1947 framebuffer. Framebuffer-attachable images can be attached to and 1948 detached from these attachment points, which are described further 1949 in section 4.4.2. Also, the size and format of the images attached 1950 to application-created framebuffers are controlled entirely within 1951 the GL interface, and are not affected by window system events, such 1952 as pixel format selection, window resizes, and display mode changes. 1953 1954 Additionally, when rendering to or reading from an application 1955 created-framebuffer object, 1956 1957 - The pixel ownership test always succeeds. In other words, 1958 framebuffer objects own all of their pixels. 1959 1960 - There are no visible color buffer bitplanes. This means 1961 there is no color buffer corresponding to the back, front, 1962 left, or right color bitplanes. 1963 1964 - The only color buffer bitplanes are the ones defined by the 1965 framebuffer attachment points named COLOR_ATTACHMENT0 1966 through COLOR_ATTACHMENTn. 1967 1968 - The only depth buffer bitplanes are the ones defined by the 1969 framebuffer attachment point DEPTH_ATTACHMENT. 1970 1971 - The only stencil buffer bitplanes are the ones defined by 1972 the framebuffer attachment point STENCIL_ATTACHMENT. 1973 1974 - There are no accum buffer bitplanes, so the value of the 1975 implementation-dependent state variables ACCUM_RED_BITS, 1976 ACCUM_GREEN_BITS, ACCUM_BLUE_BITS, and ACCUM_ALPHA_BITS, are 1977 all zero. 1978 1979 - There are no AUX buffer bitplanes, so the value of the 1980 implementation-dependent state variable AUX_BUFFERS is zero. 1981 1982 - If the attachment sizes are not all identical, rendering will be 1983 limited to the largest area that can fit in all of the 1984 attachments (i.e. an intersection of rectangles having a lower 1985 left of (0,0) and an upper right of (width,height) for each 1986 attachment) 1987 1988 - If the attachment sizes are not all identical, the values of 1989 pixels outside the common intersection area after rendering are 1990 undefined. 1991 1992 Framebuffer objects are deleted by calling 1993 1994 void DeleteFramebuffers(sizei n, uint *framebuffers); 1995 1996 <framebuffers> contains <n> names of framebuffer objects to be 1997 deleted. After a framebuffer object is deleted, it has no 1998 attachments, and its name is again unused. If a framebuffer that 1999 is currently bound to one or more of the targets 2000 DRAW_FRAMEBUFFER or READ_FRAMEBUFFER is deleted, it is as 2001 though BindFramebuffer had been executed with the corresponding 2002 <target> and <framebuffer> zero. Unused names in 2003 <framebuffers> are silently ignored, as is the value zero. 2004 2005 The command 2006 2007 void GenFramebuffers(sizei n, uint *ids); 2008 2009 returns <n> previously unused framebuffer object names in <ids>. 2010 These names are marked as used, for the purposes of 2011 GenFramebuffers only, but they acquire state and type only when 2012 they are first bound, just as if they were unused. 2013 2014 The names bound to the draw and read framebuffer bindings can be 2015 queried by calling GetIntegerv with the symbolic constants 2016 DRAW_FRAMEBUFFER_BINDING and READ_FRAMEBUFFER_BINDING 2017 respectively. FRAMEBUFFER_BINDING is equivalent to 2018 DRAW_FRAMEBUFFER_BINDING. 2019 2020 4.4.2 Attaching Images to Framebuffer Objects 2021 2022 Framebuffer-attachable images may be attached to, and detached from, 2023 framebuffer objects. In contrast, the image 2024 attachments of the default framebuffer may not be 2025 changed by the GL. 2026 2027 A single framebuffer-attachable image may be attached to multiple 2028 framebuffer objects, potentially avoiding some 2029 data copies, and possibly decreasing memory consumption. 2030 2031 For each logical buffer, a framebuffer object stores a set of 2032 state which defines the logical buffer's <attachment point>. The 2033 attachment point state contains enough information to identify the 2034 single image attached to the attachment point, or to indicate that 2035 no image is attached. The per-logical buffer attachment point 2036 state is listed in table 5.nnn 2037 2038 There are two types of framebuffer-attachable images: the image of a 2039 renderbuffer object, and an image of a texture object. 2040 2041 4.4.2.1 Renderbuffer Objects 2042 2043 A renderbuffer is a data storage object containing a single image of 2044 a renderable internal format. GL provides the methods described 2045 below to allocate and delete a renderbuffer's image, and to attach a 2046 renderbuffer's image to a framebuffer object. 2047 2048 The name space for renderbuffer objects is the unsigned integers, 2049 with zero reserved for the GL. A renderbuffer object is created by 2050 binding a name returned by GenRenderbuffers (see below) 2051 to RENDERBUFFER. The binding is effected by calling 2052 2053 void BindRenderbuffer( enum target, uint renderbuffer ); 2054 2055 with <target> set to RENDERBUFFER and <renderbuffer> set to the 2056 unused name. If <renderbuffer> is not zero, then the resulting 2057 renderbuffer object is a new state vector, initialized with a 2058 zero-sized memory buffer, and comprising the state values listed in 2059 Table 8.nnn. Any previous binding to <target> is broken. 2060 2061 BindRenderbuffer may also be used to bind an existing 2062 renderbuffer object. If the bind is successful, no change is made 2063 to the state of the newly bound renderbuffer object, and any 2064 previous binding to <target> is broken. 2065 2066 While a renderbuffer object is bound, GL operations on the target to 2067 which it is bound affect the bound renderbuffer object, and queries 2068 of the target to which a renderbuffer object is bound return state 2069 from the bound object. 2070 2071 The name zero is reserved. A renderbuffer object cannot be created 2072 with the name zero. If <renderbuffer> is zero, then any previous 2073 binding to <target> is broken and the <target> binding is restored 2074 to the initial state. 2075 2076 In the initial state, the reserved name zero is bound to 2077 RENDERBUFFER. There is no renderbuffer object corresponding to 2078 the name zero, so client attempts to modify or query renderbuffer 2079 state for the target RENDERBUFFER while zero is bound will 2080 generate GL errors, as described in section 6.1.3. 2081 2082 The current RENDERBUFFER binding can be determined by calling 2083 GetIntegerv with the symbolic constant RENDERBUFFER_BINDING. 2084 2085 BindRenderbuffer fails and an INVALID_OPERATION error is generated 2086 if <renderbuffer> is not a name returned from a previous call to 2087 GenRenderbuffers, or if such a name has since been deleted with 2088 DeleteRenderbuffers. 2089 2090 Renderbuffer objects are deleted by calling 2091 2092 void DeleteRenderbuffers( sizei n, const uint *renderbuffers ); 2093 2094 where <renderbuffers> contains <n> names of renderbuffer objects to be 2095 deleted. After a renderbuffer object is deleted, it has no 2096 contents, and its name is again unused. If a renderbuffer that is 2097 currently bound to RENDERBUFFER is deleted, it is as though 2098 BindRenderbuffer had been executed with the <target> 2099 RENDERBUFFER and <name> of zero. Additionally, special care 2100 must be taken when deleting a renderbuffer if the image of the 2101 renderbuffer is attached to a framebuffer object (see section 2102 4.4.2.2 for details). Unused names in <renderbuffers> are silently 2103 ignored, as is the value zero. 2104 2105 The command 2106 2107 void GenRenderbuffers( sizei n, uint *renderbuffers ); 2108 2109 returns <n> previously unused renderbuffer object names in 2110 <renderbuffers>. These names are marked as used, for the purposes 2111 of GenRenderbuffers only, but they acquire renderbuffer state 2112 only when they are first bound, just as if they were unused. 2113 2114 The command 2115 2116 void RenderbufferStorageMultisample(enum target, sizei samples, 2117 enum internalformat, 2118 sizei width, sizei height); 2119 2120 establishes the data storage, format, dimensions, and number of 2121 samples of a renderbuffer object's image. <target> must be 2122 RENDERBUFFER. <internalformat> must be color-renderable, depth- 2123 renderable, or stencil-renderable (as defined in section 4.4.4). 2124 <width> and <height> are the dimensions in pixels of the renderbuffer. 2125 If either <width> or <height> is greater than MAX_RENDERBUFFER_SIZE, 2126 or if <samples> is greater than MAX_SAMPLES, 2127 then the error INVALID_VALUE is 2128 generated. If the GL is unable to create a data store of the 2129 requested size, the error OUT_OF_MEMORY is generated. 2130 2131 Upon success, RenderbufferStorageMultisample deletes any existing 2132 data store for the renderbuffer image and the contents of the data 2133 store after calling RenderbufferStorageMultisample are undefined. 2134 RENDERBUFFER_WIDTH is set to <width>, RENDERBUFFER_HEIGHT is 2135 set to <height>, and RENDERBUFFER_INTERNAL_FORMAT is set to 2136 <internalformat>. 2137 2138 If <samples> is zero, then RENDERBUFFER_SAMPLES is set to zero. 2139 Otherwise <samples> represents a request for a desired minimum 2140 number of samples. Since different implementations may support 2141 different sample counts for multisampled rendering, the actual 2142 number of samples allocated for the renderbuffer image is 2143 implementation dependent. However, the resulting value for 2144 RENDERBUFFER_SAMPLES is guaranteed to be greater than or equal 2145 to <samples> and no more than the next larger sample count supported 2146 by the implementation. 2147 2148 Sized Base S 2149 Internal Format Internal format Bits 2150 --------------- --------------- ---- 2151 STENCIL_INDEX1 STENCIL_INDEX 1 2152 STENCIL_INDEX4 STENCIL_INDEX 4 2153 STENCIL_INDEX8 STENCIL_INDEX 8 2154 STENCIL_INDEX16 STENCIL_INDEX 16 2155 ---------------------------------------------------------------- 2156 Table 2.nnn Desired component resolution for each sized internal 2157 format that can be used only with renderbuffers. 2158 2159 A GL implementation may vary its allocation of internal component 2160 resolution based on any RenderbufferStorage parameter (except 2161 target), but the allocation and chosen internal format must not be a 2162 function of any other state and cannot be changed once they are 2163 established. 2164 2165 The command 2166 2167 void RenderbufferStorage(enum target, enum internalformat, 2168 sizei width, sizei height); 2169 2170 is equivalent to calling RenderbufferStorageMultisample with 2171 <samples> equal to zero." 2172 2173 4.4.2.2 Attaching Renderbuffer Images to a Framebuffer 2174 2175 A renderbuffer can be attached as one of the logical buffers of the 2176 currently bound framebuffer object by calling 2177 2178 void FramebufferRenderbuffer(enum target, 2179 enum attachment, 2180 enum renderbuffertarget, 2181 uint renderbuffer); 2182 2183 <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or 2184 FRAMEBUFFER. FRAMEBUFFER is equivalent to 2185 DRAW_FRAMEBUFFER. 2186 An INVALID_OPERATION error is generated if the value of the 2187 corresponding binding is zero. <attachment> should be set to 2188 one of the attachment points of the framebuffer listed in table 2189 1.nnn. <renderbuffertarget> must be RENDERBUFFER and 2190 <renderbuffer> should be set to the name of the renderbuffer object 2191 to be attached to the framebuffer. <renderbuffer> must be either 2192 zero or the name of an existing renderbuffer object of type 2193 <renderbuffertarget>, otherwise an INVALID_OPERATION error is 2194 generated. If <renderbuffer> is zero, then the value of 2195 <renderbuffertarget> is ignored. 2196 2197 If <renderbuffer> is not zero and if FramebufferRenderbuffer is 2198 successful, then the renderbuffer named <renderbuffer> will be used 2199 as the logical buffer identified by <attachment> of the framebuffer 2200 currently bound to <target>. The value of 2201 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE for the specified attachment 2202 point is set to RENDERBUFFER and the value of 2203 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME is set to <renderbuffer>. All 2204 other state values of the attachment point specified by <attachment> 2205 are set to their default values listed in table 5.nnn. No change is 2206 made to the state of the renderbuffer object and any previous 2207 attachment to the <attachment> logical buffer of the framebuffer 2208 object bound to framebuffer <target> is broken. If 2209 the attachment is not successful, then no change is made to 2210 the state of either the renderbuffer object or the framebuffer 2211 object. 2212 2213 Calling FramebufferRenderbuffer with the <renderbuffer> name zero 2214 will detach the image, if any, identified by <attachment>, in the 2215 framebuffer currently bound to <target>. All state values of the 2216 attachment point specified by <attachment> in the object bound to 2217 <target> are set to their default values listed in table 5.nnn. 2218 2219 Setting <attachment> to the value DEPTH_STENCIL_ATTACHMENT is a 2220 special case causing both the depth and stencil attachments of the 2221 framebuffer object to be set to <renderbuffer>, which should have 2222 base internal format DEPTH_STENCIL. 2223 2224 If a renderbuffer object is deleted while its image is attached to 2225 one or more attachment points in the currently bound framebuffer, 2226 then it is as if FramebufferRenderbuffer had been called, with 2227 a <renderbuffer> of 0, for each attachment point to which this image 2228 was attached in the currently bound framebuffer. In other words, 2229 this renderbuffer image is first detached from all attachment points 2230 in the currently bound framebuffer. Note that the renderbuffer 2231 image is specifically *not* detached from any non-bound 2232 framebuffers. Detaching the image from any non-bound framebuffers 2233 is the responsibility of the application. 2234 2235 Name of attachment 2236 ----------------------------------------------------- 2237 COLOR_ATTACHMENTi (see caption) 2238 DEPTH_ATTACHMENT 2239 STENCIL_ATTACHMENT 2240 DEPTH_STENCIL_ATTACHMENT 2241 ----------------------------------------------------- 2242 Table 1.nnn: Framebuffer attachment points. <i> in 2243 COLOR_ATTACHMENTi may range from zero to the value of 2244 MAX_COLOR_ATTACHMENTS - 1. 2245 2246 4.4.2.3 Attaching Texture Images to a Framebuffer 2247 2248 GL supports copying the rendered contents of the framebuffer into 2249 the images of a texture object through the use of the routines 2250 CopyTexImage{1D|2D}, and CopyTexSubImage{1D|2D|3D}. Additionally, 2251 GL supports rendering directly into the images of a texture object. 2252 2253 To render directly into a texture image, a specified image from a 2254 texture object can be attached as one of the logical buffers of the 2255 currently bound framebuffer object by calling one of the following 2256 routines, depending on the type of the texture: 2257 2258 void FramebufferTexture1D(enum target, enum attachment, 2259 enum textarget, uint texture, 2260 int level); 2261 void FramebufferTexture2D(enum target, enum attachment, 2262 enum textarget, uint texture, 2263 int level); 2264 void FramebufferTexture3D(enum target, enum attachment, 2265 enum textarget, uint texture, 2266 int level, int layer); 2267 2268 In all three routines, <target> must be DRAW_FRAMEBUFFER, 2269 READ_FRAMEBUFFER or FRAMEBUFFER. FRAMEBUFFER is 2270 equivalent to DRAW_FRAMEBUFFER. 2271 An INVALID_OPERATION error is generated if the 2272 value of the corresponding binding is zero. 2273 <attachment> must be one of the attachment points of the 2274 framebuffer listed in table 1.nnn. 2275 2276 If <texture> is zero, the image identified by <attachment>, if 2277 any, will be detached from the framebuffer currently bound to 2278 <target>. <textarget>, <level>, and <layer> are ignored. All 2279 state values of the attachment point specified by <attachment> are 2280 set to their default values listed in table 5.nnn. 2281 2282 If <texture> is not zero, then <texture> must either name an existing 2283 texture object with a target of <textarget>, or <texture> must name an 2284 existing cube map texture and <textarget> must be one of 2285 TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, 2286 TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X, 2287 TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z. Otherwise, 2288 an INVALID_OPERATION error is generated. 2289 2290 <level> specifies the mipmap level of the texture image to be 2291 attached to the framebuffer. 2292 2293 If <textarget> is TEXTURE_RECTANGLE_ARB, then <level> must be zero. 2294 If <textarget> is TEXTURE_3D, then <level> must be greater than or 2295 equal to zero and less than or equal to log base 2 of the value of 2296 MAX_3D_TEXTURE_SIZE. If <textarget> is one of 2297 TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, 2298 TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X, 2299 TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z, then 2300 <level> must be greater than or equal to zero and less than or equal 2301 to log base 2 of the value of MAX_CUBE_MAP_TEXTURE_SIZE. For all other 2302 values of <textarget>, <level> must be greater than or equal to zero and 2303 no larger than log base 2 of the value of MAX_TEXTURE_SIZE. Otherwise, 2304 an INVALID_VALUE error is generated. 2305 2306 <layer> specifies the layer of a 2-dimensional image within a 2307 3-dimensional texture. An INVALID_VALUE error is generated if 2308 <layer> is larger than the value of MAX_3D_TEXTURE_SIZE-1. 2309 2310 For FramebufferTexture1D, if <texture> is not zero, then 2311 <textarget> must be TEXTURE_1D. 2312 2313 For FramebufferTexture2D, if <texture> is not zero, then 2314 <textarget> must be one of TEXTURE_2D, TEXTURE_RECTANGLE_ARB, 2315 TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, 2316 TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X, 2317 TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z. 2318 2319 For FramebufferTexture3D, if <texture> is not zero, then 2320 <textarget> must be TEXTURE_3D. 2321 2322 If <texture> is not zero, and if FramebufferTexture{1D|2D|3D} is 2323 successful, then the specified texture image will be used as the 2324 logical buffer identified by <attachment> of the framebuffer 2325 currently bound to <target>. The value of 2326 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE for the specified attachment 2327 point is set to TEXTURE and the value of 2328 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME is set to <texture>. 2329 Additionally, the value of FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL for 2330 the named attachment point is set to <level>. If <texture> is a 2331 cube map texture, then the value of 2332 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE the named attachment 2333 point is set to <textarget>. If <texture> is a 3D texture, then the 2334 value of FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER for the named 2335 attachment point is set to <layer>. All other state values of the 2336 attachment point specified by <attachment> are set to their default 2337 values listed in table 5.nnn. No change is made to the state of the 2338 texture object, and any previous attachment to the <attachment> 2339 logical buffer of the framebuffer object bound to framebuffer 2340 <target> is broken. If the attachment is not 2341 successful, then no change is made to the state of either the 2342 texture object or the framebuffer object. 2343 2344 Setting <attachment> to the value DEPTH_STENCIL_ATTACHMENT is a 2345 special case causing both the depth and stencil attachments of the 2346 framebuffer object to be set to <texture>. <texture> must have base 2347 internal format DEPTH_STENCIL, or the depth and stencil 2348 framebuffer attachments will be incomplete (see section 4.4.4.1). 2349 2350 The command 2351 2352 void FramebufferTextureLayer(enum target,enum attachment, 2353 uint texture,int level,int layer); 2354 2355 operates identically to FramebufferTexture3D, except that it 2356 attaches a single layer of a three-dimensional texture, or one- or 2357 two-dimensional array texture. <layer> is an integer indicating the 2358 layer number, and is treated identically to the <layer> parameter in 2359 FramebufferTexture3D. The error INVALID_VALUE is generated if 2360 <layer> is negative. The error INVALID_OPERATION is generated if 2361 <texture> is non-zero and is not the name of a three dimensional 2362 texture, or one- or two-dimensional array texture. 2363 2364 Unlike FramebufferTexture3D, no <textarget> parameter is accepted. 2365 2366 If <texture> is non-zero and the command does not result in an 2367 error, the framebuffer attachment state corresponding to 2368 <attachment> is updated as in the other FramebufferTexture commands, 2369 except that FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is set to 2370 <layer>. 2371 2372 If a texture object is deleted while its image is attached to one or 2373 more attachment points in the currently bound framebuffer, then it 2374 is as if FramebufferTexture* had been called, with a <texture> of 2375 zero, for each attachment point to which this image was attached in 2376 the currently bound framebuffer. In other words, this texture image 2377 is first detached from all attachment points in the currently bound 2378 framebuffer. Note that the texture image is specifically *not* 2379 detached from any other framebuffer objects. Detaching the texture 2380 image from any other framebuffer objects is the responsibility of 2381 the application. 2382 2383 4.4.3 Rendering When an Image of a Bound Texture Object is Also 2384 Attached to the Framebuffer 2385 2386 The mechanisms for attaching textures to a framebuffer object do not 2387 prevent a one- or two-dimensional texture level, a face of a cube 2388 map texture level, or a layer of a two-dimensional array or 2389 three-dimensional texture from being attached to the draw 2390 framebuffer while the same texture is bound to a texture unit. While 2391 any of these conditions hold, texturing operations accessing that 2392 image will produce undefined results, as described at the end of 2393 section 3.8.8. Conditions resulting in such undefined behavior are 2394 defined in more detail below. Such undefined texturing operations 2395 are likely to leave the final results of the shader or 2396 fixed-function fragment processing operations undefined, and should 2397 be avoided. 2398 2399 Special precautions need to be taken to avoid attaching a texture 2400 image to the currently bound framebuffer while the texture object is 2401 currently bound and enabled for texturing. Doing so could lead to 2402 the creation of a <feedback loop> between the writing of pixels by 2403 the GL's rendering operations and the simultaneous reading of those 2404 same pixels when used as texels in the currently bound texture. In 2405 this scenario, the framebuffer will be considered framebuffer 2406 complete (see section 4.4.4), but the values of fragments rendered 2407 while in this state will be undefined. The values of texture 2408 samples may be undefined as well, as described at the end of the 2409 "Scale Factor and Level of Detail" subsection of section 3.8.8. 2410 2411 Specifically, the values of rendered fragments are undefined if all 2412 of the following conditions are true: 2413 2414 - an image from texture object <T> is attached to the currently 2415 bound framebuffer at attachment point <A>, and 2416 2417 - the texture object <T> is currently bound to a texture unit 2418 <U>, and 2419 2420 - the current fixed-function texture state or programmable 2421 vertex and/or fragment processing state makes it possible(*) 2422 to sample from the texture object <T> bound to texture unit 2423 <U> 2424 2425 while either of the following conditions are true: 2426 2427 - the value of TEXTURE MIN FILTER for texture object <T> is 2428 NEAREST or LINEAR, and the value of 2429 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL for attachment point 2430 <A> is equal to the value of TEXTURE_BASE_LEVEL for the 2431 texture object <T>, or 2432 2433 - the value of TEXTURE_MIN_FILTER for texture object <T> is one 2434 of NEAREST_MIPMAP_NEAREST, NEAREST_MIPMAP LINEAR, LINEAR 2435 MIPMAP_NEAREST, or LINEAR_MIPMAP_LINEAR, and the value of 2436 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL for attachment point 2437 <A> is within the range specified by the current values of 2438 TEXTURE_BASE_LEVEL to q, inclusive, for the texture object 2439 <T>. (q is defined in the Mipmapping discussion of section 2440 3.8.8), 2441 2442 (*) For the purpose of this discussion, it is <possible> 2443 to sample from the texture object <T> bound to texture unit <U> 2444 if any of the following are true: 2445 2446 - Programmable vertex and fragment processing is disabled 2447 and the target of texture object <T> is enabled according 2448 to the texture target precedence rules of section 3.8.15 2449 - FRAGMENT_PROGRAM_ARB is enabled and the currently bound 2450 fragment program contains any instructions that 2451 sample from the texture object <T> bound to <U> 2452 - The active fragment or vertex shader contains any instructions 2453 that might sample from the texture object <T> bound to <U> if even 2454 those instructions might only be executed conditionally. 2455 2456 Note that if TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL exclude any 2457 levels containing image(s) attached to the currently bound 2458 framebuffer, then the above conditions will not be met, (i.e., the 2459 above rule will not cause the values of rendered fragments to be 2460 undefined.) 2461 2462 4.4.4 Framebuffer Completeness 2463 2464 A framebuffer must be <framebuffer complete> to effectively be used 2465 as the draw or read framebuffer of the GL. 2466 2467 The default framebuffer is always complete if it exists; however, if no 2468 default framebuffer exists (no window system-provided drawable is 2469 associated with the GL context), it is deemed to be incomplete. 2470 2471 A framebuffer object is said to be framebuffer complete if all of 2472 its attached images, and all framebuffer parameters required to 2473 utilize the framebuffer for rendering and reading, are consistently 2474 defined and meet the requirements defined below. The rules of 2475 framebuffer completeness are dependent on the properties of the 2476 attached images, and on certain implementation dependent 2477 restrictions. 2478 2479 The internal formats of the attached images can affect the 2480 completeness of the framebuffer, so it is useful to first define the 2481 relationship between the internal format of an image and the 2482 attachment points to which it can be attached. 2483 2484 * The following base internal formats from table 3.15 are 2485 <color-renderable>: ALPHA, LUMINANCE, LUMINANCE_ALPHA, 2486 INTENSITY, RED, RG, RGB, RGBA, FLOAT_R_NV, FLOAT_RG_NV, 2487 FLOAT_RGB_NV, and FLOAT_RGBA_NV. The sized 2488 internal formats from table 3.16 that have a color-renderable 2489 base internal format are also color-renderable. No other 2490 formats, including compressed internal formats, are 2491 color-renderable. 2492 2493 * An internal format is <depth-renderable> if it is 2494 DEPTH_COMPONENT or one of the formats from table 3.16 whose 2495 base internal format is DEPTH_COMPONENT or DEPTH_STENCIL. 2496 No other formats are depth-renderable. 2497 2498 * An internal format is <stencil-renderable> if it is 2499 STENCIL_INDEX or DEPTH_STENCIL, if it is one of the 2500 STENCIL_INDEX formats from table 2.nnn, or if it is one of the 2501 formats from table 3.16 whose base internal format is 2502 DEPTH_STENCIL. No other formats are stencil-renderable." 2503 2504 4.4.4.1 Framebuffer Attachment Completeness 2505 2506 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE for the 2507 framebuffer attachment point <attachment> is not NONE, then it is 2508 said that a framebuffer-attachable image, named <image>, is attached 2509 to the framebuffer at the attachment point. <image> is identified 2510 by the state in <attachment> as described in section 4.4.2. 2511 2512 The framebuffer attachment point <attachment> is said to be 2513 <framebuffer attachment complete> if the value of 2514 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE for <attachment> is NONE 2515 (i.e., no image is attached), or if all of the following conditions 2516 are true: 2517 2518 * <image> is a component of an existing object with the name 2519 specified by FRAMEBUFFER_ATTACHMENT_OBJECT_NAME, and of the 2520 type specified by FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE. 2521 2522 * The width and height of <image> must be non-zero. 2523 2524 * If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is TEXTURE and 2525 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME names a 3-dimensional 2526 texture, then FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER must be 2527 smaller than the depth of the texture. 2528 2529 * If <attachment> is COLOR_ATTACHMENTi, then <image> must have 2530 a color-renderable internal format. 2531 2532 * If <attachment> is DEPTH_ATTACHMENT, then <image> must have 2533 a depth-renderable internal format. 2534 2535 * If <attachment> is STENCIL_ATTACHMENT, then <image> must 2536 have a stencil-renderable internal format. 2537 2538 4.4.4.2 Whole Framebuffer Completeness 2539 2540 Each rule below is followed by an error enum enclosed in { brackets }. 2541 The meaning of these errors is explained below and under ``Effects of 2542 Framebuffer Completeness on Framebuffer Operations'' later in section 2543 4.4.4. 2544 2545 The framebuffer object <target> is said to be "framebuffer complete" if 2546 all the following conditions are true: 2547 2548 * <target> is the default framebuffer, and the default framebuffer 2549 exists. 2550 { FRAMEBUFFER_UNDEFINED } 2551 2552 * All framebuffer attachment points are framebuffer attachment 2553 complete. 2554 { FRAMEBUFFER_INCOMPLETE_ATTACHMENT } 2555 2556 * There is at least one image attached to the framebuffer. 2557 { FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT } 2558 2559 * The value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE must not be 2560 NONE for any color attachment point(s) named by DRAW_BUFFERi. 2561 { FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER } 2562 2563 * If READ_BUFFER is not NONE, then the value of 2564 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE must not be NONE for the 2565 color attachment point named by READ_BUFFER. 2566 { FRAMEBUFFER_INCOMPLETE_READ_BUFFER } 2567 2568 * The combination of internal formats of the attached 2569 images does not violate an implementation-dependent set of 2570 restrictions. 2571 { FRAMEBUFFER_UNSUPPORTED } 2572 2573 * The value of RENDERBUFFER_SAMPLES is the same for all attached 2574 images. 2575 { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE } 2576 2577 2578 The token in { brackets } after each clause of the framebuffer 2579 completeness rules specifies the return value of 2580 CheckFramebufferStatus (see below) that is generated when that 2581 clause is violated. If more than one clause is violated, it is 2582 implementation-dependent exactly which value will be returned by 2583 CheckFramebufferStatus. 2584 2585 Performing any of the following actions may change whether the 2586 framebuffer is considered complete or incomplete. 2587 2588 - Binding to a different framebuffer with BindFramebuffer. 2589 2590 - Attaching an image to the framebuffer with 2591 FramebufferTexture{1D|2D|3D} or FramebufferRenderbuffer. 2592 2593 - Detaching an image from the framebuffer with 2594 FramebufferTexture{1D|2D|3D} or FramebufferRenderbuffer. 2595 2596 - Changing the internal format of a texture image that is attached 2597 to the framebuffer by calling {Copy|Compressed}TexImage{1D|2D|3D}. 2598 2599 - Changing the internal format of a renderbuffer that is attached 2600 to the framebuffer by calling RenderbufferStorage. 2601 2602 - Deleting, with DeleteTextures or DeleteRenderbuffers, an object 2603 containing an image that is attached to a framebuffer object 2604 that is bound to the framebuffer. 2605 2606 - Changing READ_BUFFER or one of the DRAW_BUFFERS. 2607 2608 - Associating a different window system-provided drawable, or no 2609 drawable, with the default framebuffer using a window system binding 2610 API such as GLX, WGL, CGL, or EGL. 2611 2612 Although GL defines a wide variety of internal formats for 2613 framebuffer-attachable images, such as texture images and 2614 renderbuffer images, some implementations may not support rendering 2615 to particular combinations of internal formats. If the combination 2616 of formats of the images attached to a framebuffer object are not 2617 supported by the implementation, then the framebuffer is not 2618 complete under the clause labeled FRAMEBUFFER_UNSUPPORTED. There 2619 must exist, however, at least one combination of internal formats 2620 for which the framebuffer cannot be FRAMEBUFFER_UNSUPPORTED. 2621 2622 Because of the <implementation-dependent> clause of the framebuffer 2623 completeness test in particular, and because framebuffer 2624 completeness can change when the set of attached images is modified, 2625 it is strongly advised, though is not required, that an application 2626 check to see if the framebuffer is complete prior to rendering. The 2627 status of the framebuffer object currently bound to <target> can be 2628 queried by calling 2629 2630 enum CheckFramebufferStatus(enum target); 2631 2632 <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER or 2633 FRAMEBUFFER. FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER. 2634 If CheckFramebufferStatus is called within a Begin/End pair, 2635 an INVALID_OPERATION error is generated. If 2636 CheckFramebufferStatus generates an error, 0 is returned. 2637 2638 Otherwise, an enum is returned that identifies whether 2639 or not the framebuffer bound to <target> is complete, and if not 2640 complete the enum identifies one of the rules of framebuffer 2641 completeness that is violated. If the framebuffer is complete, then 2642 FRAMEBUFFER_COMPLETE is returned. 2643 2644 The values of SAMPLE_BUFFERS and SAMPLES are derived from the 2645 attachments of the currently bound framebuffer object. If the 2646 current DRAW_FRAMEBUFFER_BINDING is not framebuffer complete, 2647 then both SAMPLE_BUFFERS and SAMPLES are undefined. Otherwise, 2648 SAMPLES is equal to the value of RENDERBUFFER_SAMPLES for the 2649 attached images (which all must have the same value for 2650 RENDERBUFFER_SAMPLES). Further, SAMPLE_BUFFERS is one if 2651 SAMPLES is non-zero. Otherwise, SAMPLE_BUFFERS is zero. 2652 2653 4.4.4.3 Effects of Framebuffer Completeness on Framebuffer Operations 2654 2655 Attempting to render to or read from a framebuffer which is not 2656 framebuffer complete will generate an INVALID_FRAMEBUFFER_OPERATION 2657 error. This means that rendering commands such as Begin, 2658 RasterPos, any command that performs an implicit Begin, as well as 2659 commands that read the framebuffer such as ReadPixels and 2660 CopyTex{Sub}Image will generate the error 2661 INVALID_FRAMEBUFFER_OPERATION if called while the framebuffer is 2662 not framebuffer complete. 2663 2664 4.4.5 Effects of Framebuffer State on Framebuffer Dependent Values 2665 2666 The values of the state variables listed in table 9.nnn (Framebuffer 2667 Dependent Values) may change when a change is made to 2668 DRAW_FRAMEBUFFER_BINDING, to the state of the currently bound 2669 framebuffer object, or to an image attached to the currently bound 2670 framebuffer object. 2671 2672 When DRAW_FRAMEBUFFER_BINDING is zero, the values of the state 2673 variables listed in table 9.nnn are implementation defined. 2674 2675 When DRAW_FRAMEBUFFER_BINDING is non-zero, if the currently bound 2676 framebuffer object is not framebuffer complete, then the values of 2677 the state variables listed in table 9.nnn are undefined. 2678 2679 When DRAW_FRAMEBUFFER_BINDING is non-zero and the currently bound 2680 framebuffer object is framebuffer complete, then the values of the 2681 state variables listed in table 9.nnn are completely determined by 2682 DRAW_FRAMEBUFFER_BINDING, the state of the currently bound 2683 framebuffer object, and the state of the images attached to the 2684 currently bound framebuffer object. 2685 The values of RED_BITS, GREEN_BITS, BLUE_BITS, and ALPHA_BITS are 2686 defined only if all color attachments of the draw framebuffer have 2687 identical formats, in which case the color component depths of color 2688 attachment zero are returned. The values returned for DEPTH_BITS and 2689 STENCIL_BITS are the depth or stencil component depth of the 2690 corresponding attachment of the draw framebuffer, respectively. The 2691 actual sizes of the color, depth, or stencil bit planes can be 2692 obtained by querying an attachment point using 2693 GetFramebufferAttachmentParameteriv, 2694 or querying the object attached at that point. If the value of 2695 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE at a particular attachment 2696 point is RENDERBUFFER, the sizes may be determined by calling 2697 GetRenderbufferParameteriv as described in section 6.1.3. If 2698 the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE at a particular 2699 attachment point is TEXTURE, the sizes may be determined by calling 2700 GetTexParameter, as described in section 6.1.3. 2701 2702 2703 4.4.6 Mapping between Pixel and Element in Attached Image 2704 2705 When DRAW_FRAMEBUFFER_BINDING is non-zero, an operation that writes 2706 to the framebuffer modifies the image attached to the selected 2707 logical buffer, and an operation that reads from the framebuffer 2708 reads from the image attached to the selected logical buffer. 2709 2710 If the attached image is a renderbuffer image, then the window 2711 coordinates (x[w], y[w]) corresponds to the value in the 2712 renderbuffer image at the same coordinates. 2713 2714 If the attached image is a texture image, then the window 2715 coordinates (x[w], y[w]) correspond to the texel (i, j, k), from 2716 figure 3.10 as follows: 2717 2718 i = (x[w] - b) 2719 2720 j = (y[w] - b) 2721 2722 k = (layer - b) 2723 2724 where <b> is the texture image's border width, and <layer> is the 2725 value of FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER for the selected 2726 logical buffer. For a two-dimensional texture, <k> and <layer> are 2727 irrelevant; for a one-dimensional texture, <j>, <k>, and <layer> are 2728 both irrelevant. 2729 2730 (x[w], y[w]) corresponds to a border texel if x[w], y[w], or 2731 <layer> is less than the border width, or if x[w], y[w], or <layer> 2732 is greater than or equal to the border width plus the width or height or 2733 depth, respectively, of the texture image. 2734 2735 Conversion to Framebuffer-Attachable Image Components 2736 2737 When an enabled color value is written to the framebuffer while the 2738 draw framebuffer binding is non-zero, for each draw buffer the R, G, B, 2739 and A values are converted to internal components as described in 2740 table 3.15, according to the table row corresponding to the internal 2741 format of the framebuffer-attachable image attached to the selected 2742 logical buffer, and the resulting internal components are written to 2743 the image attached to logical buffer. The masking operations 2744 described in section 4.2.2 are also effective. 2745 2746 Conversion to RGBA Values 2747 2748 When a color value is read or is used as the source of a logical 2749 operation or blending while the read framebuffer binding is non-zero, 2750 the components of the framebuffer-attachable image that is attached to 2751 the logical buffer selected by READ_BUFFER are first converted to R, G, 2752 B, and A values according to table 3.21 and the internal format of the 2753 attached image." 2754 2755 2756Additions to Chapter 5 of the OpenGL 2.1 Specification (Special Functions) 2757 2758 Added to section 5.4, as part of the discussion of which commands 2759 are not compiled into display lists: 2760 2761 "Certain commands, when called while compiling a display list, are 2762 not compiled into the display list but are executed immediately. 2763 These are: ..., GenFramebuffers, BindFramebuffer, 2764 DeleteFramebuffers, CheckFramebufferStatus, 2765 GenRenderbuffers, BindRenderbuffer, DeleteRenderbuffers, 2766 RenderbufferStorage, RenderbufferStorageMultisample, 2767 FramebufferTexture1D, FramebufferTexture2D, 2768 FramebufferTexture3D, FramebufferRenderbuffer, BlitFramebuffer, 2769 GenerateMipmap..." 2770 2771 2772Additions to Chapter 6 of the OpenGL 2.1 Specification (State and State 2773Requests) 2774 2775 In section 6.1.3 "Enumerated Queries", modify the seventh paragraph 2776 to say: 2777 2778 "For texture images with uncompressed internal formats, queries of 2779 <value> of TEXTURE_RED_SIZE, TEXTURE_GREEN_SIZE, TEXTURE_BLUE_SIZE, 2780 TEXTURE_ALPHA_SIZE, TEXTURE_LUMINANCE_SIZE, TEXTURE_INTENSITY_SIZE, 2781 TEXTURE_DEPTH_SIZE, and TEXTURE_STENCIL_SIZE return the actual 2782 resolutions of the stored image array components..." 2783 2784 Section 6.1.4 "Texture Queries", in the second paragraph, replace 2785 the first second and third sentences as follows: 2786 2787 "Calling GetTexImage with a color format (one of RED, GREEN, 2788 BLUE, ALPHA, RGB, BGR, RGBA, BGRA, LUMINANCE, or 2789 LUMINANCE_ALPHA) when the internal format of the texture image 2790 is not a color format causes the error INVALID_OPERATION. 2791 2792 Calling GetTexImage with a <format> of DEPTH_COMPONENT when the 2793 base internal format of the texture image is not DEPTH_COMPONENT 2794 or DEPTH_STENCIL causes the error INVALID_OPERATION. 2795 2796 Calling GetTexImage with a <format> of DEPTH_STENCIL when 2797 the base internal format of the texture image is not 2798 DEPTH_STENCIL causes the error INVALID_OPERATION. 2799 2800 GetTexImage obtains component groups from a texture image with 2801 the indicated level-of-detail. If <format> is a color format, 2802 then the components are assigned among R, G, B, and A according 2803 to Table 6.1, starting with the first group in the first row, 2804 and continuing by obtaining groups in order from each row and 2805 proceeding from the first row to the last, and from the first 2806 image to the last for three-dimensional textures. If <format> 2807 is DEPTH_COMPONENT, then each depth component is assigned with 2808 the same ordering of rows and images. If <format> is 2809 DEPTH_STENCIL, then each depth component and each stencil 2810 index is assigned with the same ordering of rows and images." 2811 2812 After section 6.1.14 and before section 6.1.15 (which should be 2813 renumbered 6.1.17), add two new sections: 2814 2815 "6.1.15 Framebuffer Object Queries 2816 2817 The command 2818 2819 boolean IsFramebuffer( uint framebuffer ); 2820 2821 returns TRUE if <framebuffer> is the name of a framebuffer 2822 object. If <framebuffer> is zero, or if <framebuffer> is a 2823 non-zero value that is not the name of a framebuffer object, 2824 IsFramebuffer return FALSE. 2825 2826 The command 2827 2828 void GetFramebufferAttachmentParameteriv(enum target, 2829 enum attachment, 2830 enum pname, 2831 int *params); 2832 2833 returns information about attachments of a bound framebuffer object. 2834 <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER or FRAMEBUFFER. 2835 FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER. 2836 2837 If the default framebuffer is bound to <target>, then <attachment> 2838 must be one of FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, or 2839 AUXi, identifying a color buffer; DEPTH, identifying the depth 2840 buffer; or STENCIL, identifying the stencil buffer. 2841 2842 If a framebuffer object is bound to <target>, then <attachment> must 2843 be one of the attachment points of the framebuffer listed in table 2844 1.nnn. 2845 2846 If <attachment> is DEPTH_STENCIL_ATTACHMENT, and different objects 2847 are bound to the depth and stencil attachment points of <target>, 2848 the query will fail and generate an INVALID_OPERATION error. If the 2849 same object is bound to both attachment points, information about 2850 that object will be returned. 2851 2852 Upon successful return from GetFramebufferAttachmentParameteriv, if 2853 <pname> is FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE, then <param> will 2854 contain one of NONE, FRAMEBUFFER_DEFAULT, TEXTURE, or RENDERBUFFER, 2855 identifying the type of object which contains the attached image. 2856 Other values accepted for <pname> depend on the type of object, as 2857 described below. 2858 2859 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is 2860 NONE, no framebuffer is bound to <target>. In this case 2861 querying <pname> FRAMEBUFFER_ATTACHMENT_OBJECT_NAME 2862 will return zero, and all other queries will generate an 2863 INVALID_OPERATION error. 2864 2865 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is not 2866 NONE, these queries apply to all other framebuffer types: 2867 2868 * If <pname> is FRAMEBUFFER_ATTACHMENT_RED_SIZE, 2869 FRAMEBUFFER_ATTACHMENT_GREEN_SIZE, 2870 FRAMEBUFFER_ATTACHMENT_BLUE_SIZE, 2871 FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE, 2872 FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE, or 2873 FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE, then <param> will contain 2874 the number of bits in the corresponding red, green, blue, alpha, 2875 depth, or stencil component of the specified <attachment>. Zero 2876 is returned if the requested component is not present in 2877 <attachment>. 2878 2879 * If <pname> is FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE, <param> 2880 will contain the format of components of the specified 2881 attachment, one of FLOAT, INT, UNSIGNED_INT, UNSIGNED_NORMALIZED 2882 or INDEX for floating-point, signed integer, unsigned integer, 2883 unsigned fixed-point, or index components respectively. Only 2884 color buffers may have index or integer components. 2885 2886 * If <pname> is FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING, <param> 2887 will contain the encoding of components of the specified 2888 attachment, one of LINEAR or SRGB for linear or sRGB-encoded 2889 components, respectively. Only color buffer components may be 2890 sRGB-encoded; such components are treated as described in 2891 sections 4.1.8 "Blending" and 4.1.X "sRGB Conversion" (as 2892 modified by ARB_framebuffer_sRGB). For the default framebuffer, 2893 color encoding is determined by the implementation. For 2894 framebuffer objects, components are sRGB-encoded if the internal 2895 format of a color attachment is one of the color-renderable SRGB 2896 formats described in section 3.8.15 "sRGB Texture Color 2897 Conversion". 2898 2899 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is RENDERBUFFER, 2900 then 2901 2902 * If <pname> is FRAMEBUFFER_ATTACHMENT_OBJECT_NAME, <params> will 2903 contain the name of the renderbuffer object which contains the 2904 attached image. 2905 2906 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is TEXTURE, then 2907 2908 * If <pname> is FRAMEBUFFER_ATTACHMENT_OBJECT_NAME, then <params> 2909 will contain the name of the texture object which contains the 2910 attached image. 2911 2912 * If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL, then 2913 <params> will contain the mipmap level of the texture object 2914 which contains the attached image. 2915 2916 * If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE and 2917 the texture object named FRAMEBUFFER_ATTACHMENT_OBJECT_NAME is a 2918 cube map texture, then <params> will contain the cube map face 2919 of the cubemap texture object which contains the attached image. 2920 Otherwise <params> will contain the value zero. 2921 2922 * If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER and the 2923 texture object named FRAMEBUFFER_ATTACHMENT_OBJECT_NAME is a 2924 three-dimensional texture, then <params> will contain the layer 2925 of the 2D image of the 3D texture object which contains the 2926 attached image. Otherwise <params> will contain the value zero. 2927 2928 Any combinations of framebuffer type and <pname> not described above 2929 will generate an INVALID_ENUM error." 2930 2931 2932 6.1.16 Renderbuffer Object Queries 2933 2934 "The command 2935 2936 boolean IsRenderbuffer( uint renderbuffer ); 2937 2938 returns TRUE if <renderbuffer> is the name of a renderbuffer 2939 object. If <renderbuffer> is zero, or if <renderbuffer> is a 2940 non-zero value that is not the name of a renderbuffer object, 2941 IsRenderbuffer return FALSE. 2942 2943 The command 2944 2945 void GetRenderbufferParameteriv(enum target, enum pname, 2946 int* params); 2947 2948 returns information about a bound renderbuffer object. <target> must 2949 be RENDERBUFFER and <pname> must be one of the symbolic values in 2950 table 8.nnn. If the renderbuffer currently bound to <target> is 2951 zero, then an INVALID_OPERATION error is generated. 2952 2953 Upon successful return from GetRenderbufferParameteriv, if <pname> 2954 is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT, 2955 RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES, then <params> 2956 will contain the width in pixels, height in pixels, internal format, 2957 or number of samples, respectively, of the image of the renderbuffer 2958 currently bound to <target>. 2959 2960 If <pname> is RENDERBUFFER_RED_SIZE, RENDERBUFFER_GREEN_SIZE, 2961 RENDERBUFFER_BLUE_SIZE, RENDERBUFFER_ALPHA_SIZE, 2962 RENDERBUFFER_DEPTH_SIZE, or RENDERBUFFER_STENCIL_SIZE, then <params> 2963 will contain the actual resolutions, (not the resolutions specified 2964 when the image array was defined), for the red, green, blue, alpha 2965 depth, or stencil components, respectively, of the image of the 2966 renderbuffer currently bound to <target>. 2967 2968 Otherwise, an INVALID_ENUM error is generated." 2969 2970 In section 6.2 "State Tables", add a row to table 6.18 "Textures 2971 (state per texture image)": 2972 2973 Get value Type Get Cmd IV Description Sec. 2974 ------------------ ------ -------------------- --- ---------------------------------- ----- 2975 ... ... ... ... ... ... 2976 TEXTURE_STENCIL_SIZE n x Z+ GetTexLevelParameter 0 texture image's stencil resolution 3.8.3 2977 2978 2979Errors 2980 2981 The error INVALID_OPERATION is generated if DRAW_FRAMEBUFFER_BINDING 2982 is zero and DrawBuffer or DrawBuffers is called with a <buf> 2983 constant (other than NONE) that does not correspond to a buffer 2984 allocated to the GL by the window-system, including the constants 2985 COLOR_ATTACHMENT0 through COLOR_ATTACHMENTn, where n is 2986 MAX_COLOR_ATTACHMENTS - 1. 2987 2988 The error INVALID_OPERATION is generated if DRAW_FRAMEBUFFER_BINDING 2989 is non-zero and DrawBuffer or DrawBuffer is called 2990 with a <buf> constant (other than NONE) that is not in the range 2991 COLOR_ATTACHMENT0 through COLOR_ATTACHMENTn, where n is 2992 MAX_COLOR_ATTACHMENTS - 1. 2993 2994 The error INVALID_OPERATION is generated if READ_FRAMEBUFFER_BINDING 2995 is non-zero and ReadBuffer is called 2996 with a <buf> constant (other than NONE) that is not in the range 2997 COLOR_ATTACHMENT0 through COLOR_ATTACHMENTn, where n is 2998 MAX_COLOR_ATTACHMENTS - 1. 2999 3000 The error INVALID_ENUM is generated if DrawBuffer or ReadBuffer is 3001 called with a <buf> constant that is not listed in table 4.4 or 3002 10.nnn. 3003 3004 The error INVALID_ENUM is generated if DrawBuffers is called with a 3005 <buf> constant that is not listed in table 10.nnn or 11.nnn. 3006 3007 The error INVALID_FRAMEBUFFER_OPERATION is generated if 3008 BlitFramebuffer, DrawPixels, or CopyPixels is called while the 3009 draw framebuffer is not framebuffer complete. 3010 3011 The error INVALID_FRAMEBUFFER_OPERATION is generated if 3012 BlitFramebuffer, ReadPixels, CopyPixels, CopyTex{Sub}Image*, 3013 CopyColor{Sub}Table, or CopyConvolutionFilter* is called while the 3014 read framebuffer is not framebuffer complete. 3015 3016 The error INVALID_OPERATION is generated if 3017 GetFramebufferAttachmentParameteriv is called while the value of 3018 DRAW_FRAMEBUFFER_BINDING is zero. 3019 3020 The error INVALID_OPERATION is generated if 3021 FramebufferRenderbuffer or FramebufferTexture{1D|2D|3D} is 3022 called while the value of DRAW_FRAMEBUFFER_BINDING is zero. 3023 3024 The error INVALID_OPERATION is generated if RenderbufferStorage 3025 or GetRenderbufferParameteriv is called while the value of 3026 RENDERBUFFER_BINDING is zero. 3027 3028 The error INVALID_ENUM is generated if 3029 GetFramebufferAttachmentParameteriv is called with an 3030 <attachment> other than COLOR_ATTACHMENT0 through 3031 COLOR_ATTACHMENTn, where n is MAX_COLOR_ATTACHMENTS - 1. 3032 3033 The error INVALID_ENUM is generated if 3034 GetFramebufferAttachmentParameteriv is called with a <pname> 3035 other than FRAMEBUFFER_ATTACHMENT_OBJECT_NAME when the type of 3036 the attached object at the named attachment point is 3037 RENDERBUFFER. 3038 3039 The error INVALID_ENUM is generated if 3040 GetFramebufferAttachmentParameteriv is called with a <pname> 3041 other than FRAMEBUFFER_ATTACHMENT_OBJECT_NAME, 3042 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL, 3043 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE, or 3044 FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER when the type of the 3045 attached object at the named attachment point is TEXTURE. 3046 3047 The error INVALID_ENUM is generated if GetRenderbufferParameteriv 3048 is called with a <pname> other than RENDERBUFFER_WIDTH, 3049 RENDERBUFFER_HEIGHT, or RENDERBUFFER_INTERNAL_FORMAT, 3050 RENDERBUFFER_RED_SIZE, RENDERBUFFER_GREEN_SIZE, 3051 RENDERBUFFER_BLUE_SIZE, RENDERBUFFER_ALPHA_SIZE, 3052 RENDERBUFFER_DEPTH_SIZE, or RENDERBUFFER_STENCIL_SIZE. 3053 3054 The error INVALID_VALUE is generated if RenderbufferStorage is 3055 called with a <width> or <height> that is greater than 3056 MAX_RENDERBUFFER_SIZE. 3057 3058 The error INVALID_ENUM is generated if RenderbufferStorage is 3059 called with an <internalformat> that is not RGB, RGBA, 3060 DEPTH_COMPONENT, STENCIL_INDEX, DEPTH_STENCIL, or one of the 3061 internal formats from table 3.16 or table 2.nnn that has a base 3062 internal format of RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, r 3063 DEPTH_STENCIL. 3064 3065 The error INVALID_OPERATION is generated if 3066 FramebufferRenderbuffer is called and <renderbuffer> is not the 3067 name of a renderbuffer object. 3068 3069 The error INVALID_OPERATION is generated if 3070 FramebufferTexture{1D|2D|3D} is called and <texture> is not the 3071 name of a texture object. 3072 3073 The error INVALID_VALUE is generated if 3074 FramebufferTexture{1D|2D|3D} is called with a <level> that is 3075 less than zero. 3076 3077 The error INVALID_VALUE is generated if FramebufferTexture2D is 3078 called with a <level> that is not zero and <textarget> is 3079 TEXTURE_RECTANGLE_ARB. 3080 3081 The error INVALID_VALUE is generated if FramebufferTexture{1D|2D} 3082 is called with a <level> that is greater than the log base 2 of 3083 MAX_TEXTURE_SIZE and <texture> is a 1D or 2D texture. 3084 3085 The error INVALID_VALUE is generated if FramebufferTexture2D 3086 is called with a <level> that is greater than the log base 2 of 3087 MAX_CUBE_MAP_TEXTURE_SIZE and <texture> is a cubemap texture. 3088 3089 The error INVALID_VALUE is generated if FramebufferTexture3D is 3090 called with a <level> greater than the log base 2 of the 3091 MAX_3D_TEXTURE_SIZE. 3092 3093 The error INVALID_VALUE is generated if FramebufferTexture3D is 3094 called with a <layer> that is larger than MAX_3D_TEXTURE_SIZE-1. 3095 3096 The error INVALID_VALUE is generated by BlitFramebuffer if 3097 <mask> has any bits set other than those named by 3098 COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT. 3099 3100 The error INVALID_OPERATION is generated if BlitFramebuffer is 3101 called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT 3102 and <filter> is not NEAREST. 3103 3104 The error INVALID_OPERATION is generated if BlitFramebuffer is 3105 called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT 3106 and the source and destination depth or stencil buffer formats do 3107 not match. 3108 3109 The error INVALID_ENUM is generated by BlitFramebuffer if 3110 <filter> is not LINEAR or NEAREST. 3111 3112 The error INVALID_OPERATION is generated if BlitFramebuffer 3113 is called within a Begin/End pair. 3114 3115 The error INVALID_ENUM is generated if BindFramebuffer, 3116 CheckFramebufferStatus, FramebufferTexture{1D|2D|3D}, 3117 FramebufferRenderbuffer, or 3118 GetFramebufferAttachmentParameteriv is called and <target> is 3119 not DRAW_FRAMEBUFFER, READ_FRAMEBUFFER or FRAMEBUFFER. 3120 3121 The error INVALID_OPERATION is generated if 3122 CheckFramebufferStatus is called within a Begin/End pair. 3123 3124 The error OUT_OF_MEMORY is generated if the GL is unable to create a 3125 data store of the required size when calling RenderbufferStorage. 3126 3127 The error INVALID_OPERATION is generated if GenerateMipmap is 3128 called with a <target> of TEXTURE_CUBE_MAP and the texture object 3129 currently bound to TEXTURE_CUBE_MAP is not "cube complete" as 3130 defined in section 3.8.10 3131 3132 The error INVALID_OPERATION is generated if ReadPixels, 3133 CopyPixels, CopyTex{Sub}Image*, CopyColor{Sub}Table, or 3134 CopyConvolutionFilter* is called while READ_FRAMEBUFFER_BINDING 3135 is non-zero, the read framebuffer is framebuffer complete, and the 3136 value of SAMPLE_BUFFERS for the read framebuffer is greater than 3137 zero. 3138 3139 The error OUT_OF_MEMORY is generated when 3140 RenderbufferStorageMultisample cannot create storage of the 3141 specified size. 3142 3143 If both the draw and read framebuffers are framebuffer complete and 3144 both have a value of SAMPLE_BUFFERS that is greater than zero, then 3145 the error INVALID_OPERATION is generated if BlitFramebuffer is 3146 called and the values of SAMPLES for the draw and read framebuffers 3147 do not match. 3148 3149 If both the draw and read framebuffers are framebuffer complete and 3150 either has a value of SAMPLE_BUFFERS that is greater than zero, then 3151 the error INVALID_OPERATION is generated if BlitFramebuffer is 3152 called and the formats of the draw and read framebuffers are not 3153 identical. 3154 3155 If either the draw or read framebuffer is framebuffer complete and 3156 has a value of SAMPLE_BUFFERS that is greater than zero, then the 3157 error INVALID_OPERATION is generated if BlitFramebuffer is called 3158 and the specified source and destination dimensions are not 3159 identical. 3160 3161 If RenderbufferStorageMultisample is called with a value of 3162 <samples> that is greater than MAX_SAMPLES, then the error 3163 INVALID_VALUE is generated. 3164 3165 The error INVALID_ENUM is generated if DrawPixels or ReadPixels is 3166 called where format is DEPTH_STENCIL and type is not 3167 UNSIGNED_INT_24_8. 3168 3169 The error INVALID_OPERATION is generated if DrawPixels or ReadPixels 3170 is called where type is UNSIGNED_INT_24_8 and format is not 3171 DEPTH_STENCIL. 3172 3173 The error INVALID_OPERATION is generated if DrawPixels or ReadPixels 3174 is called where format is DEPTH_STENCIL and there is not both a 3175 depth buffer and a stencil buffer. 3176 3177 The error INVALID_OPERATION is generated if CopyPixels is called 3178 where type is DEPTH_STENCIL and there is not both a depth buffer 3179 and a stencil buffer. 3180 3181 3182New State 3183 3184 (add new table 3.nnn, "Framebuffer (state per framebuffer target binding point)") 3185 3186 Get Value Type Get Command Initial Value Description Section Attribute 3187 ------------------------ ---- ----------- -------------- ------------------- ------------ --------- 3188 DRAW_FRAMEBUFFER_BINDING Z+ GetIntegerv 0 Framebuffer object bound 4.4.1 - 3189 to DRAW_FRAMEBUFFER 3190 READ_FRAMEBUFFER_BINDING Z+ GetIntegerv 0 Framebuffer object 4.4.1 - 3191 to READ_FRAMEBUFFER 3192 3193 (insert new table 4.nnn, "Framebuffer (state per framebuffer object)") 3194 3195 Get Value Type Get Command Initial Value Description Section Attribute 3196 ---------------- ------ ------------- ------------- -------------------- ------------ --------- 3197 DRAW_BUFFERi [1] 1 + xZ(10*) GetIntegerv see 4.2.1 Draw buffer selected 4.2.1 color-buffer 3198 for color output i 3199 READ_BUFFER [2] Z(3) GetIntegerv see 4.3.2 Read source buffer 4.3.2 pixel 3200 3201 [1] prior to this extension, the DRAW_BUFFERi state was 3202 described in table 6.21 "Framebuffer Control" of the OpenGL 3203 2.0 specification. 3204 [2] prior to this extension, the READ_BUFFER state was described 3205 in table 6.26 "Pixel" of the OpenGL 2.0 specification. 3206 3207 3208 3209 (insert new table 5.nnn, "Framebuffer (state per framebuffer object attachment point)") 3210 3211 Get Value Type Get Command Initial Value Description Section Attribute 3212 -------------------------------------------- ---- -------------------------------------- ------------- -------------------- ------------ --------- 3213 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE Z GetFramebufferAttachmentParameteriv NONE type of 4.4.2.2 and - 3214 image attached to 4.4.2.3 3215 framebuffer attachment 3216 point 3217 3218 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME Z GetFramebufferAttachmentParameteriv 0 name of object 4.4.2.2 and - 3219 attached to 4.4.2.3 3220 framebuffer attachment 3221 point 3222 3223 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL Z GetFramebufferAttachmentParameteriv 0 mipmap level of 4.4.2.2 and - 3224 texture image 4.4.2.3 3225 attached, if object 3226 attached is texture. 3227 3228 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE Z+ GetFramebufferAttachmentParameteriv NONE cubemap face of 4.4.2.2 and - 3229 texture image 4.4.2.3 3230 attached, if object 3231 attached is cubemap 3232 texture. 3233 3234 FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER Z GetFramebufferAttachmentParameteriv 0 layer of 4.4.2.2 and - 3235 texture image 4.4.2.3 3236 attached, if object 3237 attached is 3D texture. 3238 3239 FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING Z_2 GetFramebufferAttachmentParameteriv - Encoding of components 6.1.3 - 3240 in the attached image 3241 3242 FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE Z_4 GetFramebufferAttachmentParameteriv - Data type of components 6.1.3 - 3243 in the attached image 3244 3245 FRAMEBUFFER_ATTACHMENT_RED_SIZE Z+ GetFramebufferAttachmentParameteriv - Size in bits of att. 6.1.3 - 3246 image's red component 3247 3248 FRAMEBUFFER_ATTACHMENT_GREEN_SIZE Z+ GetFramebufferAttachmentParameteriv - Size in bits of att. 6.1.3 - 3249 image's green component 3250 3251 FRAMEBUFFER_ATTACHMENT_BLUE_SIZE Z+ GetFramebufferAttachmentParameteriv - Size in bits of att. 6.1.3 - 3252 image's blue component 3253 3254 FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE Z+ GetFramebufferAttachmentParameteriv - Size in bits of att. 6.1.3 - 3255 image's alpha component 3256 3257 FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE Z+ GetFramebufferAttachmentParameteriv - Size in bits of att. 6.1.3 - 3258 image's depth component 3259 3260 FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE Z+ GetFramebufferAttachmentParameteriv - Size in bits of att. 6.1.3 - 3261 image's stencil component 3262 3263 3264 3265 3266 (insert new table 7.nnn, "Renderbuffers (state per renderbuffer target and binding point)") 3267 3268 Get Value Type Get Command Initial Value Description Section Attribute 3269 ---------------------------- ------ ------------- ------------- -------------------- ------------ --------- 3270 RENDERBUFFER_BINDING Z GetIntegerv 0 renderbuffer object 4.4.2.1 - 3271 bound to RENDERBUFFER 3272 3273 3274 (insert new table 8.nnn, "Renderbuffers (state per renderbuffer object)") 3275 3276 Get Value Type Get Command Initial Value Description Section Attribute 3277 ---------------------------- ------ ------------- ------------- -------------------- ------------ --------- 3278 RENDERBUFFER_WIDTH Z GetRenderbufferParameteriv 0 width of renderbuffer 4.4.2.1 - 3279 3280 RENDERBUFFER_HEIGHT Z GetRenderbufferParameteriv 0 height of renderbuffer 4.4.2.1 - 3281 3282 RENDERBUFFER_INTERNAL_FORMAT Z+ GetRenderbufferParameteriv RGBA internal format 4.4.2.1 - 3283 of renderbuffer 3284 3285 RENDERBUFFER_RED_SIZE Z GetRenderbufferParameteriv 0 size in bits of 4.4.2.1 - 3286 renderbuffer image's 3287 red component 3288 3289 RENDERBUFFER_GREEN_SIZE Z GetRenderbufferParameteriv 0 size in bits of 4.4.2.1 - 3290 renderbuffer image's 3291 green component 3292 3293 RENDERBUFFER_BLUE_SIZE Z GetRenderbufferParameteriv 0 size in bits of 4.4.2.1 - 3294 renderbuffer image's 3295 blue component 3296 3297 RENDERBUFFER_ALPHA_SIZE Z GetRenderbufferParameteriv 0 size in bits of 4.4.2.1 - 3298 renderbuffer image's 3299 alpha component 3300 3301 RENDERBUFFER_DEPTH_SIZE Z GetRenderbufferParameteriv 0 size in bits of 4.4.2.1 - 3302 renderbuffer image's 3303 depth component 3304 3305 RENDERBUFFER_STENCIL_SIZE Z GetRenderbufferParameteriv 0 size in bits of 4.4.2.1 - 3306 renderbuffer image's 3307 stencil component 3308 3309 RENDERBUFFER_SAMPLES Z+ GetRenderbufferParameteriv 0 number of samples 4.4.2.1 - 3310 3311 3312 3313 3314 3315Move the following existing state from "Implementation Dependent 3316Values", tables 6.33-6.37 to into a new table called "Framebuffer 3317Dependent Values", table 9.nnn. 3318 3319 Get Value 3320 --------- 3321 AUX_BUFFERS 3322 MAX_DRAW_BUFFERS 3323 RGBA_MODE 3324 INDEX_MODE 3325 DOUBLEBUFFER 3326 STEREO 3327 SAMPLE_BUFFERS 3328 SAMPLES 3329 RED_BITS 3330 GREEN_BITS 3331 BLUE_BITS 3332 ALPHA_BITS 3333 INDEX_BITS 3334 DEPTH_BITS 3335 STENCIL_BITS 3336 ACCUM_RED_BITS 3337 ACCUM_GREEN_BITS 3338 ACCUM_BLUE_BITS 3339 ACCUM_ALPHA_BITS 3340 3341To the same table called "Framebuffer Dependent Values", table 9.nnn 3342add the following new framebuffer dependent state. 3343 3344 Get Value Type Get Command Minimum Value Description Section Attribute 3345 --------- ---- ----------- ------------- ------------------- ------- --------- 3346 MAX_COLOR_ATTACHMENTS Z+ GetIntegerv 1 Maximum number of 4.4.2.2 - 3347 attachment points 3348 for color buffers 3349 when using framebuffer 3350 objects 3351 3352 MAX_SAMPLES Z+ GetIntegerv 0 Maximum number of 4.4.2.1 - 3353 samples supported 3354 for multisampling 3355 3356New Implementation Dependent State 3357 3358 Get Value Type Get Command Minimum Value Description Section Attribute 3359 --------- ---- ----------- ------------- ------------------- ------- --------- 3360 MAX_RENDERBUFFER_SIZE Z+ GetIntegerv 64 Maximum width and 4.4.2.1 - 3361 height of 3362 renderbuffers 3363 supported by 3364 the implementation 3365 3366Additions to the AGL/GLX/WGL Specifications and dependencies on 3367WGL_ARB_make_current_read, GLX_SGI_make_current_read, and GLX 1.3 3368 3369 The color, depth, stencil, aux, and accum logical buffers defined by 3370 the <draw> and <read> drawables passed to glXMakeContextCurrent, 3371 glXMakeCurrent, and glXMakeCurrentRead are ignored while the value 3372 of DRAW_FRAMEBUFFER_BINDING is non-zero. 3373 3374Dependencies on ATI_draw_buffers and ARB_draw_buffers 3375 3376 If neither ATI_draw_buffers nor ARB_draw_buffers are supported, then 3377 all discussions of DrawBuffers should be ignored. 3378 3379 In addition, the language describing DrawBuffers are derived from a 3380 combination of the ARB_draw_buffers specification and section 4.2.1 3381 of the OpenGL 2.0 specification. 3382 3383Dependencies on ARB_fragment_program, ARB_fragment_shader, and 3384ARB_vertex_shader 3385 3386 If ARB_fragment_program, ARB_fragment_shader, and ARB_vertex_shader 3387 are all not supported, then all references to the currently bound 3388 program or shader should be ignored. 3389 3390Dependencies on ARB_texture_rectangle 3391 3392 If ARB_texture_rectangle is not supported, then all references to 3393 TEXTURE_RECTANGLE_ARB should be ignored. 3394 3395Dependencies on ARB_color_buffer_float 3396 3397 The reference to CLAMP_FRAGMENT_COLOR_ARB in section 4.3.3 applies 3398 only if ARB_color_buffer_float is supported. 3399 3400Dependencies on ARB_texture_rg 3401 3402 If ARB_texture_rg is not supported, delete the references to RED and 3403 RG from the list of color-renderable base internal formats from 3404 section 4.4.4. 3405 3406Dependencies on NV_float_buffer 3407 3408 If NV_float_buffer is not supported, delete the references to 3409 FLOAT_R_NV, FLOAT_RG_NV, FLOAT_RGB_NV and FLOAT_RGBA_NV from the list 3410 of color-renderable base internal formats from section 4.4.4 3411 3412Dependencies on EXT_framebuffer_object 3413 3414 Framebuffer objects created with the commands defined by the 3415 GL_EXT_framebuffer_object extension are defined to be shared, while 3416 FBOs created with commands defined by the OpenGL core or 3417 GL_ARB_framebuffer_object extension are defined *not* to be shared. 3418 However, the following functions are viewed as aliases (in particular 3419 the opcodes for X are also the same) between the functions of 3420 GL_EXT_framebuffer_object and GL_ARB_framebuffer_object: 3421 3422 IsRenderbufferEXT / IsRenderbuffer 3423 DeleteRenderbuffersEXT / DeleteRenderbuffers 3424 GenRenderbuffersEXT / GenRenderbuffers 3425 RenderbufferStorageEXT / RenderbufferStorage 3426 GetRenderbufferParameterivEXT / GetRenderbufferParameteriv 3427 IsFramebufferEXT / IsFramebuffer 3428 DeleteFramebuffersEXT / DeleteFramebuffers 3429 GenFramebuffersEXT / GenFramebuffers 3430 CheckFramebufferStatusEXT / CheckFramebufferStatus 3431 FramebufferTexture1DEXT / FramebufferTexture1D 3432 FramebufferTexture2DEXT / FramebufferTexture2D 3433 FramebufferRenderbufferEXT / FramebufferRenderbuffer 3434 GenerateMipmapEXT / GenerateMipmap 3435 GetFramebufferAttachmentParameterivEXT / GetFramebufferAttachmentParameteriv 3436 3437 Since the above pairs are aliases, the functions of a pair are 3438 equivalent. Note that the functions BindFramebuffer and 3439 BindFramebufferEXT are not aliases and neither are the functions 3440 BindRenderbuffer and BindRenderbufferEXT. Because object creation 3441 occurs when the framebuffer object is bound for the first time, a 3442 framebuffer object can be shared across contexts only if it was first 3443 bound with BindFramebufferEXT. Framebuffers first bound with 3444 BindFramebuffer may not be shared across contexts. Framebuffer 3445 objects created with BindFramebufferEXT may subsequently be bound 3446 using BindFramebuffer. Framebuffer objects created with 3447 BindFramebuffer may be bound with BindFramebufferEXT provided they are 3448 bound to the same context they were created on. 3449 3450Dependencies on EXT_texture_array 3451 3452 If EXT_texture_array is not supported, delete all references to 3453 one- and two-dimensional array textures. 3454 3455Dependencies on EXT_texture_integer 3456 3457 If EXT_texture_integer is not supported, the following changes should 3458 be made: 3459 3460 The definition of GetFramebufferAttachmentParameteriv should be 3461 modified to remove any references to signed and unsigned integer 3462 components for color buffers and the values of INT and UNSIGNED_INT 3463 should be removed from the list of possible values for <param> when 3464 <pname> is FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE. 3465 3466Dependencies on ARB_framebuffer_sRGB 3467 3468 If ARB_framebuffer_sRGB is not supported, the following changes should 3469 be made: 3470 3471 The definition of GetFramebufferAttachmentParameteriv should be 3472 modified to remove any reference to sRGB-encoded components or 3473 color buffers and sRGB conversion. The value of SRGB should be 3474 removed from the list of possible values for <param> when <pname> is 3475 FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING. 3476 3477GLX Protocol 3478 3479 Nineteen new GL commands are added. 3480 3481 The following thirteen rendering commands are sent to the server 3482 as part of a glXRender request: 3483 3484 BindRenderbuffer 3485 2 12 rendering command length 3486 2 235 rendering command opcode 3487 4 ENUM target 3488 4 CARD32 renderbuffer 3489 3490 DeleteRenderbuffer 3491 2 8+n*4 rendering command length 3492 2 4317 rendering command opcode 3493 4 CARD32 n 3494 n*4 LISTofCARD32 renderbuffers 3495 3496 RenderbufferStorage 3497 2 20 rendering command length 3498 2 4318 rendering command opcode 3499 4 ENUM target 3500 4 ENUM internalFormat 3501 4 CARD32 width 3502 4 CARD32 height 3503 3504 RenderbufferStorageMultisample 3505 3506 2 24 rendering command length 3507 2 4331 rendering command opcode 3508 4 ENUM target 3509 4 CARD32 samples 3510 4 ENUM internalformat 3511 4 CARD32 width 3512 4 CARD32 height 3513 3514 BindFramebuffer 3515 2 12 rendering command length 3516 2 236 rendering command opcode 3517 4 ENUM target 3518 4 CARD32 framebuffer 3519 3520 DeleteFramebuffer 3521 2 8+n*4 rendering command length 3522 2 4320 rendering command opcode 3523 4 CARD32 n 3524 n*4 LISTofCARD32 framebuffers 3525 3526 FramebufferTexture1D 3527 2 24 rendering command length 3528 2 4321 rendering command opcode 3529 4 ENUM target 3530 4 ENUM attachment 3531 4 ENUM textarget 3532 4 CARD32 texture 3533 4 CARD32 level 3534 3535 FramebufferTexture2D 3536 2 24 rendering command length 3537 2 4322 rendering command opcode 3538 4 ENUM target 3539 4 ENUM attachment 3540 4 ENUM textarget 3541 4 CARD32 texture 3542 4 CARD32 level 3543 3544 FramebufferTexture3D 3545 2 28 rendering command length 3546 2 4323 rendering command opcode 3547 4 ENUM target 3548 4 ENUM attachment 3549 4 ENUM textarget 3550 4 CARD32 texture 3551 4 CARD32 level 3552 4 CARD32 layer 3553 3554 FramebufferTextureLayer 3555 2 24 rendering command length 3556 2 237 rendering command opcode 3557 4 ENUM target 3558 4 ENUM attachment 3559 4 CARD32 texture 3560 4 CARD32 level 3561 4 CARD32 layer 3562 3563 FramebufferRenderbuffer 3564 2 20 rendering command length 3565 2 4324 rendering command opcode 3566 4 ENUM target 3567 4 ENUM attachment 3568 4 ENUM renderbuffertarget 3569 4 CARD32 renderbuffer 3570 3571 BlitFramebuffer 3572 2 44 rendering command length 3573 2 4330 rendering command opcode 3574 4 CARD32 source X0 3575 4 CARD32 source Y0 3576 4 CARD32 source X1 3577 4 CARD32 source Y1 3578 4 CARD32 destination X0 3579 4 CARD32 destination Y0 3580 4 CARD32 destination X1 3581 4 CARD32 destination Y1 3582 4 CARD32 mask 3583 4 ENUM filter 3584 3585 GenerateMipmap 3586 2 8 rendering command length 3587 2 4325 rendering command opcode 3588 4 ENUM target 3589 3590 The remaining seven commands are non-rendering commands. These 3591 commands are sent separately (i.e., not as part of a glXRender or 3592 glXRenderLarge request), using the glXVendorPrivateWithReply 3593 request: 3594 3595 IsRenderbuffer 3596 1 CARD8 opcode (X assigned) 3597 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3598 2 4 request length 3599 4 1422 vendor specific opcode 3600 4 GLX_CONTEXT_TAG context tag 3601 4 CARD32 renderbuffer 3602 => 3603 1 1 reply 3604 1 unused 3605 2 CARD16 sequence number 3606 4 0 reply length 3607 4 BOOL32 return value 3608 20 unused 3609 3610 GenRenderbuffers 3611 1 CARD8 opcode (X assigned) 3612 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3613 2 4 request length 3614 4 1423 vendor specific opcode 3615 4 GLX_CONTEXT_TAG context tag 3616 4 CARD32 n 3617 => 3618 1 1 reply 3619 1 unused 3620 2 CARD16 sequence number 3621 4 m reply length 3622 4 unused 3623 4 CARD32 n 3624 16 unused 3625 n*4 LISTofCARD32 renderbuffers 3626 3627 GetRenderbufferParameteriv 3628 1 CARD8 opcode (X assigned) 3629 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3630 2 5 request length 3631 4 1424 vendor specific opcode 3632 4 GLX_CONTEXT_TAG context tag 3633 4 ENUM target 3634 4 ENUM pname 3635 => 3636 1 1 reply 3637 1 unused 3638 2 CARD16 sequence number 3639 4 m reply length, m = (n == 1 ? 0 : n) 3640 4 unused 3641 4 CARD32 n 3642 3643 if (n = 1) this follows: 3644 3645 4 CARD32 params 3646 12 unused 3647 3648 otherwise this follows: 3649 3650 16 unused 3651 n*4 LISTofCARD32 params 3652 3653 IsFramebuffer 3654 1 CARD8 opcode (X assigned) 3655 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3656 2 4 request length 3657 4 1425 vendor specific opcode 3658 4 GLX_CONTEXT_TAG context tag 3659 4 CARD32 framebuffer 3660 => 3661 1 1 reply 3662 1 unused 3663 2 CARD16 sequence number 3664 4 0 reply length 3665 4 BOOL32 return value 3666 20 unused 3667 3668 GenFramebuffers 3669 1 CARD8 opcode (X assigned) 3670 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3671 2 4 request length 3672 4 1426 vendor specific opcode 3673 4 GLX_CONTEXT_TAG context tag 3674 4 CARD32 n 3675 => 3676 1 1 reply 3677 1 unused 3678 2 CARD16 sequence number 3679 4 n reply length 3680 4 unused 3681 4 CARD32 n 3682 16 unused 3683 n*4 LISTofCARD32 framebuffers 3684 3685 CheckFramebufferStatus 3686 1 CARD8 opcode (X assigned) 3687 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3688 2 4 request length 3689 4 1427 vendor specific opcode 3690 4 GLX_CONTEXT_TAG context tag 3691 4 ENUM target 3692 => 3693 1 1 reply 3694 1 unused 3695 2 CARD16 sequence number 3696 4 0 reply length 3697 4 ENUM return value 3698 20 unused 3699 3700 GetFramebufferAttachmentParameteriv 3701 1 CARD8 opcode (X assigned) 3702 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 3703 2 6 request length 3704 4 1428 vendor specific opcode 3705 4 GLX_CONTEXT_TAG context tag 3706 4 ENUM target 3707 4 ENUM attachment 3708 4 ENUM pname 3709 => 3710 1 1 reply 3711 1 unused 3712 2 CARD16 sequence number 3713 4 m reply length, m = (n == 1 ? 0 : n) 3714 4 unused 3715 4 CARD32 n 3716 3717 if (n = 1) this follows: 3718 3719 4 CARD32 params 3720 12 unused 3721 3722 otherwise this follows: 3723 3724 16 unused 3725 n*4 LISTofCARD32 params 3726 3727 3728Usage Examples 3729 3730 The following examples use a helper macro for 3731 CHECK_FRAMEBUFFER_STATUS, defined below. 3732 3733 Example (6) gives a (very slightly) more robust example of handling 3734 the possible return values for glCheckFramebufferStatus. 3735 3736 #define CHECK_FRAMEBUFFER_STATUS() \ 3737 { \ 3738 GLenum status; \ 3739 status = glCheckFramebufferStatus(GL_DRAW_FRAMEBUFFER); \ 3740 switch(status) { \ 3741 case GL_FRAMEBUFFER_COMPLETE: \ 3742 break; \ 3743 case GL_FRAMEBUFFER_UNSUPPORTED: \ 3744 /* choose different formats */ \ 3745 break; \ 3746 default: \ 3747 /* programming error; will fail on all hardware */ \ 3748 assert(0); \ 3749 } 3750 } 3751 3752 (1) Render to 2D texture with a depth buffer 3753 3754 // Given: color_tex - TEXTURE_2D color texture object 3755 // depth_rb - GL_DEPTH renderbuffer object 3756 // fb - framebuffer object 3757 3758 // Enable render-to-texture 3759 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 3760 3761 // Set up color_tex and depth_rb for render-to-texture 3762 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3763 GL_COLOR_ATTACHMENT0, 3764 GL_TEXTURE_2D, color_tex, 0); 3765 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3766 GL_DEPTH_ATTACHMENT, 3767 GL_RENDERBUFFER, depth_rb); 3768 3769 // Check framebuffer completeness at the end of initialization. 3770 CHECK_FRAMEBUFFER_STATUS(); 3771 3772 <draw to the texture and renderbuffer> 3773 3774 // Re-enable rendering to the window 3775 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 3776 3777 glBindTexture(GL_TEXTURE_2D, color_tex); 3778 <draw to the window, reading from the color_tex> 3779 3780 3781 (2) Application that supports both RBBCTT (render back buffer, copy to 3782 texture) and RTT (render to texture). The migration path from RBBCTT 3783 to RTT is easy. 3784 3785 if (useFramebuffer) { 3786 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 3787 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3788 GL_COLOR_ATTACHMENT0, 3789 GL_TEXTURE_2D, color_tex, 0); 3790 CHECK_FRAMEBUFFER_STATUS(); 3791 } 3792 3793 draw_to_texture(); 3794 3795 glBindTexture (GL_TEXTURE_2D, color_tex); 3796 if (useFramebuffer) { 3797 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 3798 } else { // copy tex path 3799 glCopyTexSubImage(...); 3800 } 3801 3802 3803 (3) Simple render-to-texture loop with initialization. Create an 3804 RGB8 texture, a 24-bit depth renderbuffer, and a stencil 3805 renderbuffer. In a loop, alternate between rendering to, and 3806 texturing out of, the color texture. 3807 3808 glGenFramebuffers(1, &fb); 3809 glGenTextures(1, &color_tex); 3810 glGenRenderbuffers(1, &depth_rb); 3811 glGenRenderbuffers(1, &stencil_rb); 3812 3813 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 3814 3815 // initialize color texture 3816 glBindTexture(GL_TEXTURE_2D, color_tex); 3817 glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 3818 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 512, 512, 0, 3819 GL_RGB, GL_INT, NULL); 3820 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3821 GL_COLOR_ATTACHMENT0, 3822 GL_TEXTURE_2D, color_tex, 0); 3823 3824 // initialize depth renderbuffer 3825 glBindRenderbuffer(GL_RENDERBUFFER, depth_rb); 3826 glRenderbufferStorage(GL_RENDERBUFFER, 3827 GL_DEPTH_COMPONENT24, 512, 512); 3828 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3829 GL_DEPTH_ATTACHMENT, 3830 GL_RENDERBUFFER, depth_rb); 3831 3832 // initialize stencil renderbuffer 3833 glBindRenderbuffer(GL_RENDERBUFFER, stencil_rb); 3834 glRenderbufferStorage(GL_RENDERBUFFER, 3835 GL_STENCIL_INDEX, 512, 512); 3836 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3837 GL_STENCIL_ATTACHMENT, 3838 GL_RENDERBUFFER, stencil_rb); 3839 3840 // Check framebuffer completeness at the end of initialization. 3841 CHECK_FRAMEBUFFER_STATUS(); 3842 3843 loop { 3844 glBindTexture(GL_TEXTURE_2D, 0); 3845 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 3846 3847 <draw to the texture> 3848 3849 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 3850 glBindTexture(GL_TEXTURE_2D, color_tex); 3851 3852 <draw to the window, reading from the color texture> 3853 } 3854 3855 3856 (4) Render-to-texture loop with automatic mipmap generation. There 3857 are N framebuffers, N mipmap color textures, and a single shared 3858 depth renderbuffer. The depth renderbuffer is not a mipmap. 3859 3860 GLuint fb_array[N]; 3861 GLuint color_tex_array[N]; 3862 GLuint depth_rb; 3863 3864 glGenFramebuffers(N, fb_array); 3865 glGenTextures(N, color_tex_array); 3866 glGenRenderbuffers(1, &depth_rb); 3867 3868 // initialize color textures 3869 for (int i=0; i<N; i++) { 3870 glBindTexture(GL_TEXTURE_2D, color_tex_array[N]); 3871 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 512, 512, 0, 3872 GL_RGB, GL_INT, NULL); 3873 3874 // establish a mipmap chain for the texture 3875 glGenerateMipmap(GL_TEXTURE_2D); 3876 } 3877 3878 // initialize depth renderbuffer 3879 glBindRenderbuffer(GL_RENDERBUFFER, depth_rb); 3880 glRenderbufferStorage(GL_RENDERBUFFER, 3881 GL_DEPTH_COMPONENT24, 512, 512); 3882 3883 // setup framebuffers, sharing depth 3884 for (int i=0; i<N; i++) { 3885 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb_array[i]); 3886 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3887 GL_COLOR_ATTACHMENT0, 3888 GL_TEXTURE_2D, color_tex_array[i], 0); 3889 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3890 GL_DEPTH_ATTACHMENT, 3891 GL_RENDERBUFFER, depth_rb); 3892 } 3893 3894 // Check framebuffer completeness at the end of initialization. 3895 CHECK_FRAMEBUFFER_STATUS(); 3896 3897 loop { 3898 glBindTexture(GL_TEXTURE_2D, 0); 3899 3900 for (int i=0; i<N; i++) { 3901 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb_array[i]); 3902 <draw to texture i> 3903 } 3904 3905 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 3906 3907 // automatically generate mipmaps 3908 for (int i=0; i<N; i++) { 3909 glBindTexture(GL_TEXTURE_2D, color_tex_array[i]); 3910 glGenerateMipmap(GL_TEXTURE_2D); 3911 } 3912 3913 <draw to the window, reading from the color textures> 3914 } 3915 3916 3917 (5) Render-to-texture loop with custom mipmap generation. 3918 The depth renderbuffer is not a mipmap. 3919 3920 glGenFramebuffers(1, &fb); 3921 glGenTextures(1, &color_tex); 3922 glGenRenderbuffers(1, &depth_rb); 3923 3924 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 3925 3926 // initialize color texture and establish mipmap chain 3927 glBindTexture(GL_TEXTURE_2D, color_tex); 3928 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 512, 512, 0, 3929 GL_RGB, GL_INT, NULL); 3930 glGenerateMipmap(GL_TEXTURE_2D); 3931 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3932 GL_COLOR_ATTACHMENT0, 3933 GL_TEXTURE_2D, color_tex, 0); 3934 3935 // initialize depth renderbuffer 3936 glBindRenderbuffer(GL_RENDERBUFFER, depth_rb); 3937 glRenderbufferStorage(GL_RENDERBUFFER, 3938 GL_DEPTH_COMPONENT24, 512, 512); 3939 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3940 GL_DEPTH_ATTACHMENT, 3941 GL_RENDERBUFFER, depth_rb); 3942 3943 // Check framebuffer completeness at the end of initialization. 3944 CHECK_FRAMEBUFFER_STATUS(); 3945 3946 loop { 3947 glBindTexture(GL_TEXTURE_2D, 0); 3948 3949 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 3950 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3951 GL_COLOR_ATTACHMENT0, 3952 GL_TEXTURE_2D, color_tex, 0); 3953 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3954 GL_DEPTH_ATTACHMENT, 3955 GL_RENDERBUFFER, depth_rb); 3956 3957 <draw to the base level of the color texture> 3958 3959 // custom-generate successive mipmap levels 3960 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 3961 GL_DEPTH_ATTACHMENT, 3962 GL_RENDERBUFFER, 0); 3963 glBindTexture(GL_TEXTURE_2D, color_tex); 3964 foreach (level > 0, in order of increasing values of level) { 3965 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 3966 GL_COLOR_ATTACHMENT0, 3967 GL_TEXTURE_2D, color_tex, level); 3968 glTexParameteri(TEXTURE_2D, TEXTURE_BASE_LEVEL, level-1); 3969 glTexParameteri(TEXTURE_2D, TEXTURE_MAX_LEVEL, level-1); 3970 3971 <draw to level> 3972 } 3973 glTexParameteri(TEXTURE_2D, TEXTURE_BASE_LEVEL, 0); 3974 glTexParameteri(TEXTURE_2D, TEXTURE_MAX_LEVEL, max); 3975 3976 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 3977 <draw to the window, reading from the color texture> 3978 } 3979 3980 3981 (6) Pseudo-code example of one method of responding to 3982 FRAMEBUFFER_UNSUPPORTED 3983 3984 bool done = false; 3985 bool success = false; 3986 int configurationNumber = 0; 3987 GLenum status; 3988 3989 while (!done) 3990 { 3991 for (each framebuffer-attachable image) 3992 { 3993 ChooseInternalFormatForFramebufferAttachableImage(configurationNumber); 3994 3995 CreateFramebufferAttachableImage(); 3996 3997 AttachFramebufferAttachableImageToFramebuffer(); 3998 } 3999 4000 status = glCheckFramebufferStatus(GL_DRAW_FRAMEBUFFER); 4001 switch(status) 4002 { 4003 case GL_FRAMEBUFFER_COMPLETE: 4004 success = true; 4005 done = true; 4006 break; 4007 4008 case GL_FRAMEBUFFER_UNSUPPORTED: 4009 if (configCount < MAX_NUM_CONFIGS_I_WANT_TO_TRY) 4010 { 4011 printf("current config not supported, trying again); 4012 configurationNumber++; 4013 } 4014 else 4015 { 4016 printf("couldn't find a supported config\n"); 4017 success = false; 4018 done = true; 4019 } 4020 break; 4021 4022 default: 4023 // programming error; will fail on all hardware 4024 FatalError(); 4025 exit(1); 4026 } 4027 } 4028 4029 if (!success) 4030 { 4031 printf("couldn't find a supported config\n"); 4032 FatalError(); 4033 exit(1); 4034 } 4035 4036 // Current framebuffer is supported and complete!! 4037 Draw(); 4038 4039 4040 (7) Render to depth texture with no color attachments 4041 4042 // Given: depth_tex - TEXTURE_2D depth texture object 4043 // fb - framebuffer object 4044 4045 // Enable render-to-texture 4046 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 4047 4048 // Set up depth_tex for render-to-texture 4049 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 4050 GL_DEPTH_ATTACHMENT, 4051 GL_TEXTURE_2D, depth_tex, 0); 4052 4053 // No color buffer to draw to or read from 4054 glDrawBuffer(GL_NONE); 4055 glReadBuffer(GL_NONE); 4056 4057 // Check framebuffer completeness at the end of initialization. 4058 CHECK_FRAMEBUFFER_STATUS(); 4059 4060 <draw something> 4061 4062 // Re-enable rendering to the window 4063 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 4064 4065 glBindTexture(GL_TEXTURE_2D, depth_tex); 4066 <draw to the window, reading from the depth_tex> 4067 4068 (8) FBO and ARB_draw_buffers 4069 4070 // Given: color_texA - TEXTURE_2D color texture object 4071 // Given: color_texB - TEXTURE_2D color texture object 4072 // depth_rb - GL_DEPTH renderbuffer object 4073 // fb - framebuffer object 4074 4075 // Set up the framebuffer object 4076 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 4077 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 4078 GL_COLOR_ATTACHMENT0, 4079 GL_TEXTURE_2D, color_texA, 0); 4080 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 4081 GL_COLOR_ATTACHMENT1, 4082 GL_TEXTURE_2D, color_texB, 0); 4083 glFramebufferRenderbuffer(GL_DRAW_FRAMEBUFFER, 4084 GL_DEPTH_ATTACHMENT, 4085 GL_RENDERBUFFER, depth_rb); 4086 4087 // Enable both attachments as draw buffers 4088 GLenum drawbuffers = {GL_COLOR_ATTACHMENT0, 4089 GL_COLOR_ATTACHMENT1}; 4090 glDrawBuffers(2, drawbuffers); 4091 4092 // Check framebuffer completeness at the end of initialization. 4093 CHECK_FRAMEBUFFER_STATUS(); 4094 4095 // Enable fragment program that writes to both gl_FragData[0] 4096 // and gl_FragData[1] 4097 4098 <draw something> 4099 4100 // Disable fragment program 4101 4102 // Re-enable rendering to the window 4103 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 0); 4104 4105 // Bind both textures, each to a different texture unit 4106 glActiveTexture(GL_TEXTURE0); 4107 glBindTexture(GL_TEXTURE_2D, color_texA); 4108 glActiveTexture(GL_TEXTURE1); 4109 glBindTexture(GL_TEXTURE_2D, color_texB); 4110 4111 <draw to the window> 4112 4113Sample Code (from framebuffer_blit) 4114 4115 /* Render to framebuffer object 2 */ 4116 glBindFramebuffer(DRAW_FRAMEBUFFER, 2); 4117 RenderScene(); 4118 4119 /* Blit contents of color buffer, depth buffer and stencil buffer 4120 * from framebuffer object 2 to framebuffer object 1. 4121 */ 4122 glBindFramebuffer(GL_READ_FRAMEBUFFER, 2); 4123 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 1); 4124 glBlitFramebuffer(0, 0, 640, 480, 4125 0, 0, 640, 480, 4126 GL_COLOR_BUFFER_BIT | 4127 GL_DEPTH_BUFFER_BIT | 4128 GL_STENCIL_BUFFER_BIT, 4129 GL_NEAREST); 4130 4131 /* Blit contents of color buffer from framebuffer object 1 to 4132 * framebuffer object 2, inverting the image in the X direction. 4133 */ 4134 glBindFramebuffer(GL_READ_FRAMEBUFFER, 1); 4135 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 2); 4136 glBlitFramebuffer(0, 0, 640, 480, 4137 640, 0, 0, 480, 4138 GL_COLOR_BUFFER_BIT, 4139 GL_NEAREST); 4140 4141 /* Blit color buffer from framebuffer object 1 to framebuffer 4142 * object 3 with a 2X zoom and linear filtering. 4143 */ 4144 glBindFramebuffer(GL_READ_FRAMEBUFFER, 1); 4145 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, 3); 4146 glBlitFramebuffer(0, 0, 640, 480, 4147 0, 0, 1280, 960, 4148 GL_COLOR_BUFFER_BIT, GL_LINEAR); 4149 4150Usage Examples (from packed_depth_stencil) 4151 4152 (1) Attach a DEPTH_STENCIL texture image to an FBO as both the 4153 depth and stencil buffers. 4154 4155 glGenFramebuffers(1, &fb); 4156 glGenTextures(1, &tex_color); 4157 glGenTextures(1, &tex_depthstencil); 4158 4159 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 4160 4161 // Setup color texture (mipmap) 4162 glBindTexture(GL_TEXTURE_2D, tex_color); 4163 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 4164 512, 512, 0, GL_RGBA, GL_INT, NULL); 4165 glGenerateMipmap(GL_TEXTURE_2D); 4166 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 4167 GL_COLOR_ATTACHMENT0, 4168 GL_TEXTURE_2D, tex_color, 0); 4169 4170 // Setup depth_stencil texture (not mipmap) 4171 glBindTexture(GL_TEXTURE_2D, tex_depthstencil); 4172 glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 4173 glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH24_STENCIL8, 4174 512, 512, 0, GL_DEPTH_STENCIL, 4175 GL_UNSIGNED_INT_24_8, NULL); 4176 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 4177 GL_DEPTH_ATTACHMENT, 4178 GL_TEXTURE_2D, tex_depthstencil, 0); 4179 glFramebufferTexture2D(GL_DRAW_FRAMEBUFFER, 4180 GL_STENCIL_ATTACHMENT, 4181 GL_TEXTURE_2D, tex_depthstencil, 0); 4182 4183 // Check framebuffer completeness at the end of initialization. 4184 4185 loop { 4186 glBindTexture(GL_TEXTURE_2D, 0); 4187 glBindFramebuffer(GL_DRAW_FRAMEBUFFER, fb); 4188 <render to color, depth, and stencil textures> 4189 glBindFramebuffer(GL_FRAMEBUFFER, 0); 4190 4191 glBindTexture(GL_TEXTURE_2D, tex_color); 4192 glGenerateMipmap(GL_TEXTURE_2D); 4193 <draw to the window, reading from the color texture> 4194 4195 glBindTexture(GL_TEXTURE_2D, tex_depthstencil); 4196 <draw to the window, reading depth from the depthstencil texture> 4197 } 4198 4199 4200Issues 4201 4202 (1) What should this extension be named? 4203 4204 RESOLVED. We will call this ARB_framebuffer_object. 4205 4206 (2) What additional functionality does this extension include over 4207 EXT_framebuffer_object? 4208 4209 RESOLVED. 4210 4211 Currently we incorporate the following layered extensions: 4212 4213 * EXT_framebuffer_multisample 4214 * EXT_framebuffer_blit 4215 * EXT_packed_depth_stencil 4216 4217 As well as the following features: 4218 4219 * Permit attachments with different width and height (mixed 4220 dimensions) 4221 4222 * Permit color attachments with different formats (mixed 4223 formats). 4224 4225 * Render to 1 and 2 component R/RG formats that are provided 4226 via the ARB_texture_rg extension. L/A/LA/I will be 4227 left for a separate (trivial) extension. 4228 4229 * Gen'ed names must be used for framebuffer objects and 4230 renderbuffers. 4231 4232 * Added FramebufferTextureLayer. 4233 4234 Other features we have considered include: 4235 4236 * Render to Vertex Attrib (RTVA) 4237 4238 * Format compatibility API that can guarantee a set of textures 4239 images have framebuffer-compatible formats. 4240 4241 * Infolog or other means for communicating framebuffer 4242 incompleteness information to the application for debugging 4243 purposes. 4244 4245 * A technique for page flipping framebuffer-attachable images. 4246 4247 * Relaxing framebuffer completeness restrictions, possibly even 4248 remove FRAMEBUFFER_UNSUPPORTED. Maybe go so far as to remove 4249 CheckFramebufferStatus. 4250 4251 Features we have rejected include: 4252 4253 * GetRenderbufferImage (benefit/demand does not seem to 4254 outweigh the additional complexity.) 4255 4256 * READ_BUFFER == NONE for framebuffer zero. 4257 4258 * Attach images from a window or from a pbuffer to an 4259 application-created framebuffer object. 4260 4261 (3) What are the other differences from EXT_framebuffer_object. 4262 4263 * Framebuffer completeness only considers the attachments named 4264 by DRAW_BUFFERi and READ_BUFFER. Any other attachments do 4265 not affect framebuffer completeness. (In 4266 EXT_framebuffer_object, all attachments affected framebuffer 4267 completeness, independent of the DRAW_BUFFERi and READ_BUFFER 4268 state.) 4269 * Added new queries for the sizes of the bit planes for color, 4270 depth and stencil attachments at a framebuffer attachment point. 4271 * Added new queries for framebuffer attachment component type and 4272 color encoding. 4273 * Many other minor tweaks to synchronize with the GL3 framebuffer 4274 objects. 4275 * ARB FBOs are not shareable. 4276 4277 (4) Do we need new enum values, or can we re-use the ones from the EXT 4278 versions? 4279 4280 RESOLVED. This extension is designed to be compatible with 4281 EXT_framebuffer_object, and thus we can reuse the enumerants. There 4282 are also a number of additional enumerants added in this extension. 4283 4284 (5) What should a query of RED_BITS, GREEN_BITS, BLUE_BITS, ALPHA_BITS. 4285 return if the attached color-renderable images have different 4286 formats? 4287 4288 RESOLVED. The values of RED_BITS, GREEN_BIT, BLUE_BITS and 4289 ALPHA_BITS are only defined if all color attachments of the draw 4290 framebuffer have identical formats, in which case the color 4291 component sizes of color attachment zero are return. This is 4292 necessary for backwards compatibility with EXT_framebuffer_object. 4293 The actual sizes of the color, depth, or stencil bit planes can be 4294 obtained by querying an attachment point using 4295 GetFramebufferAttachmentParameteriv using the new 4296 FRAMEBUFFER_ATTACHMENT_*_SIZE enumerants, or by querying the object 4297 attached at that point. 4298 4299 (6) What are the proper names for the 1 and 2 component fixed-point, 4300 float, and pure integer texture formats? 4301 4302 RESOLVED: as introduced in the 3.0 spec, using RED and RG base 4303 internal format terminology. The new RED/RG formats have also been 4304 spun out of 3.0 as the ARB_texture_rg extension. 4305 4306 (7) This extension and EXT_framebuffer_object both have "bind 4307 framebuffer" functions (BindFramebuffer and BindFramebufferEXT). Are 4308 there any differences in functionality between the two functions? 4309 4310 RESOLVED: Yes. Both extensions will create a new framebuffer object 4311 if called with an unused name. However, BindFramebuffer defined in 4312 this extension will generate an INVALID_OPERATION error if the name 4313 provided has not been generated by GenFramebuffer. That error did 4314 not exist in EXT_framebuffer_object, and this extension does not 4315 modify the behavior of BindFramebufferEXT. This difference also 4316 applies to BindRenderbuffer from this extension vs. 4317 BindRenderbufferEXT from EXT_framebuffer_object. 4318 4319 (8) Why don't the new tokens and entry points in this extension have 4320 "ARB" suffixes like other ARB extensions? 4321 4322 RESOLVED: Unlike most ARB extensions, this is a strict subset of 4323 functionality already approved in OpenGL 3.0. This extension 4324 exists only to support that functionality on older hardware that 4325 cannot implement a full OpenGL 3.0 driver. Since there are no 4326 possible behavior changes between the ARB extension and core 4327 features, source code compatibility is improved by not using 4328 suffixes on the extension. 4329 4330 (9) Should color-renderable textures be limited to a subset of 4331 color base internal formats? 4332 4333 RESOLVED: No, all color base internal formats and 4334 sized internal formats should be supported by FBO; the FBO 4335 status can report what works and doesn't work. 4336 4337 The glCheckFramebufferStatus provides a mechanism for FBOs to 4338 report whether or not the FBO configuration is supported or 4339 not (i.e. GL_FRAMEBUFFER_UNSUPPORTED). If implementations 4340 have issues supporting certain color formats for rendering, 4341 the existing FBO mechanism is sufficient to report their lack 4342 of support. 4343 4344 Prior to revision 29, the list of color-renderable base internal 4345 formats did not include LUMINANCE, LUMINANCE_ALPHA, or INTENSITY 4346 (and the EXT version of FBO did not list ALPHA either). 4347 4348 This lead to inconsistent operation of FBO. For example, you 4349 could use a glFramebufferTexture2D to attach a texture that 4350 was LUMINANCE, LUMINANCE_ALPHA, or INTENSITY to an FBO and find 4351 out via glCheckFramebufferStatus that this combination wasn't 4352 considered color-renderable, but if an internal format for one of 4353 these base internal formats was used with glRenderbufferStorage, 4354 then an OpenGL error would be generated according to the 4355 specification. Such inconsistencies are undesirable and 4356 unnecessarily limit the render-to-texture functionality exposed by 4357 some implementations when hardware capable of rendering to 4358 LUMINANCE, LUMINANCE_ALPHA, and INTENSITY textures does exist. 4359 4360 For this reason, revision 29 (specification version 1.1) adds 4361 these previously missing based internal formats. Developers are 4362 warned that some implementations (specification version 1.0) 4363 will report OpenGL errors if glRenderbufferStorage is called for 4364 LUMINANCE, INTENSITY, LUMINANCE_ALPHA formats (or even possibly 4365 ALPHA in the case of the EXT version of FBO). 4366 4367 Some thought was given to introducing a new, one-off extension 4368 (instead of a version 1.1) to allow the LUMINANCE, INTENSITY, 4369 LUMINANCE_ALPHA base internal formats and their respective 4370 sized formats to be color-renderable (both otherwise introduce 4371 no new API). Given the existence of a mechanism for determine 4372 whether or not an FBO is supported, simply providing this version 4373 1.1 clarification was judged to be the most expedient approach. 4374 This approach also provides consistency with other approved 4375 ARB specifications such as ARB_framebuffer_sRGB which describes 4376 (see its issue #9) that formats such as GL_SLUMINANCE8. 4377 4378 (10) Can ARB framebuffer objects be shared between contexts? 4379 ARB_framebuffer_object is supposed to be compatible with 4380 EXT_framebuffer_object, but also a subset of OpenGL 3.0. 4381 EXT_framebuffer_object (rev. 120) explicitly allows sharing in 4382 issue 76, but the 3.0 spec explicitly disallows it in Appendix D. 4383 4384 Resolved: No. ARB_framebuffer_object is intended to capture the 4385 functionality that went into GL 3.0. Furthermore, given that the 4386 entry points and tokens in this extension and the core are identical 4387 there is no way that an implementation could differentiate FBOs 4388 created with this extension from those created by core GL. 4389 4390 ADDITIONAL COMMENTS: 4391 4392 See the "Dependencies on EXT_framebuffer_object" section above for 4393 the interaction behaviour between EXT and non-EXT FBO interfaces. 4394 4395Revision History 4396 4397 #1, October 20, 2005: jjuliano 4398 - branch from EXT_framebuffer_object 4399 - Delete old issues and revision history 4400 4401 #2, November 28, 2005: jjuliano 4402 - Add issues 1 and 2. 4403 - Describe RenderbufferStorage in terms of color/depth/stencil 4404 renderable with forward reference to 4.4.4. 4405 - Reword the definitions of color/depth/stencil renderable. 4406 - Explicitly state how framebuffer operations write to and read 4407 from texture images. 4408 - Incorporate feedback from Barthold. 4409 4410 #3-draft2, January 16, 2006: jjuliano 4411 - Define the conversions to/from framebuffer in terms of the 4412 internal format(s) of the attached image(s). 4413 - Handle color mask in RGBA to internal component conversion. 4414 - Improve language in section 4.4.5. 4415 - Add dependencies on more extensions. 4416 4417 #4c April 28, 2008: dgkoch 4418 - merge in framebuffer_blit and update other references to 4419 FRAMEBUFFER_EXT and FRAMEBUFFER_BINDING_EXT, eliminating all 4420 references to the obsolete bindings. 4421 4422 #5 May 2, 2008: rbarris, dgkoch 4423 - merge in framebuffer_multisample 4424 4425 #6 May 8, 2008: dgkoch 4426 - rebase against OpenGL 2.1 spec 4427 4428 #7 May 8, 2008: dgkoch 4429 - merge in packed_depth_stencil 4430 4431 #8 May 8, 2008: dgkoch 4432 - add caveat that MSAA to MSAA blit may have issues (khronos bug 4433 #3005) 4434 4435 #9 May 9, 2008: dgkoch 4436 - renamed from EXT_fbo2 to ARB_fbo. Changed all suffixes to _ARB 4437 instead of _EXT. 4438 4439 #10 May 19, 2008: rbarris 4440 - Bugzilla 3013: allow dimension mismatches (esp. depth) 4441 4442 #11 May 21, 2008: dgkoch 4443 - Bugzilla 3014: allow different color formats when using MRT. 4444 - added Issues 4, 5 4445 - deleted FRAMEBUFFER_INCOMPLETE_FORMATS & 4446 FRAMEBUFFER_INCOMPLETE_DIMENSIONS 4447 - added text for proposed resolution of Issue (5) 4448 4449 #12 May 22, 2008: dgkoch 4450 - Bugzilla 3015: define one- and two- component formats to be 4451 color-renderable 4452 - added Issue 6 4453 4454 #13 May 29, 2008: Jon Leech 4455 - Many updates and minor fixes for consistency with the 3.0 spec 4456 draft. Replace DEPTH with DEPTH_COMPONENT in most uses. Increase 4457 MAX_RENDERBUFFER_SIZE to 64 matching MAX_TEXTURE_SIZE (pending 4458 resolution of bug 3454). Pose some open questions preceded by 4459 "***". 4460 4461 #14 June 26: dgkoch 4462 - change MAX_SAMPLES to 0, to indicate the multisampling is not 4463 required. (bug 3551) 4464 4465 #15 July 2: Jon Leech 4466 - More updates for 3.0 spec consistency. Define meaning of <src> 4467 NONE and FRONT_AND_BACK for ReadBuffer() - this was an 4468 oversight introduced with the original extension. Replace 4469 reference to nonexistent table 12.nnn with reference to 4470 table 3.15. Start introducing RED and RG formats from 3.0 spec. 4471 4472 #16 July 10: dgkoch 4473 - backport error change for DrawBuffer in 4.2.1 (bug 3530) 4474 4475 #17 July 12, 2008: Jon Leech 4476 - Use 'layer' instead of 'zoffset' terminology. Add 4477 FramebufferTextureLayer. 4478 - Add framebuffer attachment queries for attachment component 4479 size / type / color encoding. 4480 - Allow framebuffer incomplete if no default framebuffer is made 4481 current, with new framebuffer status error. 4482 - Allow multisample buffers in framebuffer objects. 4483 - Global renaming / simplification to "default framebuffer" and 4484 "framebuffer object". Did not yet re-flow those paragraphs for 4485 ease of comparison. 4486 - Add more introductory material about framebuffers in chapter 2. 4487 - Remove requirement that all color attachments have the same 4488 depth. 4489 - Restrict FBOs and renderbuffers to Gen'ed names as agreed for 4490 3.0. 4491 - Update clipping / buffer intersection / filtering rules for 4492 BlitFramebuffer. 4493 - Allow FRAMEBUFFER as a bind pseudotarget aliasing both read 4494 and draw framebuffer targets. Allow DEPTH_STENCIL_ATTACHMENT 4495 as an attachment alias for both depth and stencil attachments. 4496 - Add Pat's introductory paragraph describing feedback loops in 4497 section 4.4.3. 4498 - Make RED_BITS etc. context queries defined iff all draw color 4499 buffers have the same format. 4500 - Remove "Dependencies" sections for NV extensions since we no 4501 longer refer to their tokens. Need to add some dependencies 4502 sections for new ARB extensions and figure out which language 4503 goes here and which language with those extensions (e.g. 4504 texture_rg, framebuffer_sRGB, 4505 - Many minor non-functional language tweaks to match 3.0 core 4506 language. 4507 4508 #18 July 14, 2008: Rob Barris 4509 - Tidy up introductory/overview section 4510 4511 #19 July 16, 2008: Daniel Koch, Rob Barris 4512 - add interactions with ARB_texture_rg, EXT_texture_array and 4513 NV_float_buffer 4514 - restore FRAMEBUFFER enumerant and restore all the text where 4515 it had been accepted before (removed in version 4). 4516 - allow texture arrays via FramebufferTextureLayer 4517 - removed reference to required format list which we don't have here. 4518 - updated resolution of issue (6) 4519 4520 #20 July 16, 2008: Daniel Koch, Rob Barris 4521 - simplification of language for logical operation when a FB-image 4522 is attached more than once 4523 - add interactions with EXT_texture_integer and ARB_framebuffer_sRGB 4524 - Resolved issues (2), (4) and (5) 4525 - Updated issue (3) (although the list is still not exhaustive) 4526 4527 #21 July 17, 2008: Daniel Koch 4528 - add Issue (7) as suggested by pbrown 4529 - restore FRAMEBUFFER_BINDING alias 4530 - fix incorrect references to FRAMEBUFFER_BINDING 4531 4532 #22 July 17, 2008: Jon Leech 4533 - minor language cleanup for consistency with the 3.0 core spec. 4534 4535 #23 July 24, 2008: Jon Leech 4536 - Use new GLX rendering opcodes for BindRenderbuffer and 4537 BindFramebuffer so they can be semantically distinguished 4538 from the EXT entry points. 4539 - Add GLX protocol for FramebufferTextureLayer. 4540 4541 #24 August 7, 2008: Jon Leech 4542 - Remove ARB suffixes. 4543 4544 #25 August 8, 2008: Jon Leech 4545 - Add missing framebuffer attachment state for component type / 4546 encoding / size to state tables. 4547 4548 #26 August 8, 2008: Jon Leech 4549 - Add missing INDEX token for legacy default framebuffer 4550 color buffer component types. 4551 4552 #27 August 20, 2008: Jon Leech 4553 - Add ALPHA to list of color-renderable base internal formats to 4554 sync with 3.0 spec language. 4555 4556 #28 November 17, 2008: Mark Kilgard & Nigel Stewart 4557 - glFramebufferTexturLayerARB -> glFramebufferTextureLayerARB 4558 (add final e to Texture) 4559 4560 #29 March 12, 2009: Jon Leech 4561 - Edits in chapter 4 intro for consistency with GL core spec 4562 language, including removing the completeness requirement that all 4563 color buffers of an FBO be the same depth. Reflow some text for 4564 readability. 4565 4566 #30 March 31, 2009: Mark Kilgard & Jeff Juliano 4567 - Change color-renderable to be any color texture format. 4568 Fix some typos. 4569 4570 #31 May 27, 2009: Jon Leech 4571 - Change default value of FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE 4572 to NONE (bug 4407). 4573 4574 #32 July 21, 2010: Daniel Koch 4575 - Add issue 10 clarifying that ARB fbos cannot be shared. 4576 4577 #33 July 22, 2011: Jon Leech 4578 - Remove error which disallowed non-multisample <-> sample blits 4579 (bug 7367). 4580 4581 #34 October 2, 2011: Jon Leech 4582 - Bring chapter 6 language changes in sync with the OpenGL 3.0 API 4583 specification phrasing, and fix the description of 4584 GetFramebufferAttachmentParameteriv to use DEPTH and STENCIL as 4585 attachment names, rather than the nonexistent DEPTH_BUFFER and 4586 STENCIL_BUFFER tokens (Bug 8102). 4587 4588 #35 June 29, 2013: Jon Leech 4589 - Rearrange New Tokens section to allow all simple queries to be 4590 queried with GetBooleanv as well, since it's defined to work for 4591 all of them (Bug 6838). 4592 4593 #36, September 23, 2013: Jon Leech 4594 - Specify that undefined behavior results when mixing EXT and 4595 ARB_framebuffer_object / OpenGL 3.0 API framebuffer objects 4596 (Bug 10738). 4597 4598 #37, June 20, 2016: Kevin Rogvin, James Jones 4599 - Specify behaviour of mixing EXT and ARB_framebuffer_object / 4600 OpenGL 3.0 framebuffer objects so that the aliases of the 4601 functions are correctly observed (Bug 1485) 4602 4603 #38, October 6, 2016: Jon Leech 4604 - Remove STENCIL_REF from list of state moved to become framebuffer 4605 dependent (Bug 8422). 4606