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