1Name 2 3 EXT_framebuffer_object 4 5Name Strings 6 7 GL_EXT_framebuffer_object 8 9Contributors 10 11 Kurt Akeley 12 Jason Allen 13 Bob Beretta 14 Pat Brown 15 Matt Craighead 16 Alex Eddy 17 Cass Everitt 18 Mark Galvan 19 Michael Gold 20 Evan Hart 21 Jeff Juliano 22 Mark Kilgard 23 Dale Kirkland 24 Jon Leech 25 Bill Licea-Kane 26 Barthold Lichtenbelt 27 Kent Lin 28 Rob Mace 29 Teri Morrison 30 Chris Niederauer 31 Brian Paul 32 Paul Puey 33 Ian Romanick 34 John Rosasco 35 R. Jason Sams 36 Jeremy Sandmel 37 Mark Segal 38 Avinash Seetharamaiah 39 Folker Schamel 40 Daniel Vogel 41 Eric Werness 42 Cliff Woolley 43 44Contacts 45 46 Jeff Juliano, NVIDIA Corporation (jjuliano 'at' nvidia.com) 47 Jeremy Sandmel, Apple Computer (jsandmel 'at' apple.com) 48 49Status 50 51 Complete. 52 Approved by the ARB "superbuffers" Working Group on January 31, 2005. 53 Despite being controlled by the ARB WG, this is not an officially 54 approved ARB extension at this time, thus the "EXT" tag. 55 56Version 57 58 Last Modified Date: October 6, 2016 59 Revision: #123 60 61Number 62 63 310 64 65Dependencies 66 67 OpenGL 1.1 is required. 68 69 WGL_ARB_make_current_read affects the definition of this extension. 70 71 GLX 1.3 / GLX_SGI_make_current_read affects the definition of this 72 extension. 73 74 ATI_draw_buffers affects the definition of this extension. 75 76 ARB_draw_buffers affects the definition of this extension. 77 78 ARB_fragment_program affects the definition of this extension. 79 80 ARB_fragment_shader affects the definition of this extension. 81 82 ARB_framebuffer_object and OpenGL 3.0 core affect the definition of 83 this extension. 84 85 ARB_texture_rectangle affects the definition of this extension. 86 87 ARB_vertex_shader affects the definition of this extension. 88 89 EXT_packed_depth_stencil affects the definition of this extension. 90 91 NV_float_buffer affects the definition of this extension. 92 93 NV_texture_shader affects the definition of this extension. 94 95 Written based on the wording of the OpenGL 1.5 specification. 96 97Overview 98 99 This extension defines a simple interface for drawing to rendering 100 destinations other than the buffers provided to the GL by the 101 window-system. 102 103 In this extension, these newly defined rendering destinations are 104 known collectively as "framebuffer-attachable images". This 105 extension provides a mechanism for attaching framebuffer-attachable 106 images to the GL framebuffer as one of the standard GL logical 107 buffers: color, depth, and stencil. (Attaching a 108 framebuffer-attachable image to the accum logical buffer is left for 109 a future extension to define). When a framebuffer-attachable image 110 is attached to the framebuffer, it is used as the source and 111 destination of fragment operations as described in Chapter 4. 112 113 By allowing the use of a framebuffer-attachable image as a rendering 114 destination, this extension enables a form of "offscreen" rendering. 115 Furthermore, "render to texture" is supported by allowing the images 116 of a texture to be used as framebuffer-attachable images. A 117 particular image of a texture object is selected for use as a 118 framebuffer-attachable image by specifying the mipmap level, cube 119 map face (for a cube map texture), and z-offset (for a 3D texture) 120 that identifies the image. The "render to texture" semantics of 121 this extension are similar to performing traditional rendering to 122 the framebuffer, followed immediately by a call to CopyTexSubImage. 123 However, by using this extension instead, an application can achieve 124 the same effect, but with the advantage that the GL can usually 125 eliminate the data copy that would have been incurred by calling 126 CopyTexSubImage. 127 128 This extension also defines a new GL object type, called a 129 "renderbuffer", which encapsulates a single 2D pixel image. The 130 image of renderbuffer can be used as a framebuffer-attachable image 131 for generalized offscreen rendering and it also provides a means to 132 support rendering to GL logical buffer types which have no 133 corresponding texture format (stencil, accum, etc). A renderbuffer 134 is similar to a texture in that both renderbuffers and textures can 135 be independently allocated and shared among multiple contexts. The 136 framework defined by this extension is general enough that support 137 for attaching images from GL objects other than textures and 138 renderbuffers could be added by layered extensions. 139 140 To facilitate efficient switching between collections of 141 framebuffer-attachable images, this extension introduces another new 142 GL object, called a framebuffer object. A framebuffer object 143 contains the state that defines the traditional GL framebuffer, 144 including its set of images. Prior to this extension, it was the 145 window-system which defined and managed this collection of images, 146 traditionally by grouping them into a "drawable". The window-system 147 API's would also provide a function (i.e., wglMakeCurrent, 148 glXMakeCurrent, aglSetDrawable, etc.) to bind a drawable with a GL 149 context (as is done in the WGL_ARB_pbuffer extension). In this 150 extension however, this functionality is subsumed by the GL and the 151 GL provides the function BindFramebufferEXT to bind a framebuffer 152 object to the current context. Later, the context can bind back to 153 the window-system-provided framebuffer in order to display rendered 154 content. 155 156 Previous extensions that enabled rendering to a texture have been 157 much more complicated. One example is the combination of 158 ARB_pbuffer and ARB_render_texture, both of which are window-system 159 extensions. This combination requires calling MakeCurrent, an 160 operation that may be expensive, to switch between the window and 161 the pbuffer drawables. An application must create one pbuffer per 162 renderable texture in order to portably use ARB_render_texture. An 163 application must maintain at least one GL context per texture 164 format, because each context can only operate on a single 165 pixelformat or FBConfig. All of these characteristics make 166 ARB_render_texture both inefficient and cumbersome to use. 167 168 EXT_framebuffer_object, on the other hand, is both simpler to use 169 and more efficient than ARB_render_texture. The 170 EXT_framebuffer_object API is contained wholly within the GL API and 171 has no (non-portable) window-system components. Under 172 EXT_framebuffer_object, it is not necessary to create a second GL 173 context when rendering to a texture image whose format differs from 174 that of the window. Finally, unlike the pbuffers of 175 ARB_render_texture, a single framebuffer object can facilitate 176 rendering to an unlimited number of texture objects. 177 178Glossary of Helpful Terms 179 180 logical buffer: 181 One of the color, depth, or stencil buffers of the 182 framebuffer. 183 184 framebuffer: 185 The collection of logical buffers and associated state 186 defining where the output of GL rendering is directed. 187 188 texture: 189 an object which consists of one or more 2D arrays of pixel 190 images and associated state that can be used as a source of 191 data during the texture-mapping process described in section 192 3.8. 193 194 texture image: 195 one of the 2D arrays of pixels that are part of a texture 196 object as defined in section 3.8. Texture images contain 197 and define the texels of the texture object. 198 199 renderbuffer: 200 A new type of storage object which contains a single 2D 201 array of pixels and associated state that can be used as a 202 destination for pixel data written during the rendering 203 process described in Chapter 4. 204 205 renderbuffer image: 206 The 2D array of pixels that is part of a renderbuffer 207 object. A renderbuffer image contains and defines the 208 pixels of the renderbuffer object. 209 210 framebuffer-attachable image: 211 A 2D pixel image that can be attached to one of the logical 212 buffer attachment points of a framebuffer object. Texture 213 images and renderbuffer images are two examples of 214 framebuffer-attachable images. 215 216 attachment point: 217 The set of state which references a specific 218 framebuffer-attachable image, and allows that 219 framebuffer-attachable image to be used to store the 220 contents of a logical buffer of a framebuffer object. There 221 is an attachment point state vector for each color, depth, 222 and stencil buffer of a framebuffer. 223 224 attach: 225 The act of connecting one object to another object. 226 227 An "attach" operation is similar to a "bind" operation in 228 that both represent a reference to the attached or bound 229 object for the purpose of managing object lifetimes and both 230 enable manipulation of the state of the attached or bound 231 object. 232 233 However, an "attach" is also different from a "bind" in that 234 "binding" an unused object creates a new object, while 235 "attaching" does not. Additionally, "bind" establishes a 236 connection between a context and an object, while "attach" 237 establishes a connection between two objects. 238 239 Finally, if object "A" is attached to object "B" and object 240 "B" is bound to context "C", then in most respects, we treat 241 "A" as if it is <implicitly> bound to "C". 242 243 framebuffer attachment completeness: 244 Similar to texture "mipmap" or "cube" completeness from 245 section 3.8.10, defines a minimum set of criteria for 246 framebuffer attachment points. (for complete definition, 247 see section 4.4.4.1) 248 249 framebuffer completeness: 250 Similar to texture "mipmap cube completeness", defines a 251 composite set of "completeness" requirements and 252 relationships among the attached framebuffer-attachable 253 images. (for complete definition, see section 4.4.4.2) 254 255 256Issues 257 258 Breaking from past convention, the very large issues section has 259 been moved to the end of the document. It can be found after 260 Examples, before Revision History. 261 262 263New Procedures and Functions 264 265 boolean IsRenderbufferEXT(uint renderbuffer); 266 void BindRenderbufferEXT(enum target, uint renderbuffer); 267 void DeleteRenderbuffersEXT(sizei n, const uint *renderbuffers); 268 void GenRenderbuffersEXT(sizei n, uint *renderbuffers); 269 270 void RenderbufferStorageEXT(enum target, enum internalformat, 271 sizei width, sizei height); 272 273 void GetRenderbufferParameterivEXT(enum target, enum pname, int *params); 274 275 boolean IsFramebufferEXT(uint framebuffer); 276 void BindFramebufferEXT(enum target, uint framebuffer); 277 void DeleteFramebuffersEXT(sizei n, const uint *framebuffers); 278 void GenFramebuffersEXT(sizei n, uint *framebuffers); 279 280 enum CheckFramebufferStatusEXT(enum target); 281 282 void FramebufferTexture1DEXT(enum target, enum attachment, 283 enum textarget, uint texture, 284 int level); 285 void FramebufferTexture2DEXT(enum target, enum attachment, 286 enum textarget, uint texture, 287 int level); 288 void FramebufferTexture3DEXT(enum target, enum attachment, 289 enum textarget, uint texture, 290 int level, int zoffset); 291 292 void FramebufferRenderbufferEXT(enum target, enum attachment, 293 enum renderbuffertarget, uint renderbuffer); 294 295 void GetFramebufferAttachmentParameterivEXT(enum target, enum attachment, 296 enum pname, int *params); 297 298 void GenerateMipmapEXT(enum target); 299 300 301New Types 302 303 None. 304 305 306New Tokens 307 308 Accepted by the <target> parameter of BindFramebufferEXT, 309 CheckFramebufferStatusEXT, FramebufferTexture{1D|2D|3D}EXT, 310 FramebufferRenderbufferEXT, and 311 GetFramebufferAttachmentParameterivEXT: 312 313 FRAMEBUFFER_EXT 0x8D40 314 315 Accepted by the <target> parameter of BindRenderbufferEXT, 316 RenderbufferStorageEXT, and GetRenderbufferParameterivEXT, and 317 returned by GetFramebufferAttachmentParameterivEXT: 318 319 RENDERBUFFER_EXT 0x8D41 320 321 Accepted by the <internalformat> parameter of 322 RenderbufferStorageEXT: 323 324 STENCIL_INDEX1_EXT 0x8D46 325 STENCIL_INDEX4_EXT 0x8D47 326 STENCIL_INDEX8_EXT 0x8D48 327 STENCIL_INDEX16_EXT 0x8D49 328 329 Accepted by the <pname> parameter of GetRenderbufferParameterivEXT: 330 331 RENDERBUFFER_WIDTH_EXT 0x8D42 332 RENDERBUFFER_HEIGHT_EXT 0x8D43 333 RENDERBUFFER_INTERNAL_FORMAT_EXT 0x8D44 334 RENDERBUFFER_RED_SIZE_EXT 0x8D50 335 RENDERBUFFER_GREEN_SIZE_EXT 0x8D51 336 RENDERBUFFER_BLUE_SIZE_EXT 0x8D52 337 RENDERBUFFER_ALPHA_SIZE_EXT 0x8D53 338 RENDERBUFFER_DEPTH_SIZE_EXT 0x8D54 339 RENDERBUFFER_STENCIL_SIZE_EXT 0x8D55 340 341 Accepted by the <pname> parameter of 342 GetFramebufferAttachmentParameterivEXT: 343 344 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT 0x8CD0 345 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT 0x8CD1 346 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT 0x8CD2 347 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT 0x8CD3 348 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT 0x8CD4 349 350 Accepted by the <attachment> parameter of 351 FramebufferTexture{1D|2D|3D}EXT, FramebufferRenderbufferEXT, and 352 GetFramebufferAttachmentParameterivEXT 353 354 COLOR_ATTACHMENT0_EXT 0x8CE0 355 COLOR_ATTACHMENT1_EXT 0x8CE1 356 COLOR_ATTACHMENT2_EXT 0x8CE2 357 COLOR_ATTACHMENT3_EXT 0x8CE3 358 COLOR_ATTACHMENT4_EXT 0x8CE4 359 COLOR_ATTACHMENT5_EXT 0x8CE5 360 COLOR_ATTACHMENT6_EXT 0x8CE6 361 COLOR_ATTACHMENT7_EXT 0x8CE7 362 COLOR_ATTACHMENT8_EXT 0x8CE8 363 COLOR_ATTACHMENT9_EXT 0x8CE9 364 COLOR_ATTACHMENT10_EXT 0x8CEA 365 COLOR_ATTACHMENT11_EXT 0x8CEB 366 COLOR_ATTACHMENT12_EXT 0x8CEC 367 COLOR_ATTACHMENT13_EXT 0x8CED 368 COLOR_ATTACHMENT14_EXT 0x8CEE 369 COLOR_ATTACHMENT15_EXT 0x8CEF 370 DEPTH_ATTACHMENT_EXT 0x8D00 371 STENCIL_ATTACHMENT_EXT 0x8D20 372 373 Returned by CheckFramebufferStatusEXT(): 374 375 FRAMEBUFFER_COMPLETE_EXT 0x8CD5 376 FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT 0x8CD6 377 FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT_EXT 0x8CD7 378 FRAMEBUFFER_INCOMPLETE_DIMENSIONS_EXT 0x8CD9 379 FRAMEBUFFER_INCOMPLETE_FORMATS_EXT 0x8CDA 380 FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER_EXT 0x8CDB 381 FRAMEBUFFER_INCOMPLETE_READ_BUFFER_EXT 0x8CDC 382 FRAMEBUFFER_UNSUPPORTED_EXT 0x8CDD 383 384 Accepted by GetIntegerv(): 385 386 FRAMEBUFFER_BINDING_EXT 0x8CA6 387 RENDERBUFFER_BINDING_EXT 0x8CA7 388 MAX_COLOR_ATTACHMENTS_EXT 0x8CDF 389 MAX_RENDERBUFFER_SIZE_EXT 0x84E8 390 391 Returned by GetError(): 392 393 INVALID_FRAMEBUFFER_OPERATION_EXT 0x0506 394 395Additions to Chapter 2 of the 1.5 Specification (OpenGL Operation) 396 397 "The GL interacts with two classes of framebuffers: 398 window-system-provided framebuffers and application-created 399 framebuffers. There is always one window-system-provided 400 framebuffer, while application-created framebuffers can be created 401 as desired. These two types of framebuffer are distinguished 402 primarily by the interface for configuring and managing their state. 403 404 The effects of GL commands on the window-system-provided framebuffer 405 are ultimately controlled by the window-system that allocates 406 framebuffer resources. It is the window-system that determines 407 which portions of this framebuffer the GL may access at any given 408 time and that communicates to the GL how those portions are 409 structured. Therefore, there are no GL commands to configure the 410 window-system-provided framebuffer. Similarly, display of 411 framebuffer contents on a CRT monitor (including the transformation 412 of individual framebuffer values by such techniques as gamma 413 correction) is not addressed by the GL. Framebuffer configuration 414 occurs outside of the GL in conjunction with the window-system. 415 416 The initialization of a GL context itself occurs when the 417 window-system allocates a window for GL rendering and is influenced 418 by the state of the window-system-provided framebuffer." 419 420Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization) 421 422 In section 3.6.4, page 102, add the following text to the definiton 423 of DrawPixels: 424 425 "If the object bound to FRAMEBUFFER_BINDING_EXT is not "framebuffer 426 complete" (as defined in section 4.4.4.2), then an attempt to call 427 DrawPixels will generate the error 428 INVALID_FRAMEBUFFER_OPERATION_EXT." 429 430 In section 3.8.8, add the following text immediately before the 431 subsection "Mipmapping" on page 151: 432 433 "If all of the following conditions are satisfied, then the value of 434 the selected Tau(ijk), Tau(ij), or Tau(i) in the above equations is 435 undefined instead of referring to the value of the texel at location 436 (i), (i,j), or (i,j,k). See Chapter 4 for discussion of framebuffer 437 objects and their attachments. 438 439 * The current FRAMEBUFFER_BINDING_EXT names an application-created 440 framebuffer object <F>. 441 442 * The texture is attached to one of the attachment points, <A>, of 443 framebuffer object <F>. 444 445 * TEXTURE_MIN_FILTER is NEAREST or LINEAR, and the value of 446 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT for attachment point 447 <A> is equal to the value of TEXTURE_BASE_LEVEL 448 449 -or- 450 451 TEXTURE_MIN_FILTER is NEAREST_MIPMAP_NEAREST, 452 NEAREST_MIPMAP_LINEAR, LINEAR_MIPMAP_NEAREST, or 453 LINEAR_MIPMAP_LINEAR, and the value of 454 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT for attachment point 455 <A> is within the the inclusive range from TEXTURE_BASE_LEVEL to 456 q." 457 458 In subsection "Automatic Mipmap Generation" to section 3.8.8, 459 replace the first paragraph with the following text: 460 461 "If the value of texture parameter GENERATE MIPMAP is TRUE and a 462 change is made to the interior or border texels of the level[base] 463 array of a mipmap by one of the texture image specification 464 operations defined in sections 3.8.1 through 3.8.3, then a complete 465 set of mipmap arrays (as defined in section 3.8.10) will be 466 computed. Array levels level[base] + 1 through p are replaced with 467 arrays derived from the modified level[base], regardless of their 468 previous contents. All other mipmap arrays, including the 469 level[base] array, are left unchanged by this computation." 470 471 Add a new subsection "Manual Mipmap Generation" to section 3.8.8, 472 after "Automatic Mipmap Generation": 473 474 "Manual Mipmap Generation 475 476 Mipmaps can be generated manually with the command 477 478 void GenerateMipmapEXT(enum target); 479 480 where <target> is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_CUBE_MAP, 481 or TEXTURE_3D. Mipmap generation affects the texture image attached 482 to <target>. For cube map textures, INVALID_OPERATION is generated 483 if the texture bound to <target> is not cube complete, as defined in 484 section 3.8.10. 485 486 Mipmap generation replaces texture array levels level[base] + 1 487 through q with arrays derived from the level[base] array, as 488 described above under Automatic Mipmap Generation. All other mipmap 489 arrays, including the level[base] array, are left unchanged by this 490 computation. For arrays in the range level[base] through q, 491 inclusive, automatic and manual mipmap generation generate the same 492 derived arrays, given identical level[base] arrays." 493 494 Modify the third paragraph of section 3.8.12, page 157, to read: 495 496 "Texture objects are deleted by calling 497 498 void DeleteTextures( sizei n, uint *textures ); 499 500 textures contains n names of texture objects to be deleted. After a 501 texture object is deleted, it has no contents or dimensionality, and 502 its name is again unused. If a texture that is currently bound to 503 one of the targets TEXTURE 1D, TEXTURE 2D, TEXTURE 3D, or TEXTURE 504 CUBE MAP is deleted, it is as though BindTexture had been executed 505 with the same target and texture zero. Additionally, special care 506 must be taken when deleting a texture if any of the images of the 507 texture are attached to a framebuffer object. See section 4.4.2.3 508 for details. 509 510 Unused names in textures are silently ignored, as is the value 511 zero." 512 513 514Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment 515Operations and the Framebuffer) 516 517 On page 170, in the introduction to chapter 4, modify the first 518 three paragraphs to read as follows: 519 520 "The framebuffer consists of a set of pixels arranged as a 521 two-dimensional array. The height and width of this array may vary 522 from one GL implementation to another. For purposes of this 523 discussion, each pixel in the framebuffer is simply a set of some 524 number of bits. The number of bits per pixel may also vary 525 depending on the particular GL implementation or context. 526 527 Further there are two classes of framebuffers: the default 528 framebuffer supplied by the window-system-provided and 529 application-created framebuffer objects. Every GL context has a 530 single default window-system-provided framebuffer. Applications can 531 optionally create additional non-displayable framebuffer objects. 532 (For more information on application-created framebuffer objects see 533 section 4.4) 534 535 Corresponding bits from each pixel in the framebuffer are grouped 536 together into a bitplane; each bitplane contains a single bit from 537 each pixel. These bitplanes are grouped into several logical 538 buffers. These are the color, depth, stencil, and accumulation 539 buffers. The color buffer actually consists of a number of buffers, 540 and these color buffers serve related but slightly different 541 purposes depending on whether the GL is bound to the default 542 window-system-provided framebuffer or to an application-created 543 framebuffer object. 544 545 For the default window-system-provided framebuffer, the color 546 buffers are: the front left buffer, the front right buffer, the back 547 left buffer, the back right buffer, and some number of auxiliary 548 buffers. Typically, the contents of the front buffers are displayed 549 on a color monitor while the contents of the back buffers are 550 invisible. (Monoscopic contexts display only the front left buffer; 551 stereoscopic contexts display both the front left and the front 552 right buffers.) The contents of the auxiliary buffers are never 553 visible. All color buffers must have the same number of bitplanes, 554 although an implementation or context may choose not to provide 555 right buffers, back buffers, or auxiliary buffers at all. Further, 556 an implementation or context may not provide depth, stencil, or 557 accumulation buffers. 558 559 For application-created framebuffer objects, the color buffers are 560 not visible, and consequently the names of the color buffers are not 561 related to a display device. The names of the color buffers of an 562 application-created framebuffer object are: COLOR_ATTACHMENT0_EXT 563 through COLOR_ATTACHMENTn_EXT. The names of the depth and stencil 564 buffers are DEPTH_ATTACHMENT_EXT and STENCIL_ATTACHMENT_EXT. For 565 more information about the buffers of an application-created 566 framebuffer object, see section 4.4.2. To be considered framebuffer 567 complete (see section 4.4.4), all color buffers attached to an 568 application-created framebuffer object must have the same number of 569 bitplanes. Depth and stencil buffers may optionally be attached to 570 application-created framebuffers as well. 571 572 Color buffers consist of either unsigned integer color indices or R, 573 G, B, and, optionally, A unsigned integer values. The number of 574 bitplanes in each of the color buffers, the depth buffer, the 575 stencil buffer, and the accumulation buffer is dependent on the 576 currently bound framebuffer. For the default framebuffer, the 577 number of bitplanes is fixed. For application-created framebuffer 578 objects, however, the number of bitplanes in a given logical buffer 579 may change if the state of the corresponding framebuffer attachment 580 or attached image changes (see sections 4.4.2 and 4.4.5). If an 581 accumulation buffer is provided, it must have at least as many 582 bitplanes per R, G, and B color component as do the color buffers." 583 584 Add a new paragraph to the end of section 4.1.1, page 171: 585 586 "While an application-created framebuffer object is bound to 587 FRAMEBUFFER_EXT, the pixel ownership test always passes. The pixels 588 of application-created frambuffer objects are always owned by the 589 GL, not the window system. Only while the window-system-provided 590 framebuffer named zero is bound to FRAMEBUFFER_EXT does the window 591 system control pixel ownership." 592 593 Change section 4.1.5, page 174, third paragraph, first two sentences 594 to read as follows: 595 596 "<ref> is an integer reference value that is used in the unsigned 597 stencil comparison. Stencil comparison operations and queries of 598 <ref> use the value of <ref> clamped to the range [0, (2^s) - 1], 599 where s is the current number of bits in the stencil buffer." 600 601 Replace the first three sentences of 4.1.10 "Logical Operation": 602 603 "Finally, a logical operation is applied between the incoming 604 fragment's color or index values and the color or index values 605 stored at the corresponding location in the framebuffer. The result 606 replaces the values in the framebuffer at the fragment's (x[w], 607 y[w]) coordinates. However, if the DRAW_BUFFERS state selects a 608 single framebuffer-attachable image more than once, then an 609 undefined value is written to those color buffers at the fragment's 610 (x[w], y[x]) coordinates." 611 612 Change section 4.2.1, to read as follows: 613 614 "The first such operation is controlling the buffer into which color 615 values are written. This is accomplished with 616 617 void DrawBuffer( enum buf ); 618 619 <buf> defines a buffer or set of buffers for writing. <buf> must be 620 one of the values from tables 4.4 or 10.nnn. Otherwise, 621 INVALID_ENUM is generated. In addition, acceptable values for <buf> 622 depend on whether the GL is using the default window-system-provided 623 framebuffer (i.e., FRAMEBUFFER_BINDING_EXT is zero), or an 624 application-created framebuffer object (i.e., 625 FRAMEBUFFER_BINDING_EXT is non-zero). In the initial state, the GL 626 is bound to the the window-system-provided framebuffer. For more 627 information about application-created framebuffer objects, see 628 section 4.4. 629 630 If the GL is bound to the window-system-provided framebuffer, then 631 <buf> must be one the values listed in table 4.4, which summarizes 632 the constants and the buffers they indicate. In this case, <buf> is 633 a symbolic constant specifying zero, one, two, or four buffers for 634 writing. These constants refer to the four potentially visible 635 buffers front left, front right, back left, and back right, and to 636 the auxiliary buffers. Arguments other than AUXi that omit 637 reference to LEFT or RIGHT refer to both left and right buffers. 638 Arguments other than AUXi that omit reference to FRONT or BACK refer 639 to both front and back buffers. AUXi enables drawing only to 640 auxiliary buffer i. Each AUXi adheres to AUXi = AUX0 + i. 641 642 If the GL is bound to an application-created framebuffer object, 643 <buf> must be one of the values listed in table 10.nnn, which 644 summarizes the constants and the buffers they indicate. In this 645 case, <buf> is a symbolic constant specifying a single color buffer 646 for writing. Specifying COLOR_ATTACHMENTi_EXT enables drawing only 647 to the image attached to the framebuffer at COLOR_ATTACHMENTi_EXT. 648 Each COLOR_ATTACHMENTi_EXT adheres to COLOR_ATTACHMENTi_EXT = 649 COLOR_ATTACHMENT0_EXT + i. The intial value of DRAW_BUFFER for 650 application-created framebuffer objects is COLOR_ATTACHMENT0_EXT. 651 652 653 Symbolic Constant Meaning 654 ----------------- ------- 655 NONE no buffer 656 COLOR_ATTACHMENT0 output fragment color to image attached 657 at color attachment point 0 658 COLOR_ATTACHMENT1 output fragment color to image attached 659 at color attachment point 1 660 ... ... 661 COLOR_ATTACHMENTn output fragment color to image attached 662 at color attachment point n, where 663 n is MAX_COLOR_ATTACHMENTS - 1 664 ------------------------------------------------------------------- 665 Table 10.nnn: Arguments to DrawBuffer(s) and ReadBuffer when the 666 context is bound to an application-created framebuffer object, and 667 the buffers they indicate 668 669 If the GL is bound to the window-system-provided framebuffer and 670 DrawBuffer is supplied with a constant (other than NONE) that does 671 not indicate any of the color buffers allocated to the GL context by 672 the window-system (including those listed in table 10.nnn), then the 673 error INVALID_OPERATION results. 674 675 If the GL is bound to the application-created framebuffer and 676 DrawBuffer is supplied with a constant from table 4.4, or 677 COLOR_ATTACHMENTm where m is greater than or equal to 678 MAX_COLOR_ATTACHMENTS, then the error INVALID_OPERATION results. 679 680 If DrawBuffer is supplied with a constant that is neither legal for 681 the window-system provided framebuffer nor legal for an 682 application-created framebuffer object, then the error INVALID_ENUM 683 results. 684 685 The command 686 687 void DrawBuffers( sizei n, const enum *bufs ); 688 689 defines the draw buffers to which all fragment colors are written. 690 <n> specifies the number of buffers in <bufs>. <bufs> is a pointer 691 to an array of symbolic constants specifying the buffer to which 692 each fragment color is written. 693 694 Each enumerant listed in <bufs> must be one of the values from 695 tables 10.nnn or 11.nnn. Otherwise, INVALID_ENUM is generated. 696 Further, acceptable values for the constants in <bufs> depend on 697 whether the GL is using the default window-system-provided 698 framebuffer (i.e., FRAMEBUFFER_BINDING_EXT is zero), or an 699 application-created framebuffer object (i.e., 700 FRAMEBUFFER_BINDING_EXT is non-zero). For more information about 701 application-created framebuffer objects, see section 4.4. 702 703 704 symbolic front front back back aux 705 constant left right left right i 706 -------- ----- ----- ---- ----- --- 707 NONE 708 FRONT LEFT X 709 FRONT RIGHT X 710 BACK LEFT X 711 BACK RIGHT X 712 AUXi X 713 -------------------------------------------------- 714 Table 11.nnn: Arguments to DrawBuffers, when the context is bound 715 to the window-system-provided framebuffer, and the buffers that 716 they indicate. 717 718 If the GL is bound to the default window-system-provided 719 framebuffer, then the each of the constants must be one of the 720 values listed in table 11.nnn 721 722 If the GL is bound to an application-created framebuffer object, 723 then each of the constants must be one of the values listed in table 724 10.nnn. 725 726 In both cases, the draw buffers being defined correspond in order to 727 the respective fragment colors. The draw buffer for fragment colors 728 beyond <n> is set to NONE. 729 730 The maximum number of draw buffers is implementation dependent and 731 must be at least 1. The number of draw buffers supported can be 732 queried by calling GetIntegerv with the symbolic constant 733 MAX_DRAW_BUFFERS. INVALID_VALUE is generated if <n> is greater 734 than MAX_DRAW_BUFFERS. 735 736 Except for NONE, a buffer may not appear more then once in the array 737 pointed to by <bufs>. Specifying a buffer more then once will 738 result in the error INVALID_OPERATION. 739 740 If fixed-function fragment shading is being performed, DrawBuffers 741 specifies a set of draw buffers into which the fragment color is 742 written. 743 744 If a fragment shader writes to "gl_FragColor", DrawBuffers specifies 745 a set of draw buffers into which the single fragment color defined 746 by "gl_FragColor" is written. If a fragment shader writes to gl 747 FragData, DrawBuffers specifies a set of draw buffers into which 748 each of the multiple fragment colors defined by "gl_FragData" are 749 separately written. If a fragment shader writes to neither gl 750 FragColor nor "gl_FragData", the values of the fragment colors 751 following shader execution are undefined, and may differ for each 752 fragment color. 753 754 For both window-system-provided and application-created 755 framebuffers, the constants FRONT, BACK, LEFT, RIGHT, and 756 FRONT_AND_BACK are not valid in the <bufs> array passed to 757 DrawBuffers, and will result in the error INVALID_OPERATION. This 758 restriction is because these constants may themselves refer to 759 multiple buffers, as shown in table 4.4. 760 761 If the GL is bound to the window-system-provided framebuffer and 762 DrawBuffers is supplied with a constant (other than NONE) that does 763 not indicate any of the color buffers allocated to the GL context by 764 the window-system, then the error INVALID_OPERATION results. 765 766 If the GL is bound to the application-created framebuffer and 767 DrawBuffers is supplied with a constant from table 11.nnn, or 768 COLOR_ATTACHMENTm where m is greater than or equal to 769 MAX_COLOR_ATTACHMENTS, then the error INVALID_OPERATION results. 770 771 If DrawBuffers is supplied with a constant that is neither legal for 772 the window-system provided framebuffer nor legal for an 773 application-created framebuffer object, then the error INVALID_ENUM 774 results. 775 776 Indicating a buffer or buffers using DrawBuffer or DrawBuffers 777 causes subsequent pixel color value writes to affect the indicated 778 buffers. 779 780 Specifying NONE as the draw buffer for a fragment color will inhibit 781 that fragment color from being written to any buffer. 782 783 Monoscopic contexts include only left buffers, while stereoscopic 784 contexts include both left and right buffers. Likewise, single 785 buffered contexts include only front buffers, while double buffered 786 contexts include both front and back buffers. The type of context 787 is selected at GL initialization. 788 789 The state required to handle color buffer selection is an integer 790 for each supported fragment color. For the default 791 window-system-provided framebuffer, in the initial state, the draw 792 buffer for fragment color zero is FRONT if there are no back 793 buffers; otherwise it is BACK. For application-created framebuffer 794 objects, the initial value of draw buffer for fragment color zero is 795 COLOR_ATTACHMENT0_EXT. For both the window-system-provided 796 framebuffer and application-created framebuffers, the initial state 797 of draw buffers for fragment colors other then zero is NONE." 798 799 Modify section 4.2.2, page 185, third paragraph to read as follows: 800 801 "The command 802 803 void StencilMask( uint mask ); 804 805 controls the writing of particular bits into the stencil planes. The 806 least significant s bits of mask comprise an integer mask (s is the 807 number of bits in the stencil buffer), just as for IndexMask. The 808 initial state is for the stencil plane mask to be 32 ones." 809 810 In section 4.3.2, page 190, modify the first two paragraphs of the 811 definition of ReadBuffer to read as follows: 812 813 "The command 814 815 void ReadBuffer( enum src ); 816 817 takes a symbolic constant as argument. <src> must be one of the 818 values from tables 4.4 or 10.nnn. Otherwise, INVALID_ENUM is 819 generated. Further, the acceptable values for <src> depend on 820 whether the GL is using the default window-system-provided 821 framebuffer (i.e., FRAMEBUFFER_BINDING_EXT is zero), or an 822 application-created framebuffer object (i.e., 823 FRAMEBUFFER_BINDING_EXT is non-zero). For more information about 824 application-created framebuffer objects, see section 4.4. 825 826 If the object bound to FRAMEBUFFER_BINDING_EXT is not "framebuffer 827 complete" (as defined in section 4.4.4.2), then ReadPixels generates 828 the error INVALID_FRAMEBUFFER_OPERATION_EXT. If ReadBuffer is 829 supplied with a constant that is neither legal for the window-system 830 provided framebuffer, nor legal for an application-created 831 framebuffer object, then the error INVALID_ENUM results. 832 833 When FRAMEBUFFER_BINDING_EXT is zero, i.e. the default 834 window-system-provided framebuffer, <src> must be one of the values 835 listed in table 4.4. FRONT and LEFT refer to the front left buffer, 836 BACK refers to the back left buffer, and RIGHT refers to the front 837 right buffer. The other constants correspond directly to the 838 buffers that they name. If the requested buffer is missing, then the 839 error INVALID_OPERATION is generated. For the default 840 window-system-provided framebuffer, the initial setting for 841 ReadBuffer is FRONT if there is no back buffer and BACK otherwise. 842 843 When the GL is using an application-created framebuffer object, 844 <src> must be one of the values listed in table 10.nnn, including 845 NONE. In a manner analogous to how the DRAW_BUFFERs state is 846 handled, specifying COLOR_ATTACHMENTi_EXT enables reading from the 847 image attached to the framebuffer at COLOR_ATTACHMENTi_EXT. 848 ReadPixels generates INVALID_OPERATION if it attempts to select a 849 color buffer while READ_BUFFER is NONE. For application-created 850 framebuffer objects, the initial setting for ReadBuffer is 851 COLOR_ATTACHMENT0_EXT. 852 853 ReadPixels obtains values from the selected buffer from each pixel 854 with lower left hand corner at (x+i, y+j) for (0 <= i < width) and 855 (0 <= j < height); this pixel is said to be the ith pixel in the jth 856 row. If any of these pixels lies outside of the window allocated to 857 the current GL context, or outside of the image attached to the 858 currently bound framebuffer object, then the values obtained for 859 those pixels are undefined. When FRAMEBUFFER_BINDING_EXT is zero, 860 results are also undefined for individual pixels that are not owned 861 by the current context. Otherwise, ReadPixels obtains values from 862 the selected buffer, regardless of how those values were placed 863 there." 864 865 In section 4.3.2, "Reading Pixels", add a paragraph before 866 "Conversion of RGBA values" on page 191: 867 868 "When FRAMEBUFFER_BINDING is non-zero, the red, green, blue, and 869 alpha values are obtained by first reading the internal component 870 values of the corresponding value in the image attached to the 871 selected logical buffer. The internal component values are 872 converted to red, green, blue, and alpha values as specified in the 873 row of table 12.nnn corresponding to the internal format of the 874 image attached to READ_BUFFER." 875 876 Add the following text to section 4.3.3, page 194, inside the 877 definiton of CopyPixels: 878 879 "Furthermore, the behavior of several GL operations is specified "as 880 if the arguments were passed to CopyPixels." These operations 881 include: CopyTex{Sub}Image*, CopyColor{Sub}Table, and 882 CopyConvolutionFilter*. INVALID_FRAMEBUFFER_OPERATION_EXT will be 883 generated if an attempt is made to execute one of these operations, 884 or CopyPixels, while the object bound to FRAMEBUFFER_BINDING_EXT is 885 not "framebuffer complete" (as defined in section 4.4.4.2)." 886 887 Add a new section "Framebuffer Objects" after section 4.3: 888 889 "4.4 Framebuffer Objects 890 891 As described in chapters 1 and 2, GL renders into (and reads values 892 from) a framebuffer. GL defines two classes of framebuffers: 893 window-system-provided framebuffers and application-created 894 framebuffers. For each GL context, there is a single framebuffer 895 provided by the window-system, and there may also be one or more 896 framebuffer objects created and managed by the application. 897 898 By default, the GL uses the window-system-provided framebuffer. The 899 storage, dimensions, allocation, and format of the images attached 900 to this framebuffer are managed entirely by the window-system. 901 Consequently, the state of the window-system-provided framebuffer, 902 including its images, can not be changed by the GL, nor can the 903 window-system-provided framebuffer itself, or its images, be deleted 904 by the GL. 905 906 The routines described in the following sections, however, can be 907 used to create, destroy, and modify the state and attachments of 908 application-created framebuffer objects. 909 910 Application-created framebuffer objects encapsulate the state of a 911 framebuffer in a similar manner to the way texture objects 912 encapsulate the state of a texture. In particular, a framebuffer 913 object encapsulates state necessary to describe a collection of 914 color, depth, stencil, accum, and aux logical buffers. For each 915 logical buffer, a framebuffer-attachable image can be attached to 916 the framebuffer to store the rendered output for that logical 917 buffer. Examples of framebuffer-attachable images include texture 918 images and renderbuffer images. Renderbuffers are described further 919 in section 4.4.2.1 920 921 By allowing the images of a renderbuffer to be attached to a 922 framebuffer, the GL provides a mechanism to support "off-screen" 923 rendering. Further, by allowing the images of a texture to be 924 attached to a framebuffer, the GL provides a mechanism to support 925 "render to texture". 926 927 4.4.1 Binding and Managing Framebuffer Objects 928 929 The operations described in chapter 4 affect the images attached to 930 the framebuffer object bound to the target FRAMEBUFFER_EXT. By 931 default, framebuffer bound to the target FRAMEBUFFER_EXT is zero, 932 specifying the default implementation dependent framebuffer provided 933 by the windowing system. When the framebuffer bound to target 934 FRAMEBUFFER_EXT is not zero, but instead names an 935 application-created framebuffer object, then the operations 936 described in chapter 4 affect the application-created framebuffer 937 object rather than the default framebuffer. 938 939 The namespace for framebuffer objects is the unsigned integers, with 940 zero reserved by the GL to refer to the default framebuffer. A 941 framebuffer object is created by binding an unused name to the 942 target FRAMEBUFFER_EXT. The binding is effected by calling 943 944 void BindFramebufferEXT(enum target, uint framebuffer); 945 946 with <target> set to FRAMEBUFFER_EXT and <framebuffer> set to the 947 unused name. The resulting framebuffer object is a new state 948 vector, comprising all the state values listed in table 4.nnn, as 949 well as one set of the state values listed in table 5.nnn for each 950 attachment point of the framebuffer. There are 951 MAX_COLOR_ATTACHMENTS_EXT color attachment points, plus one each for 952 the depth and stencil attachment points. 953 954 BindFramebufferEXT may also be used to bind an existing framebuffer 955 object to <target>. If the bind is successful no change is made to 956 the state of the bound framebuffer object and any previous binding 957 to <target> is broken. The current FRAMEBUFFER_EXT binding can be 958 queried using GetIntegerv(FRAMEBUFFER_BINDING_EXT). 959 960 While a framebuffer object is bound to the target FRAMEBUFFER_EXT, 961 GL operations on the target to which it is bound affect the images 962 attached to the bound framebuffer object, and queries of the target 963 to which it is bound return state from the bound object. In 964 particular, queries of the values specified in table 6.31 965 (Implementation Dependent Pixel Depths) and table 8.nnn 966 (Framebuffer-Dependent State Variables) are derived from the 967 currently bound framebuffer object. The framebuffer object bound to 968 the target FRAMEBUFFER_EXT is used as the destination of fragment 969 operations and as the source of pixel reads such as ReadPixels, as 970 described in chapter 4. 971 972 In the initial state, the reserved name zero is bound to the target 973 FRAMEBUFFER_EXT. There is no application-created framebuffer object 974 corresponding to the name zero. Instead, the name zero refers to 975 the window-system-provided framebuffer. All queries and operations 976 on the framebuffer while the name zero is bound to the target 977 FRAMEBUFFER_EXT operate on this default framebuffer. On some 978 implementations, the properties of the default 979 window-system-provided framebuffer can change over time (e.g., in 980 response to window-system events such as attaching the context to a 981 new window-system drawable.) 982 983 Application-created framebuffer objects (i.e., those with a non-zero 984 name) differ from the default window-system-provided framebuffer in 985 a few important ways. First and foremost, unlike the 986 window-system-provided framebuffer, application-created-framebuffers 987 have modifiable attachment points for each logical buffer in the 988 framebuffer. Framebuffer-attachable images can be attached to and 989 detached from these attachment points, which are described further 990 in section 4.4.2. Also, the size and format of the images attached 991 to application-created framebuffers are controlled entirely within 992 the GL interface, and are not affected by window-system events, such 993 as pixel format selection, window resizes, and display mode changes. 994 995 Additionally, when rendering to or reading from an application 996 created-framebuffer object, 997 998 - The pixel ownership test always succeeds. In other words, 999 application-created framebuffer objects own all of their 1000 pixels. 1001 1002 - There are no visible color buffer bitplanes. This means 1003 there is no color buffer corresponding to the back, front, 1004 left, or right color bitplanes. 1005 1006 - The only color buffer bitplanes are the ones defined by the 1007 framebuffer attachment points named COLOR_ATTACHMENT0_EXT 1008 through COLOR_ATTACHMENTn_EXT. 1009 1010 - The only depth buffer bitplanes are the ones defined by the 1011 framebuffer attachment point DEPTH_ATTACHMENT_EXT. 1012 1013 - The only stencil buffer bitplanes are the ones defined by 1014 the framebuffer attachment point STENCIL_ATTACHMENT_EXT. 1015 1016 - There is no multisample buffer so the value of the 1017 implementation-dependent state variables SAMPLES and 1018 SAMPLE_BUFFERS are both 0 1019 1020 - There are no accum buffer bitplanes, so the value of the 1021 implementation-dependent state variables ACCUM_RED_BITS, 1022 ACCUM_GREEN_BITS, ACCUM_BLUE_BITS, and ACCUM_ALPHA_BITS, are 1023 all zero. 1024 1025 - There are no AUX buffer bitplanes, so the value of the 1026 implementation-dependent state variable AUX_BUFFERS is zero. 1027 1028 Framebuffer objects are deleted by calling 1029 1030 void DeleteFramebuffersEXT(sizei n, uint *framebuffers); 1031 1032 <framebuffers> contains <n> names of framebuffer objects to be 1033 deleted. After a framebuffer object is deleted, it has no 1034 attachments, and its name is again unused. If a framebuffer that is 1035 currently bound to the target FRAMEBUFFER_EXT is deleted, it is as 1036 though BindFramebufferEXT had been executed with the <target> of 1037 FRAMEBUFFER_EXT and <framebuffer> of zero. Unused names in 1038 <framebuffers> are silently ignored, as is the value zero. 1039 1040 The command 1041 1042 void GenFramebuffersEXT(sizei n, uint *ids); 1043 1044 returns <n> previously unused framebuffer object names in <ids>. 1045 These names are marked as used, for the purposes of 1046 GenFramebuffersEXT only, but they acquire state and type only when 1047 they are first bound, just as if they were unused. 1048 1049 4.4.2 Attaching Images to Framebuffer Objects 1050 1051 Framebuffer-attachable images may be attached to, and detached from, 1052 application-created framebuffer objects. In contrast, the image 1053 attachments of the window-system-provided framebuffer may not be 1054 changed by the GL. 1055 1056 A single framebuffer-attachable image may be attached to multiple 1057 application-created framebuffer objects, potentially avoiding some 1058 data copies, and possibly decreasing memory consumption. 1059 1060 For each logical buffer, the framebuffer object stores a set of 1061 state which defines the logical buffer's "attachment point". The 1062 "attachment point" state contains enough information to identify the 1063 single image attached to the attachment point, or to indicate that 1064 no image is attached. The per-logical buffer "attachment point" 1065 state is listed in table 5.nnn 1066 1067 There are two types of framebuffer-attachable images: the image of a 1068 renderbuffer object, and an image of a texture object. 1069 1070 4.4.2.1 Renderbuffer Objects 1071 1072 A renderbuffer is a data storage object containing a single image of 1073 a renderable internal format. GL provides the methods described 1074 below to allocate and delete a renderbuffer's image, and to attach a 1075 renderbuffer's image to a framebuffer object. 1076 1077 The name space for renderbuffer objects is the unsigned integers, 1078 with zero reserved for the GL. A renderbuffer object is created by 1079 binding an unused name to RENDERBUFFER_EXT. The binding is effected 1080 by calling 1081 1082 void BindRenderbufferEXT( enum target, uint renderbuffer ); 1083 1084 with <target> set to RENDERBUFFER_EXT and <renderbuffer> set to the 1085 unused name. If <renderbuffer> is not zero, then the resulting 1086 renderbuffer object is a new state vector, initialized with a 1087 zero-sized memory buffer, and comprising the state values listed in 1088 Table 8.nnn. Any previous binding to <target> is broken. 1089 1090 BindRenderbufferEXT may also be used to bind an existing 1091 renderbuffer object. If the bind is successful, no change is made 1092 to the state of the newly bound renderbuffer object, and any 1093 previous binding to <target> is broken. 1094 1095 While a renderbuffer object is bound, GL operations on the target to 1096 which it is bound affect the bound renderbuffer object, and queries 1097 of the target to which a renderbuffer object is bound return state 1098 from the bound object. 1099 1100 The name zero is reserved. A renderbuffer object cannot be created 1101 with the name zero. If <renderbuffer> is zero, then any previous 1102 binding to <target> is broken and the <target> binding is restored 1103 to the initial state. 1104 1105 In the initial state, the reserved name zero is bound to 1106 RENDERBUFFER_EXT. There is no renderbuffer object corresponding to 1107 the name zero, so client attempts to modify or query renderbuffer 1108 state for the target RENDERBUFFER_EXT while zero is bound will 1109 generate GL errors, as described in section 6.1.3. 1110 1111 Using GetIntegerv, the current RENDERBUFFER_EXT binding can be 1112 queried as RENDERBUFFER_BINDING_EXT. 1113 1114 Renderbuffer objects are deleted by calling 1115 1116 void DeleteRenderbuffersEXT( sizei n, const uint *renderbuffers ); 1117 1118 where <renderbuffers> contains n names of renderbuffer objects to be 1119 deleted. After a renderbuffer object is deleted, it has no 1120 contents, and its name is again unused. If a renderbuffer that is 1121 currently bound to RENDERBUFFER_EXT is deleted, it is as though 1122 BindRenderbufferEXT had been executed with the <target> 1123 RENDERBUFFER_EXT and <name> of zero. Additionally, special care 1124 must be taken when deleting a renderbuffer if the image of the 1125 renderbuffer is attached to a framebuffer object. (See section 1126 4.4.2.2 for details). Unused names in <renderbuffers> are silently 1127 ignored, as is the value zero. 1128 1129 The command 1130 1131 void GenRenderbuffersEXT( sizei n, uint *renderbuffers ); 1132 1133 returns <n> previously unused renderbuffer object names in 1134 <renderbuffers>. These names are marked as used, for the purposes 1135 of GenRenderbuffersEXT only, but they acquire renderbuffer state 1136 only when they are first bound, just as if they were unused. 1137 1138 The command 1139 1140 void RenderbufferStorageEXT(enum target, enum internalformat, 1141 sizei width, sizei height); 1142 1143 establishes the data storage, format, and dimensions of a 1144 renderbuffer object's image. <target> must be RENDERBUFFER_EXT. 1145 <internalformat> must be color-renderable, depth-renderable, or 1146 stencil-renderable (as defined in section 4.4.4). <width> and 1147 <height> are the dimensions in pixels of the renderbuffer. If 1148 either <width> or <height> is greater than 1149 MAX_RENDERBUFFER_SIZE_EXT, the the error INVALID_VALUE is generated. 1150 If the GL is unable to create a data store of the requested size, 1151 the error OUT_OF_MEMORY is generated. RenderbufferStorageEXT deletes 1152 any existing data store for the renderbuffer and the contents of the 1153 data store after calling RenderbufferStorageEXT are undefined. 1154 1155 Sized Base S 1156 Internal Format Internal format Bits 1157 --------------- --------------- ---- 1158 STENCIL_INDEX1_EXT STENCIL_INDEX 1 1159 STENCIL_INDEX4_EXT STENCIL_INDEX 4 1160 STENCIL_INDEX8_EXT STENCIL_INDEX 8 1161 STENCIL_INDEX16_EXT STENCIL_INDEX 16 1162 ------------------------------------------------------------------ 1163 Table 2.nnn Desired component resolution for each sized internal 1164 format that can be used only with renderbuffers. 1165 1166 A GL implementation may vary its allocation of internal component 1167 resolution based on any RenderbufferStorage parameter (except 1168 target), but the allocation and chosen internal format must not be a 1169 function of any other state and cannot be changed once they are 1170 established. The actual resolution in bits of each component of the 1171 allocated image can be queried with GetRenderbufferParameteriv as 1172 described in section 6.1.3. 1173 1174 4.4.2.2 Attaching Renderbuffer Images to a Framebuffer 1175 1176 A renderbuffer can be attached as one of the logical buffers of the 1177 currently bound framebuffer object by calling 1178 1179 void FramebufferRenderbufferEXT(enum target, 1180 enum attachment, 1181 enum renderbuffertarget, 1182 uint renderbuffer); 1183 1184 <target> must be FRAMEBUFFER_EXT. INVALID_OPERATION is generated if 1185 the current value of FRAMEBUFFER_BINDING_EXT is zero when 1186 FramebufferRenderbufferEXT is called. <attachment> should be set to 1187 one of the attachment points of the framebuffer listed in table 1188 1.nnn. <renderbuffertarget> must be RENDERBUFFER_EXT and 1189 <renderbuffer> should be set to the name of the renderbuffer object 1190 to be attached to the framebuffer. <renderbuffer> must be either 1191 zero or the name of an existing renderbuffer object of type 1192 <renderbuffertarget>, otherwise INVALID_OPERATION is generated. If 1193 <renderbuffer> is zero, then the value of <renderbuffertarget> is 1194 ignored. 1195 1196 If <renderbuffer> is not zero and if FramebufferRenderbufferEXT is 1197 successful, then the renderbuffer named <renderbuffer> will be used 1198 as the logical buffer identified by <attachment> of the framebuffer 1199 currently bound to <target>. The value of 1200 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT for the specified attachment 1201 point is set to RENDERBUFFER_EXT and the value of 1202 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is set to <renderbuffer>. All 1203 other state values of the attachment point specified by <attachment> 1204 are set to their default values listed in table 5.nnn. No change is 1205 made to the state of the renderbuffer object and any previous 1206 attachment to the <attachment> logical buffer of the framebuffer 1207 object bound to framebuffer <target> is broken. If, on the other 1208 hand, the attachment is not successful, then no change is made to 1209 the state of either the renderbuffer object or the framebuffer 1210 object. 1211 1212 Calling FramebufferRenderbufferEXT with the <renderbuffer> name zero 1213 will detach the image, if any, identified by <attachment>, in the 1214 framebuffer currently bound to <target>. All state values of the 1215 attachment point specified by <attachment> in the object bound to 1216 <target> are set to their default values listed in table 5.nnn. 1217 1218 If a renderbuffer object is deleted while its image is attached to 1219 one or more attachment points in the currently bound framebuffer, 1220 then it is as if FramebufferRenderbufferEXT() had been called, with 1221 a <renderbuffer> of 0, for each attachment point to which this image 1222 was attached in the currently bound framebuffer. In other words, 1223 this renderbuffer image is first detached from all attachment points 1224 in the currently bound framebuffer. Note that the renderbuffer 1225 image is specifically *not* detached from any non-bound 1226 framebuffers. Detaching the image from any non-bound framebuffers 1227 is the responsibility of the application. 1228 1229 Name of attachment 1230 -------------------------------------------------------------------------------------- 1231 COLOR_ATTACHMENT0_EXT ... COLOR_ATTACHMENTn_EXT (where n is from 0 to MAX_COLOR_ATTACHMENTS_EXT-1) 1232 DEPTH_ATTACHMENT_EXT 1233 STENCIL_ATTACHMENT_EXT 1234 -------------------------------------------------------------------------------------- 1235 Table 1.nnn: "List of framebuffer attachment points" 1236 1237 4.4.2.3 Attaching Texture Images to a Framebuffer 1238 1239 GL supports copying the rendered contents of the framebuffer into 1240 the images of a texture object through the use of the routines 1241 CopyTexImage{1D|2D}, and CopyTexSubImage{1D|2D|3D}. Additionally, 1242 GL supports rendering directly into the images of a texture object. 1243 1244 To render directly into a texture image, a specified image from a 1245 texture object can be attached as one of the logical buffers of the 1246 currently bound framebuffer object by calling one of the following 1247 routines, depending on the type of the texture: 1248 1249 void FramebufferTexture1DEXT(enum target, enum attachment, 1250 enum textarget, uint texture, 1251 int level); 1252 void FramebufferTexture2DEXT(enum target, enum attachment, 1253 enum textarget, uint texture, 1254 int level); 1255 void FramebufferTexture3DEXT(enum target, enum attachment, 1256 enum textarget, uint texture, 1257 int level, int zoffset); 1258 1259 In all three routines, <target> must be FRAMEBUFFER_EXT. 1260 INVALID_OPERATION is generated if the current value of 1261 FRAMEBUFFER_BINDING_EXT is zero when FramebufferTexture{1D|2D|3D}EXT 1262 is called. <attachment> must be one of the attachment points of the 1263 framebuffer listed in table 1.nnn. 1264 1265 In all three routines, if <texture> is zero, then <textarget>, 1266 <level>, and <zoffset> are ignored. If <texture> is not zero, then 1267 <texture> must either name an existing texture object with a target 1268 of <textarget>, or <texture> must name an existing cube map texture 1269 and <textarget> must be one of: TEXTURE_CUBE_MAP_POSITIVE_X, 1270 TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, 1271 TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_Y, or 1272 TEXTURE_CUBE_MAP_NEGATIVE_Z. Otherwise, GL_INVALID_OPERATION is 1273 generated. 1274 1275 <level> specifies the mipmap level of the texture image to be 1276 attached to the framebuffer. 1277 1278 If <textarget> is TEXTURE_RECTANGLE_ARB, then <level> must be zero. 1279 If <textarget> is TEXTURE_3D, then <level> must be greater than or 1280 equal to zero and less than or equal to log base 2 of 1281 MAX_3D_TEXTURE_SIZE. If <textarget> is one of 1282 TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, 1283 TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X, 1284 TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z, then 1285 <level> must be greater than or equal to zero and less than or equal 1286 to log base 2 of MAX_CUBE_MAP_TEXTURE_SIZE. For all other values of 1287 <textarget>, <level> must be greater than or equal to zero and no 1288 larger than log base 2 of MAX_TEXTURE_SIZE. Otherwise, 1289 INVALID_VALUE is generated. 1290 1291 <zoffset> specifies the z-offset of a 2-dimensional image within a 1292 3-dimensional texture. INVALID_VALUE is generated if <zoffset> is 1293 larger than MAX_3D_TEXTURE_SIZE-1. 1294 1295 For FramebufferTexture1DEXT, if <texture> is not zero, then 1296 <textarget> must be TEXTURE_1D. 1297 1298 For FramebufferTexture2DEXT, if <texture> is not zero, then 1299 <textarget> must be one of: TEXTURE_2D, TEXTURE_RECTANGLE_ARB, 1300 TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, 1301 TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X, 1302 TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z. 1303 1304 For FramebufferTexture3DEXT, if <texture> is not zero, then 1305 <textarget> must be TEXTURE_3D. 1306 1307 If <texture> is not zero, and if FramebufferTexture{1D|2D|3D}EXT is 1308 successful, then the specified texture image will be used as the 1309 logical buffer identified by <attachment> of the framebuffer 1310 currently bound to <target>. The value of 1311 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT for the specified attachment 1312 point is set to TEXTURE and the value of 1313 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is set to <texture>. 1314 Additionally, the value of FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL for 1315 the named attachment point is set to <level>. If <texture> is a 1316 cubemap texture then, the value of 1317 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE the named attachment 1318 point is set to <textarget>. If <texture> is a 3D texture, then the 1319 value of FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET for the named 1320 attachment point is set to <zoffset>. All other state values of the 1321 attachment point specified by <attachment> are set to their default 1322 values listed in table 5.nnn. No change is made to the state of the 1323 texture object, and any previous attachment to the <attachment> 1324 logical buffer of the framebuffer object bound to framebuffer 1325 <target> is broken. If, on the other hand, the attachment is not 1326 successful, then no change is made to the state of either the 1327 texture object or the framebuffer object. 1328 1329 Calling FramebufferTexture{1D|2D|3D}EXT with <texture> name zero 1330 will detach the image identified by <attachment>, if any, in the 1331 framebuffer currently bound to <target>. All state values of the 1332 attachment point specified by <attachment> are set to their default 1333 values listed in table 5.nnn. 1334 1335 If a texture object is deleted while its image is attached to one or 1336 more attachment points in the currently bound framebuffer, then it 1337 is as if FramebufferTexture{1D|2D|3D}EXT() had been called, with a 1338 <texture> of 0, for each attachment point to which this image was 1339 attached in the currently bound framebuffer. In other words, this 1340 texture image is first detached from all attachment points in the 1341 currently bound framebuffer. Note that the texture image is 1342 specifically *not* detached from any other framebuffer objects. 1343 Detaching the texture image from any other framebuffer objects is 1344 the responsibility of the application. 1345 1346 4.4.3 Rendering When an Image of a Bound Texture Object is Also 1347 Attached to the Framebuffer 1348 1349 Special precautions need to be taken to avoid attaching a texture 1350 image to the currently bound framebuffer while the texture object is 1351 currently bound and enabled for texturing. Doing so could lead to 1352 the creation of a "feedback loop" between the writing of pixels by 1353 the GL's rendering operations and the simultaneous reading of those 1354 same pixels when used as texels in the currently bound texture. In 1355 this scenario, the framebuffer will be considered framebuffer 1356 complete (see section 4.4.4), but the values of fragments rendered 1357 while in this state will be undefined. The values of texture 1358 samples may be undefined as well, as described in section 3.8.8. 1359 1360 Specifically, the values of rendered fragments are undefined if all 1361 of the following conditions are true: 1362 1363 - an image from texture object <T> is attached to the currently 1364 bound framebuffer at attachment point <A>, and 1365 1366 - the texture object <T> is currently bound to a texture unit 1367 <U>, and 1368 1369 - the current fixed-function texture state or programmable 1370 vertex and/or fragment processing state makes it possible(*) 1371 to sample from the texture object <T> bound to texture unit 1372 <U> 1373 1374 while either of the following conditions are true: 1375 1376 - the value of TEXTURE MIN FILTER for texture object <T> is 1377 NEAREST or LINEAR, and the value of 1378 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT for attachment point 1379 <A> is equal to the value of TEXTURE_BASE_LEVEL for the 1380 texture object <T>, or 1381 1382 - the value of TEXTURE_MIN_FILTER for texture object <T> is one 1383 of NEAREST_MIPMAP_NEAREST, NEAREST_MIPMAP LINEAR, LINEAR 1384 MIPMAP_NEAREST, or LINEAR_MIPMAP_LINEAR, and the value of 1385 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT for attachment point 1386 <A> is within the the range specified by the current values of 1387 TEXTURE_BASE_LEVEL to q, inclusive, for the texture object 1388 <T>. (q is defined in the Mipmapping discussion of section 1389 3.8.8), 1390 1391 (*) For the purpose of this discussion, we consider it "possible" 1392 to sample from the texture object <T> bound to texture unit <U>" 1393 if any of the following are true: 1394 1395 - programmable vertex and fragment processing is disabled 1396 and the target of texture object <T> is enabled according 1397 to the texture target precedence rules of section 3.8.15, 1398 or 1399 - if FRAGMENT_PROGRAM_ARB is enabled and the currently bound 1400 fragment program contains any instructions that 1401 sample from the texture object <T> bound to <U>, 1402 or 1403 - if the active fragment or vertex shader contains 1404 any instructions that might sample from the texture object <T> bound 1405 to <U> if even those instructions might only be executed 1406 conditionally. 1407 1408 Note that if TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL exclude any 1409 levels containing image(s) attached to the currently bound 1410 framebuffer, then the above conditions will not be met, (i.e., the 1411 above rule will not cause the values of rendered fragments to be 1412 undefined.) 1413 1414 4.4.4 Framebuffer Completeness 1415 1416 A framebuffer object is said to be "framebuffer complete" if all of 1417 its attached images, and all framebuffer parameters required to 1418 utilize the framebuffer for rendering and reading, are consistently 1419 defined and meet the requirements defined below. The rules of 1420 framebuffer completeness are dependent on the properties of the 1421 attached images, and on certain implementation dependent 1422 restrictions. A framebuffer must be complete to effectively be used 1423 as the destination for GL framebuffer rendering operations and the 1424 source for GL framebuffer read operations. 1425 1426 The internal formats of the attached images can affect the 1427 completeness of the framebuffer, so it is useful to first define the 1428 relationship between the internal format of an image and the 1429 attachment points to which it can be attached. 1430 1431 * The following base internal formats from table 3.15 are 1432 "color-renderable": RGB, RGBA, FLOAT_R_NV, FLOAT_RG_NV, 1433 FLOAT_RGB_NV, and FLOAT_RGBA_NV. The sized internal formats 1434 from table 3.16 that have a color-renderable base internal 1435 format are also color-renderable. No other formats, including 1436 compressed internal formats, are color-renderable. 1437 1438 * An internal format is "depth-renderable" if it is 1439 DEPTH_COMPONENT, or if it is one of the sized internal formats 1440 from table 3.16 that has a depth-renderable base internal 1441 format. No other formats are depth-renderable. 1442 1443 * An internal format is "stencil-renderable" if it is 1444 STENCIL_INDEX, or if it is one of the sized internal formats 1445 from table 2.nnn that has a stencil-renderable base internal 1446 format. No other formats are stencil-renderable. 1447 1448 4.4.4.1 Framebuffer Attachment Completeness 1449 1450 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT for the 1451 framebuffer attachment point <attachment> is not NONE, then it is 1452 said that a framebuffer-attachable image, named <image>, is attached 1453 to the framebuffer at the attachment point. <image> is identified 1454 by the state in <attachment> as described in section 4.4.2. 1455 1456 The framebuffer attachment point <attachment> is said to be 1457 "framebuffer attachment complete" if the value of 1458 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT for <attachment> is NONE 1459 (i.e., no image is attached), or if all of the following conditions 1460 are true: 1461 1462 * <image> is a component of an existing object with the name 1463 specified by FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, and of the 1464 type specified by FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT. 1465 1466 * The width and height of <image> must be non-zero. 1467 1468 * If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and 1469 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a 3-dimensional 1470 texture, then FRAMEBUFFER_ATTACHMENT_TEXTURE_ZOFFSET_EXT must be 1471 smaller than the depth of the texture. 1472 1473 * If <attachment> is one of COLOR_ATTACHMENT0_EXT through 1474 COLOR_ATTACHMENTn_EXT, then <image> must have a color-renderable 1475 internal format. 1476 1477 * If <attachment> is DEPTH_ATTACHMENT_EXT, then <image> must have 1478 a depth-renderable internal format. 1479 1480 * If <attachment> is STENCIL_ATTACHMENT_EXT, then <image> must 1481 have a stencil-renderable internal format. 1482 1483 4.4.4.2 Framebuffer Completeness 1484 1485 In this subsection, each rule is followed by an error enum enclosed 1486 in { brackets }. Sections 4.4.4.2 and 4.4.4.3 explains the 1487 relevance of the error enums. 1488 1489 The framebuffer object <target> is said to be "framebuffer complete" 1490 if it is the window-system-provided framebuffer, or if all the 1491 following conditons are true: 1492 1493 * All framebuffer attachment points are "framebuffer attachment 1494 complete". 1495 { FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT } 1496 1497 * There is at least one image attached to the framebuffer. 1498 { FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT_EXT } 1499 1500 * All attached images have the same width and height. 1501 { FRAMEBUFFER_INCOMPLETE_DIMENSIONS_EXT } 1502 1503 * All images attached to the attachment points 1504 COLOR_ATTACHMENT0_EXT through COLOR_ATTACHMENTn_EXT must have 1505 the same internal format. 1506 { FRAMEBUFFER_INCOMPLETE_FORMATS_EXT } 1507 1508 * The value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT must not be 1509 NONE for any color attachment point(s) named by DRAW_BUFFERi. 1510 { FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER_EXT } 1511 1512 * If READ_BUFFER is not NONE, then the value of 1513 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT must not be NONE for the 1514 color attachment point named by READ_BUFFER. 1515 { FRAMEBUFFER_INCOMPLETE_READ_BUFFER_EXT } 1516 1517 * The combination of internal formats of the attached 1518 images does not violate an implementation-dependent set of 1519 restrictions. 1520 { FRAMEBUFFER_UNSUPPORTED_EXT } 1521 1522 The enum in { brackets } after each clause of the framebuffer 1523 completeness rules specifies the return value of 1524 CheckFramebufferStatusEXT (see below) that is generated when that 1525 clause is violated. If more than one clause is violated, it is 1526 implementation-dependent exactly which enum will be returned by 1527 CheckFramebufferStatusEXT. 1528 1529 Performing any of the following actions may change whether the 1530 framebuffer is considered complete or incomplete. 1531 1532 - Binding to a different framebuffer with BindFramebufferEXT. 1533 1534 - Attaching an image to the framebuffer with 1535 FramebufferTexture{1D|2D|3D}EXT or FramebufferRenderbufferEXT. 1536 1537 - Detaching an image from the framebuffer with 1538 FramebufferTexture{1D|2D|3D}EXT or FramebufferRenderbufferEXT. 1539 1540 - Changing the width, height, or internal format of a texture 1541 image that is attached to the framebuffer by calling 1542 {Copy|Compressed}TexImage{1D|2D|3D}. 1543 1544 - Changing the width, height, or internal format of a renderbuffer 1545 that is attached to the framebuffer by calling 1546 RenderbufferStorageEXT. 1547 1548 - Deleting, with DeleteTextures or DeleteRenderbuffers, an object 1549 containing an image that is attached to a framebuffer object 1550 that is bound to the framebuffer. 1551 1552 - Changing READ_BUFFER or one of the DRAW_BUFFERS. 1553 1554 Although GL defines a wide variety of internal formats for 1555 framebuffer-attachable images, such as texture images and 1556 renderbuffer images, some implementations may not support rendering 1557 to particular combinations of internal formats. If the combination 1558 of formats of the images attached to a framebuffer object are not 1559 supported by the implementation, then the framebuffer is not 1560 complete under the clause labeled FRAMEBUFFER_UNSUPPORTED_EXT. There 1561 must exist, however, at least one combination of internal formats 1562 for which the framebuffer cannot be FRAMEBUFFER_UNSUPPORTED_EXT. 1563 1564 Because of the "implementation-dependent" clause of the framebuffer 1565 completeness test in particular, and because framebuffer 1566 completeness can change when the set of attached images is modified, 1567 it is strongly advised, though is not required, that an application 1568 check to see if the framebuffer is complete prior to rendering. The 1569 status of the framebuffer object currently bound to <target> can be 1570 queried by calling 1571 1572 enum CheckFramebufferStatusEXT(enum target); 1573 1574 If <target> is not FRAMEBUFFER_EXT, INVALID_ENUM is generated. If 1575 CheckFramebufferStatusEXT is called within a Begin/End pair, 1576 INVALID_OPERATION is generated. If CheckFramebufferStatusEXT 1577 generates an error, 0 is returned. 1578 1579 Otherwise, an enum is returned that identifies whether 1580 or not the framebuffer bound to <target> is complete, and if not 1581 complete the enum identifies one of the rules of framebuffer 1582 completeness that is violated. If the framebuffer is complete, then 1583 FRAMEBUFFER_COMPLETE_EXT is returned. 1584 1585 4.4.4.3 Effects of Framebuffer Completeness on Framebuffer Operations 1586 1587 If the currently bound framebuffer is not framebuffer complete, then 1588 it is an error to attempt to use the framebuffer for writing or 1589 reading. This means that rendering commands such as Begin, 1590 RasterPos, any command that performs an implicit Begin, as well as 1591 commands that read the framebuffer such as ReadPixels and 1592 CopyTex{Sub}Image will generate the error 1593 INVALID_FRAMEBUFFER_OPERATION_EXT if called while the framebuffer is 1594 not framebuffer complete. 1595 1596 4.4.5 Effects of Framebuffer State on Framebuffer Dependent Values 1597 1598 The values of the state variables listed in table 9.nnn (Framebuffer 1599 Dependent Values) may change when a change is made to 1600 FRAMEBUFFER_BINDING_EXT, to the state of the currently bound 1601 framebuffer object, or to an image attached to the currently bound 1602 framebuffer object. 1603 1604 When FRAMEBUFFER_BINDING_EXT is zero, the values of the state 1605 variables listed in table 9.nnn are implementation defined. 1606 1607 When FRAMEBUFFER_BINDING_EXT is non-zero, if the currently bound 1608 framebuffer object is not framebuffer complete, then the values of 1609 the state variables listed in table 9.nnn are undefined. 1610 1611 When FRAMEBUFFER_BINDING_EXT is non-zero and the currently bound 1612 framebuffer object is framebuffer complete, then the values of the 1613 state variables listed in table 9.nnn are completely determined by 1614 FRAMEBUFFER_BINDING_EXT, the state of the currently bound 1615 framebuffer object, and the state of the images attached to the 1616 currently bound framebuffer object. 1617 1618XXX [from jon leech] describe derivation of red green and blue size 1619 1620 1621 4.4.6 Mapping between Pixel and Element in Attached Image 1622 1623 When FRAMEBUFFER_BINDING_EXT is non-zero, an operation that writes 1624 to the framebuffer modifies the image attached to the selected 1625 logical buffer, and an operation that reads from the framebuffer 1626 reads from the image attached to the selected logical buffer. 1627 1628 If the attached image is a renderbuffer image, then the window 1629 coordinates (x[w], y[w]) corresponds to the value in the 1630 renderbuffer image at the same coordinates. 1631 1632 If the attached image is a texture image, then the window 1633 coordinates (x[w], y[w]) correspond to the texel (i, j, k), from 1634 figure 3.10, as follows: 1635 1636 i = (x[w] - b) 1637 1638 j = (y[w] - b) 1639 1640 k = (zoffset - b) 1641 1642 where b is the texture image's border width, and zoffset is the 1643 value of FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET for the selected 1644 logical buffer. For a two-dimensional texture, k and zoffset are 1645 irrelevant; for a one-dimensional texture, j, k, and zoffset are 1646 both irrelevant. 1647 1648 (x[w], y[w]) corresponds to a border texel if x[w] or y[w] or 1649 zoffset is less than the border size, or if x[w] or y[w] or zoffset 1650 is greater than the border size plus the width or height or depth, 1651 resp., of the texture image. 1652 1653 Conversion to Framebuffer-Attachable Image Components 1654 1655 When an enabled color value is written to the framebuffer while 1656 FRAMEBUFFER_BINDING is non-zero, for each draw buffer the R, G, B, 1657 and A values are converted to internal components as described in 1658 table 3.15, according to the table row corresponding to the internal 1659 format of the framebuffer-attachable image attached to the selected 1660 logical buffer, and the resulting internal components are written to 1661 the image attached to logical buffer. The masking operations 1662 described in section 4.2.2 are also effective. 1663 1664 Conversion to RGBA Values 1665 1666 When a color value is read or is used as the source of a logical 1667 operation or blending, while FRAMEBUFFER_BINDING is non-zero, the 1668 components of the framebuffer-attachable image that is attached to 1669 the logical buffer selected by READ_BUFFER are first converted to R, 1670 G, B, and A values according to table 3.21 and the internal format 1671 of the attached image." 1672 1673Additions to Chapter 5 of the OpenGL 1.5 Specification (Special Functions) 1674 1675 Added to section 5.4, as part of the discussion of which commands 1676 are not compiled into display lists: 1677 1678 "Certain commands, when called while compiling a display list, are 1679 not compiled into the display list but are executed immediately. 1680 These are: ..., GenFramebuffersEXT, BindFramebufferEXT, 1681 DeleteFramebuffersEXT, CheckFramebufferStatusEXT, 1682 GenRenderbuffersEXT, BindRenderbufferEXT, DeleteRenderbuffersEXT, 1683 RenderbufferStorageEXT, FramebufferTexture1DEXT, 1684 FramebufferTexture2DEXT, FramebufferTexture3DEXT, 1685 FramebufferRenderbufferEXT, GenerateMipmapEXT..." 1686 1687Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State 1688Requests) 1689 1690 Add to section 6.1.3, Enumerated Queries: 1691 1692 In the list of state query functions, add: 1693 1694 "void GetFramebufferAttachmentParameterivEXT(enum target, 1695 enum attachment, 1696 enum pname, 1697 int *params); 1698 1699 <target> must be FRAMEBUFFER_EXT. <attachment> must be one 1700 of the attachment points of the framebuffer listed in table 1701 1.nnn. <pname> must be one of the following: 1702 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT, 1703 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, 1704 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT, 1705 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT, 1706 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT. 1707 1708 If the framebuffer currently bound to <target> is zero, then 1709 INVALID_OPERATION is generated. 1710 1711 Upon successful return from 1712 GetFramebufferAttachmentParameterivEXT, if <pname> is 1713 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT, then param will 1714 contain one of NONE, TEXTURE, or RENDERBUFFER_EXT, 1715 identifying the type of object which contains the attached 1716 image. 1717 1718 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is 1719 RENDERBUFFER_EXT, then 1720 1721 If <pname> is FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, 1722 <params> will contain the name of the renderbuffer 1723 object which contains the attached image. 1724 1725 Otherwise, INVALID_ENUM is generated. 1726 1727 If the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is 1728 TEXTURE, then 1729 1730 If <pname> is FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, 1731 then <params> will contain the name of the texture 1732 object which contains the attached image. 1733 1734 If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT, 1735 then <params> will contain the mipmap level of the 1736 texture object which contains the attached image. 1737 1738 If <pname> is 1739 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT and the 1740 texture object named 1741 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is a cube map 1742 texture, then <params> will contain the cube map face of 1743 the cubemap texture object which contains the attached 1744 image. Otherwise <params> will contain the value zero. 1745 1746 If <pname> is 1747 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT and the 1748 texture object named 1749 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is a 1750 3-dimensional texture, then <params> will contain the 1751 zoffset of the 2D image of the 3D texture object which 1752 contains the attached image. Otherwise <params> will 1753 contain the value zero. 1754 1755 Otherwise, INVALID_ENUM is generated. 1756 1757 void GetRenderbufferParameterivEXT(enum target, enum pname, 1758 int* params); 1759 1760 <target> must be RENDERBUFFER_EXT. <pname> must be one of 1761 the symbolic values in table 8.nnn. 1762 1763 If the renderbuffer currently bound to <target> is zero, 1764 then INVALID_OPERATION is generated. 1765 1766 Upon successful return from GetRenderbufferParameterivEXT, 1767 if <pname> is RENDERBUFFER_WIDTH_EXT, 1768 RENDERBUFFER_HEIGHT_EXT, or 1769 RENDERBUFFER_INTERNAL_FORMAT_EXT, then <params> will contain 1770 the width in pixels, height in pixels, or internal format, 1771 respectively, of the image of the renderbuffer currently 1772 bound to <target>. 1773 1774 Upon successful return from GetRenderbufferParameterivEXT, 1775 if <pname> is RENDERBUFFER_RED_SIZE_EXT, 1776 RENDERBUFFER_GREEN_SIZE_EXT, RENDERBUFFER_BLUE_SIZE_EXT, 1777 RENDERBUFFER_ALPHA_SIZE_EXT, RENDERBUFFER_DEPTH_SIZE_EXT, or 1778 RENDERBUFFER_STENCIL_SIZE_EXT, then <params> will contain 1779 the actual resolutions, (not the resolutions specified when 1780 the image array was defined), for the red, green, blue, 1781 alpha depth, or stencil components, respectively, of the 1782 image of the renderbuffer currently bound to <target>. 1783 1784 Otherwise, INVALID_ENUM is generated." 1785 1786 After section 6.1.13 and before section 6.1.14 (which should be 1787 renumbered 6.1.16), add two new sections: 1788 1789 6.1.14 Framebuffer Object Queries 1790 1791 The command 1792 1793 boolean IsFramebufferEXT( uint framebuffer ); 1794 1795 returns TRUE if <framebuffer> is the name of a framebuffer 1796 object. If <framebuffer> is zero, or if <framebuffer> is a 1797 non-zero value that is not the name of a framebuffer object, 1798 IsFramebufferEXT return FALSE. 1799 1800 6.1.15 Renderbuffer Object Queries 1801 1802 The command 1803 1804 boolean IsRenderbufferEXT( uint renderbuffer ); 1805 1806 returns TRUE if <renderbuffer> is the name of a renderbuffer 1807 object. If <renderbuffer> is zero, or if <renderbuffer> is a 1808 non-zero value that is not the name of a renderbuffer object, 1809 IsRenderbufferEXT return FALSE. 1810 1811 1812Errors 1813 1814 The error INVALID_OPERATION is generated if FRAMEBUFFER_BINDING_EXT 1815 is zero and DrawBuffer or DrawBuffers is called with a <buf> 1816 constant (other than NONE) that does not correspond to a buffer 1817 allocated to the GL by the window-system, including the constants 1818 COLOR_ATTACHMENT0_EXT through COLOR_ATTACHMENTn_EXT, where n is 1819 MAX_COLOR_ATTACHMENTS_EXT - 1. 1820 1821 The error INVALID_OPERATION is generated if FRAMEBUFFER_BINDING_EXT 1822 is non-zero and DrawBuffer, DrawBuffers, or ReadBuffer is called 1823 with a <buf> constant (other than NONE) that is not in the range 1824 COLOR_ATTACHMENT0_EXT through COLOR_ATTACHMENTn_EXT, where n is 1825 MAX_COLOR_ATTACHMENTS_EXT - 1. 1826 1827 The error INVALID_ENUM is generated if DrawBuffer or ReadBuffer is 1828 called with a <buf> constant that is not listed in table 4.4 or 1829 10.nnn. 1830 1831 The error INVALID_ENUM is generated if DrawBuffers is called with a 1832 <buf> constant that is not listed in table 10.nnn or 11.nnn. 1833 1834 The error INVALID_FRAMEBUFFER_OPERATION_EXT is generated if the 1835 value of FRAMEBUFFER_STATUS_EXT is not FRAMEBUFFER_COMPLETE_EXT when 1836 any attempts to render to or read from the framebuffer are made. 1837 1838 The error INVALID_OPERATION is generated if 1839 GetFramebufferAttachmentParameterivEXT is called while the value of 1840 FRAMEBUFFER_BINDING_EXT is zero. 1841 1842 The error INVALID_OPERATION is generated if 1843 FramebufferRenderbufferEXT or FramebufferTexture{1D|2D|3D}EXT is 1844 called while the value of FRAMEBUFFER_BINDING_EXT is zero. 1845 1846 The error INVALID_OPERATION is generated if RenderbufferStorageEXT 1847 or GetRenderbufferParameterivEXT is called while the value of 1848 RENDERBUFFER_BINDING_EXT is zero. 1849 1850 The error INVALID_ENUM is generated if 1851 GetFramebufferAttachmentParameterivEXT is called with an 1852 <attachment> other than COLOR_ATTACHMENT0_EXT through 1853 COLOR_ATTACHMENTn_EXT, where n is MAX_COLOR_ATTACHMENTS_EXT - 1. 1854 1855 The error INVALID_ENUM is generated if 1856 GetFramebufferAttachmentParameterivEXT is called with a <pname> 1857 other than FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT when the type of 1858 the attached object at the named attachment point is 1859 RENDERBUFFER_EXT. 1860 1861 The error INVALID_ENUM is generated if 1862 GetFramebufferAttachmentParameterivEXT is called with a <pname> 1863 other than FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, 1864 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT, 1865 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT, or 1866 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT when the type of the 1867 attached object at the named attachment point is TEXTURE. 1868 1869 The error INVALID_ENUM is generated if GetRenderbufferParameterivEXT 1870 is called with a <pname> other than RENDERBUFFER_WIDTH_EXT, 1871 RENDERBUFFER_HEIGHT_EXT, or RENDERBUFFER_INTERNAL_FORMAT_EXT, 1872 GL_RENDERBUFFER_RED_SIZE, GL_RENDERBUFFER_GREEN_SIZE, 1873 GL_RENDERBUFFER_BLUE_SIZE, GL_RENDERBUFFER_ALPHA_SIZE, 1874 GL_RENDERBUFFER_DEPTH_SIZE, or GL_RENDERBUFFER_STENCIL_SIZE. 1875 1876 The error INVALID_VALUE is generated if RenderbufferStorageEXT is 1877 called with a <width> or <height> that is greater than 1878 MAX_RENDERBUFFER_SIZE_EXT. 1879 1880 The error INVALID_ENUM is generated if RenderbufferStorageEXT is 1881 called with an <internalformat> that is not RGB, RGBA, 1882 DEPTH_COMPONENT, STENCIL_INDEX, or one of the internal formats from 1883 table 3.16 or table 2.nnn that has a base internal format of RGB, 1884 RGBA, DEPTH_COMPONENT, or STENCIL_INDEX. 1885 1886 The error INVALID_OPERATION is generated if 1887 FramebufferRenderbufferEXT is called and <renderbuffer> is not the 1888 name of a renderbuffer object or zero. 1889 1890 The error INVALID_OPERATION is generated if 1891 FramebufferTexture{1D|2D|3D}EXT is called and <texture> is not the 1892 name of a texture object or zero. 1893 1894 The error INVALID_VALUE is generated if 1895 FramebufferTexture{1D|2D|3D}EXT is called with a <level> that is 1896 less than zero and <texture> is not zero. 1897 1898 The error INVALID_VALUE is generated if FramebufferTexture2DEXT is 1899 called with a <level> that is not zero and <textarget> is 1900 TEXTURE_RECTANGLE_ARB and <texture> is not zero. 1901 1902 The error INVALID_VALUE is generated if FramebufferTexture{1D|2D}EXT 1903 is called with a <level> that is greater than the log base 2 of 1904 MAX_TEXTURE_SIZE and <texture> is respectively a non-zero 1D or 2D 1905 texture object name. 1906 1907 The error INVALID_VALUE is generated if FramebufferTexture2DEXT 1908 is called with a <level> that is greater than the log base 2 of 1909 MAX_CUBE_MAP_TEXTURE_SIZE and <texture> is a non-zero cubemap 1910 texture object name. 1911 1912 The error INVALID_VALUE is generated if FramebufferTexture3DEXT is 1913 called with a <level> greater than the log base 2 of the 1914 MAX_3D_TEXTURE_SIZE and <texture> is not zero. 1915 1916 The error INVALID_VALUE is generated if FramebufferTexture3DEXT is 1917 called with a <zoffset> that is larger than MAX_3D_TEXTURE_SIZE-1 1918 and <texture> is not zero. 1919 1920 The error INVALID_ENUM is generated if CheckFramebufferStatusEXT is 1921 called and <target> is not FRAMEBUFFER_EXT. 1922 1923 The error INVALID_OPERATION is generated if 1924 CheckFramebufferStatusEXT is called within a Begin/End pair. 1925 1926 The error OUT_OF_MEMORY is generated if the GL is unable to create a 1927 data store of the required size when calling RenderbufferStorageEXT. 1928 1929 The error INVALID_OPERATION is generated if GenerateMipmapEXT is 1930 called with a <target> of TEXTURE_CUBE_MAP and the texture object 1931 currently bound to TEXTURE_CUBE_MAP is not "cube complete" as 1932 defined in section 3.8.10 1933 1934New State 1935 1936 (add new table 3.nnn, "Framebuffer (state per framebuffer target binding point)") 1937 1938 Get Value Type Get Command Initial Value Description Section Attribute 1939 ------------------------------- ------ ------------- -------------- -------------------- ------------ --------- 1940 FRAMEBUFFER_BINDING_EXT Z GetIntegerv 0 name of framebuffer 4.4.1 - 1941 object bound to 1942 FRAMEBUFFER_EXT 1943 target 1944 1945 (insert new table 4.nnn, "Framebuffer (state per framebuffer object)") 1946 1947 Get Value Type Get Command Initial Value Description Section Attribute 1948 ---------------- ------ ------------- ------------- -------------------- ------------ --------- 1949 DRAW_BUFFERi [1] 1 + xZ(10*) GetIntegerv see 4.2.1 draw buffer selected 4.2.1 color-buffer 1950 for color output i 1951 READ_BUFFER [2] Z(3) GetIntegerv see 4.3.2 read source 4.3.2 pixel 1952 1953 [1] prior to this extension, the DRAW_BUFFERi state was described in table 6.21 "Framebuffer Control" (of OpenGL 2.0 spec) 1954 [2] prior to this extension, the READ_BUFFER state was described in table 6.26 "Pixel" (of OpenGL 2.0 spec) 1955 1956 1957 1958 (insert new table 5.nnn, "Framebuffer (state per framebuffer object attachment point)") 1959 1960 Get Value Type Get Command Initial Value Description Section Attribute 1961 ------------------------------- ------ ------------- ------------- -------------------- ------------ --------- 1962 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT Z GetFramebufferAttachmentParameterivEXT NONE type of 4.4.2.2 and - 1963 image attached to 4.4.2.3 1964 framebuffer attachment 1965 point 1966 1967 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT Z GetFramebufferAttachmentParameterivEXT 0 name of object 4.4.2.2 and - 1968 attached to 4.4.2.3 1969 framebuffer attachment 1970 point 1971 1972 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT Z GetFramebufferAttachmentParameterivEXT 0 mipmap level of 4.4.2.2 and - 1973 texture image 4.4.2.3 1974 attached, if object 1975 attached is texture. 1976 1977 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT Z+ GetFramebufferAttachmentParameterivEXT TEXTURE_ cubemap face of 4.4.2.2 and - 1978 CUBE_MAP_ texture image 4.4.2.3 1979 POSITIVE_X attached, if object 1980 attached is cubemap 1981 texture. 1982 1983 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT Z GetFramebufferAttachmentParameterivEXT 0 zoffset of 4.4.2.2 and - 1984 texture image 4.4.2.3 1985 attached, if object 1986 attached is 3D 1987 texture. 1988 1989 1990 1991 (insert new table 7.nnn, "Renderbuffers (state per renderbuffer target and binding point)") 1992 1993 Get Value Type Get Command Initial Value Description Section Attribute 1994 ------------------------------- ------ ------------- ------------- -------------------- ------------ --------- 1995 RENDERBUFFER_BINDING_EXT Z GetIntegerv 0 renderbuffer object 4.4.2.1 - 1996 bound to 1997 RENDERBUFFER_EXT 1998 1999 2000 (insert new table 8.nnn, "Renderbuffers (state per renderbuffer object)") 2001 2002 Get Value Type Get Command Initial Value Description Section Attribute 2003 ------------------------------- ------ ------------- ------------- -------------------- ------------ --------- 2004 RENDERBUFFER_WIDTH_EXT Z GetRenderbufferParameterivEXT 0 width of renderbuffer 4.4.2.1 - 2005 2006 RENDERBUFFER_HEIGHT_EXT Z GetRenderbufferParameterivEXT 0 height of renderbuffer 4.4.2.1 - 2007 2008 RENDERBUFFER_INTERNAL_FORMAT_EXT Z+ GetRenderbufferParameterivEXT RGBA internal format 4.4.2.1 - 2009 of renderbuffer 2010 2011 RENDERBUFFER_RED_SIZE_EXT Z GetRenderbufferParameterivEXT 0 size in bits of 4.4.2.1 - 2012 renderbuffer image's 2013 red component 2014 2015 RENDERBUFFER_GREEN_SIZE_EXT Z GetRenderbufferParameterivEXT 0 size in bits of 4.4.2.1 - 2016 renderbuffer image's 2017 green component 2018 2019 RENDERBUFFER_BLUE_SIZE_EXT Z GetRenderbufferParameterivEXT 0 size in bits of 4.4.2.1 - 2020 renderbuffer image's 2021 blue component 2022 2023 RENDERBUFFER_ALPHA_SIZE_EXT Z GetRenderbufferParameterivEXT 0 size in bits of 4.4.2.1 - 2024 renderbuffer image's 2025 alpha component 2026 2027 RENDERBUFFER_DEPTH_SIZE_EXT Z GetRenderbufferParameterivEXT 0 size in bits of 4.4.2.1 - 2028 renderbuffer image's 2029 depth component 2030 2031 RENDERBUFFER_STENCIL_SIZE_EXT Z GetRenderbufferParameterivEXT 0 size in bits of 4.4.2.1 - 2032 renderbuffer image's 2033 stencil component 2034 2035Move the following existing state from "Implementation Dependent 2036Values", tables 6.31-6.36 to into a new table called "Framebuffer 2037Dependent Values", table 9.nnn. 2038 2039 Get Value 2040 --------- 2041 AUX_BUFFERS 2042 MAX_DRAW_BUFFERS 2043 RGBA_MODE 2044 INDEX_MODE 2045 DOUBLEBUFFER 2046 STEREO 2047 SAMPLE_BUFFERS 2048 SAMPLES 2049 RED_BITS 2050 GREEN_BITS 2051 BLUE_BITS 2052 ALPHA_BITS 2053 DEPTH_BITS 2054 STENCIL_BITS 2055 ACCUM_RED_BITS 2056 ACCUM_GREEN_BITS 2057 ACCUM_BLUE_BITS 2058 ACCUM_ALPHA_BITS 2059 2060To the same table called "Framebuffer Dependent Values", table 9.nnn 2061add the following new framebuffer dependent state. 2062 2063 Get Value Type Get Command Minimum Value Description Section Attribute 2064 --------- ---- ----------- ------------- ------------------- ------- --------- 2065 MAX_COLOR_ATTACHMENTS_EXT Z+ GetIntegerv 1 Maximum number of 4.4.2.2 - 2066 attachment points 2067 for color buffers 2068 when using framebuffer 2069 objects 2070 2071New Implementation Dependent State 2072 2073 Get Value Type Get Command Minimum Value Description Section Attribute 2074 --------- ---- ----------- ------------- ------------------- ------- --------- 2075 MAX_RENDERBUFFER_SIZE_EXT Z+ GetIntegerv 1 Maximum width and 4.4.2.1 - 2076 height of 2077 renderbuffers 2078 supported by 2079 the implementation 2080 2081Additions to the AGL/GLX/WGL Specifications and dependencies on 2082WGL_ARB_make_current_read, GLX_SGI_make_current_read, and GLX 1.3 2083 2084 The color, depth, stencil, aux, and accum logical buffers defined by 2085 the <draw> and <read> drawables passed to glXMakeContextCurrent, 2086 glXMakeCurrent, and glXMakeCurrentRead are ignored while the value 2087 of FRAMEBUFFER_BINDING_EXT is non-zero. 2088 2089Dependencies on ATI_draw_buffers and ARB_draw_buffers 2090 2091 If neither ATI_draw_buffers nor ARB_draw_buffers are supported, then 2092 all discussions of DrawBuffers should be ignored. 2093 2094 In addition, the language describing DrawBuffers are derived from a 2095 combination of the ARB_draw_buffers specification and section 4.2.1 2096 of the OpenGL 2.0 specification. 2097 2098Dependencies on ARB_fragment_program, ARB_fragment_shader, and 2099ARB_vertex_shader 2100 2101 If ARB_fragment_program, ARB_fragment_shader, and ARB_vertex_shader 2102 are all not supported, then all references to the currently bound 2103 program or shader should be ignored. 2104 2105Dependencies on ARB_framebuffer_object and OpenGL 3.0 2106 2107 Framebuffer objects created with the commands defined by the 2108 GL_EXT_framebuffer_object extension are defined to be shared, while 2109 FBOs created with commands defined by the OpenGL core or 2110 GL_ARB_framebuffer_object extension are defined *not* to be shared. 2111 However, the following functions are viewed as aliases (in particular 2112 the opcodes for X are also the same) between the functions of 2113 GL_EXT_framebuffer_object and GL_ARB_framebuffer_object: 2114 2115 IsRenderbufferEXT / IsRenderbuffer 2116 DeleteRenderbuffersEXT / DeleteRenderbuffers 2117 GenRenderbuffersEXT / GenRenderbuffers 2118 RenderbufferStorageEXT / RenderbufferStorage 2119 GetRenderbufferParameterivEXT / GetRenderbufferParameteriv 2120 IsFramebufferEXT / IsFramebuffer 2121 DeleteFramebuffersEXT / DeleteFramebuffers 2122 GenFramebuffersEXT / GenFramebuffers 2123 CheckFramebufferStatusEXT / CheckFramebufferStatus 2124 FramebufferTexture1DEXT / FramebufferTexture1D 2125 FramebufferTexture2DEXT / FramebufferTexture2D 2126 FramebufferRenderbufferEXT / FramebufferRenderbuffer 2127 GenerateMipmapEXT / GenerateMipmap 2128 GetFramebufferAttachmentParameterivEXT / GetFramebufferAttachmentParameteriv 2129 2130 Since the above pairs are aliases, the functions of a pair are 2131 equivalent. Note that the functions BindFramebuffer and 2132 BindFramebufferEXT are not aliases and neither are the functions 2133 BindRenderbuffer and BindRenderbufferEXT. Because object creation 2134 occurs when the framebuffer object is bound for the first time, a 2135 framebuffer object can be shared across contexts only if it was first 2136 bound with BindFramebufferEXT. Framebuffers first bound with 2137 BindFramebuffer may not be shared across contexts. Framebuffer 2138 objects created with BindFramebufferEXT may subsequently be bound 2139 using BindFramebuffer. Framebuffer objects created with 2140 BindFramebuffer may be bound with BindFramebufferEXT provided they are 2141 bound to the same context they were created on. 2142 2143Dependencies on ARB_texture_rectangle 2144 2145 If ARB_texture_rectangle is not supported, then all references to 2146 TEXTURE_RECTANGLE_ARB should be ignored. 2147 2148Dependencies on EXT_packed_depth_stencil 2149 2150 If EXT_packed_depth_stencil is not supported, then all references to 2151 DEPTH_STENCIL internal formats should be ignored. 2152 2153Dependencies on NV_float_buffer 2154 2155 If NV_float_buffer is not supported, then all references to the 2156 following internal formats should be ignored: FLOAT_R_NV, 2157 FLOAT_RG_NV, FLOAT_RGB_NV, and FLOAT_RGBA_NV. 2158 2159Dependencies on NV_texture_shader 2160 2161 The following base internal formats are not color-renderable, 2162 depth-renderable, or stencil-renderable: HILO_NV, DSDT_NV, 2163 DSDT_MAG_NV, and DSDT_MAG_INTENSITY_NV. 2164 2165GLX Protocol 2166 2167 Seventeen new GL commands are added. 2168 2169 The following ten rendering commands are sent to the sever as part 2170 of a glXRender request: 2171 2172 BindRenderbufferEXT 2173 2 12 rendering command length 2174 2 4316 rendering command opcode 2175 4 ENUM target 2176 4 CARD32 renderbuffer 2177 2178 DeleteRenderbufferEXT 2179 2 8+n*4 rendering command length 2180 2 4317 rendering command opcode 2181 4 CARD32 n 2182 n*4 LISTofCARD32 renderbuffers 2183 2184 RenderbufferStorageEXT 2185 2 20 rendering command length 2186 2 4318 rendering command opcode 2187 4 ENUM target 2188 4 ENUM internalFormat 2189 4 CARD32 width 2190 4 CARD32 height 2191 2192 BindFramebufferEXT 2193 2 12 rendering command length 2194 2 4319 rendering command opcode 2195 4 ENUM target 2196 4 CARD32 framebuffer 2197 2198 DeleteFramebufferEXT 2199 2 8+n*4 rendering command length 2200 2 4320 rendering command opcode 2201 4 CARD32 n 2202 n*4 LISTofCARD32 framebuffers 2203 2204 FramebufferTexture1DEXT 2205 2 24 rendering command length 2206 2 4321 rendering command opcode 2207 4 ENUM target 2208 4 ENUM attachement 2209 4 ENUM textarget 2210 4 CARD32 texture 2211 4 CARD32 level 2212 2213 FramebufferTexture2DEXT 2214 2 24 rendering command length 2215 2 4322 rendering command opcode 2216 4 ENUM target 2217 4 ENUM attachement 2218 4 ENUM textarget 2219 4 CARD32 texture 2220 4 CARD32 level 2221 2222 FramebufferTexture3DEXT 2223 2 28 rendering command length 2224 2 4323 rendering command opcode 2225 4 ENUM target 2226 4 ENUM attachement 2227 4 ENUM textarget 2228 4 CARD32 texture 2229 4 CARD32 level 2230 4 CARD32 zoffset 2231 2232 FramebufferRenderbufferEXT 2233 2 20 rendering command length 2234 2 4324 rendering command opcode 2235 4 ENUM target 2236 4 ENUM attachment 2237 4 ENUM renderbuffertarget 2238 4 CARD32 renderbuffer 2239 2240 GenerateMipmapEXT 2241 2 8 rendering command length 2242 2 4325 rendering command opcode 2243 4 ENUM target 2244 2245 The remaining seven commands are non-rendering commands. These 2246 commands are sent separately (i.e., not as part of a glXRender or 2247 glXRenderLarge request), using the glXVendorPrivateWithReply 2248 request: 2249 2250 IsRenderbufferEXT 2251 1 CARD8 opcode (X assigned) 2252 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2253 2 4 request length 2254 4 1422 vendor specific opcode 2255 4 GLX_CONTEXT_TAG context tag 2256 4 CARD32 renderbuffer 2257 => 2258 1 1 reply 2259 1 unused 2260 2 CARD16 sequence number 2261 4 0 reply length 2262 4 BOOL32 return value 2263 20 unused 2264 2265 GenRenderbuffersEXT 2266 1 CARD8 opcode (X assigned) 2267 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2268 2 4 request length 2269 4 1423 vendor specific opcode 2270 4 GLX_CONTEXT_TAG context tag 2271 4 CARD32 n 2272 => 2273 1 1 reply 2274 1 unused 2275 2 CARD16 sequence number 2276 4 m reply length 2277 4 unused 2278 4 CARD32 n 2279 16 unused 2280 n*4 LISTofCARD32 renderbuffers 2281 2282 GetRenderbufferParameterivEXT 2283 1 CARD8 opcode (X assigned) 2284 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2285 2 5 request length 2286 4 1424 vendor specific opcode 2287 4 GLX_CONTEXT_TAG context tag 2288 4 ENUM target 2289 4 ENUM pname 2290 => 2291 1 1 reply 2292 1 unused 2293 2 CARD16 sequence number 2294 4 m reply length, m = (n == 1 ? 0 : n) 2295 4 unused 2296 4 CARD32 n 2297 2298 if (n = 1) this follows: 2299 2300 4 CARD32 params 2301 12 unused 2302 2303 otherwise this follows: 2304 2305 16 unused 2306 n*4 LISTofCARD32 params 2307 2308 IsFramebufferEXT 2309 1 CARD8 opcode (X assigned) 2310 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2311 2 4 request length 2312 4 1425 vendor specific opcode 2313 4 GLX_CONTEXT_TAG context tag 2314 4 CARD32 framebuffer 2315 => 2316 1 1 reply 2317 1 unused 2318 2 CARD16 sequence number 2319 4 0 reply length 2320 4 BOOL32 return value 2321 20 unused 2322 2323 GenFramebuffersEXT 2324 1 CARD8 opcode (X assigned) 2325 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2326 2 4 request length 2327 4 1426 vendor specific opcode 2328 4 GLX_CONTEXT_TAG context tag 2329 4 CARD32 n 2330 => 2331 1 1 reply 2332 1 unused 2333 2 CARD16 sequence number 2334 4 n reply length 2335 4 unused 2336 4 CARD32 n 2337 16 unused 2338 n*4 LISTofCARD32 framebuffers 2339 2340 CheckFramebufferStatusEXT 2341 1 CARD8 opcode (X assigned) 2342 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2343 2 4 request length 2344 4 1427 vendor specific opcode 2345 4 GLX_CONTEXT_TAG context tag 2346 4 ENUM target 2347 => 2348 1 1 reply 2349 1 unused 2350 2 CARD16 sequence number 2351 4 0 reply length 2352 4 ENUM return value 2353 20 unused 2354 2355 GetFramebufferAttachementParameterivEXT 2356 1 CARD8 opcode (X assigned) 2357 1 17 GLX opcode (X_GLXVendorPrivateWithReply) 2358 2 6 request length 2359 4 1428 vendor specific opcode 2360 4 GLX_CONTEXT_TAG context tag 2361 4 ENUM target 2362 4 ENUM attachment 2363 4 ENUM pname 2364 => 2365 1 1 reply 2366 1 unused 2367 2 CARD16 sequence number 2368 4 m reply length, m = (n == 1 ? 0 : n) 2369 4 unused 2370 4 CARD32 n 2371 2372 if (n = 1) this follows: 2373 2374 4 CARD32 params 2375 12 unused 2376 2377 otherwise this follows: 2378 2379 16 unused 2380 n*4 LISTofCARD32 params 2381 2382 2383 2384Usage Examples 2385 2386 The following examples use a helper macro for 2387 CHECK_FRAMEBUFFER_STATUS, defined below. 2388 2389 Example (6) gives a (very slightly) more robust example of handling 2390 the possible return values for glCheckFramebufferStatusEXT. 2391 2392 #define CHECK_FRAMEBUFFER_STATUS() \ 2393 { \ 2394 GLenum status; \ 2395 status = glCheckFramebufferStatusEXT(GL_FRAMEBUFFER_EXT); \ 2396 switch(status) { \ 2397 case GL_FRAMEBUFFER_COMPLETE_EXT: \ 2398 break; \ 2399 case GL_FRAMEBUFFER_UNSUPPORTED_EXT: \ 2400 /* choose different formats */ \ 2401 break; \ 2402 default: \ 2403 /* programming error; will fail on all hardware */ \ 2404 assert(0); \ 2405 } 2406 } 2407 2408 (1) Render to 2D texture with a depth buffer 2409 2410 // Given: color_tex - TEXTURE_2D color texture object 2411 // depth_rb - GL_DEPTH renderbuffer object 2412 // fb - framebuffer object 2413 2414 // Enable render-to-texture 2415 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2416 2417 // Set up color_tex and depth_rb for render-to-texture 2418 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2419 GL_COLOR_ATTACHMENT0_EXT, 2420 GL_TEXTURE_2D, color_tex, 0); 2421 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2422 GL_DEPTH_ATTACHMENT_EXT, 2423 GL_RENDERBUFFER_EXT, depth_rb); 2424 2425 // Check framebuffer completeness at the end of initialization. 2426 CHECK_FRAMEBUFFER_STATUS(); 2427 2428 <draw to the texture and renderbuffer> 2429 2430 // Re-enable rendering to the window 2431 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2432 2433 glBindTexture(GL_TEXTURE_2D, color_tex); 2434 <draw to the window, reading from the color_tex> 2435 2436 2437 (2) Application that supports both RBBCTT (render back buffer, copy to 2438 texture) and RTT (render to texture). The migration path from RBBCTT 2439 to RTT is easy. 2440 2441 if (useFramebuffer) { 2442 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2443 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2444 GL_COLOR_ATTACHMENT0_EXT, 2445 GL_TEXTURE_2D, color_tex, 0); 2446 CHECK_FRAMEBUFFER_STATUS(); 2447 } 2448 2449 draw_to_texture(); 2450 2451 glBindTexture (GL_TEXTURE_2D, color_tex); 2452 if (useFramebuffer) { 2453 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2454 } else { // copy tex path 2455 glCopyTexSubImage(...); 2456 } 2457 2458 2459 (3) Simple render-to-texture loop with initialization. Create an 2460 RGB8 texture, a 24-bit depth renderbuffer, and a stencil 2461 renderbuffer. In a loop, alternate between rendering to, and 2462 texturing out of, the color texture. 2463 2464 glGenFramebuffersEXT(1, &fb); 2465 glGenTextures(1, &color_tex); 2466 glGenRenderbuffersEXT(1, &depth_rb); 2467 glGenRenderbuffersEXT(1, &stencil_rb); 2468 2469 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2470 2471 // initialize color texture 2472 glBindTexture(GL_TEXTURE_2D, color_tex); 2473 glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 2474 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 512, 512, 0, 2475 GL_RGB, GL_INT, NULL); 2476 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2477 GL_COLOR_ATTACHMENT0_EXT, 2478 GL_TEXTURE_2D, color_tex, 0); 2479 2480 // initialize depth renderbuffer 2481 glBindRenderbufferEXT(GL_RENDERBUFFER_EXT, depth_rb); 2482 glRenderbufferStorageEXT(GL_RENDERBUFFER_EXT, 2483 GL_DEPTH_COMPONENT24, 512, 512); 2484 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2485 GL_DEPTH_ATTACHMENT_EXT, 2486 GL_RENDERBUFFER_EXT, depth_rb); 2487 2488 // initialize stencil renderbuffer 2489 glBindRenderbufferEXT(GL_RENDERBUFFER_EXT, stencil_rb); 2490 glRenderbufferStorageEXT(GL_RENDERBUFFER_EXT, 2491 GL_STENCIL_INDEX, 512, 512); 2492 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2493 GL_STENCIL_ATTACHMENT_EXT, 2494 GL_RENDERBUFFER_EXT, stencil_rb); 2495 2496 // Check framebuffer completeness at the end of initialization. 2497 CHECK_FRAMEBUFFER_STATUS(); 2498 2499 loop { 2500 glBindTexture(GL_TEXTURE_2D, 0); 2501 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2502 2503 <draw to the texture> 2504 2505 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2506 glBindTexture(GL_TEXTURE_2D, color_tex); 2507 2508 <draw to the window, reading from the color texture> 2509 } 2510 2511 2512 (4) Render-to-texture loop with automatic mipmap generation. There 2513 are N framebuffers, N mipmap color textures, and a single shared 2514 depth renderbuffer. The depth renderbuffer is not a mipmap. 2515 2516 GLuint fb_array[N]; 2517 GLuint color_tex_array[N]; 2518 GLuint depth_rb; 2519 2520 glGenFramebuffersEXT(N, fb_array); 2521 glGenTextures(N, color_tex_array); 2522 glGenRenderbuffersEXT(1, &depth_rb); 2523 2524 // initialize color textures 2525 for (int i=0; i<N; i++) { 2526 glBindTexture(GL_TEXTURE_2D, color_tex_array[N]); 2527 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 512, 512, 0, 2528 GL_RGB, GL_INT, NULL); 2529 2530 // establish a mipmap chain for the texture 2531 glGenerateMipmapEXT(GL_TEXTURE_2D); 2532 } 2533 2534 // initialize depth renderbuffer 2535 glBindRenderbufferEXT(GL_RENDERBUFFER_EXT, depth_rb); 2536 glRenderbufferStorageEXT(GL_RENDERBUFFER_EXT, 2537 GL_DEPTH_COMPONENT24, 512, 512); 2538 2539 // setup framebuffers, sharing depth 2540 for (int i=0; i<N; i++) { 2541 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb_array[i]); 2542 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2543 GL_COLOR_ATTACHMENT0_EXT, 2544 GL_TEXTURE_2D, color_tex_array[i], 0); 2545 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2546 GL_DEPTH_ATTACHMENT_EXT, 2547 GL_RENDERBUFFER_EXT, depth_rb); 2548 } 2549 2550 // Check framebuffer completeness at the end of initialization. 2551 CHECK_FRAMEBUFFER_STATUS(); 2552 2553 loop { 2554 glBindTexture(GL_TEXTURE_2D, 0); 2555 2556 for (int i=0; i<N; i++) { 2557 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb_array[i]); 2558 <draw to texture i> 2559 } 2560 2561 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2562 2563 // automatically generate mipmaps 2564 for (int i=0; i<N; i++) { 2565 glBindTexture(GL_TEXTURE_2D, color_tex_array[i]); 2566 glGenerateMipmapEXT(GL_TEXTURE_2D); 2567 } 2568 2569 <draw to the window, reading from the color textures> 2570 } 2571 2572 2573 (5) Render-to-texture loop with custom mipmap generation. 2574 The depth renderbuffer is not a mipmap. 2575 2576 glGenFramebuffersEXT(1, &fb); 2577 glGenTextures(1, &color_tex); 2578 glGenRenderbuffersEXT(1, &depth_rb); 2579 2580 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2581 2582 // initialize color texture and establish mipmap chain 2583 glBindTexture(GL_TEXTURE_2D, color_tex); 2584 glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB8, 512, 512, 0, 2585 GL_RGB, GL_INT, NULL); 2586 glGenerateMipmapEXT(GL_TEXTURE_2D); 2587 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2588 GL_COLOR_ATTACHMENT0_EXT, 2589 GL_TEXTURE_2D, color_tex, 0); 2590 2591 // initialize depth renderbuffer 2592 glBindRenderbufferEXT(GL_RENDERBUFFER_EXT, depth_rb); 2593 glRenderbufferStorageEXT(GL_RENDERBUFFER_EXT, 2594 GL_DEPTH_COMPONENT24, 512, 512); 2595 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2596 GL_DEPTH_ATTACHMENT_EXT, 2597 GL_RENDERBUFFER_EXT, depth_rb); 2598 2599 // Check framebuffer completeness at the end of initialization. 2600 CHECK_FRAMEBUFFER_STATUS(); 2601 2602 loop { 2603 glBindTexture(GL_TEXTURE_2D, 0); 2604 2605 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2606 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2607 GL_COLOR_ATTACHMENT0_EXT, 2608 GL_TEXTURE_2D, color_tex, 0); 2609 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2610 GL_DEPTH_ATTACHMENT_EXT, 2611 GL_RENDERBUFFER_EXT, depth_rb); 2612 2613 <draw to the base level of the color texture> 2614 2615 // custom-generate successive mipmap levels 2616 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2617 GL_DEPTH_ATTACHMENT_EXT, 2618 GL_RENDERBUFFER_EXT, 0); 2619 glBindTexture(GL_TEXTURE_2D, color_tex); 2620 foreach (level > 0, in order of increasing values of level) { 2621 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2622 GL_COLOR_ATTACHMENT0_EXT, 2623 GL_TEXTURE_2D, color_tex, level); 2624 glTexParameteri(TEXTURE_2D, TEXTURE_BASE_LEVEL, level-1); 2625 glTexParameteri(TEXTURE_2D, TEXTURE_MAX_LEVEL, level-1); 2626 2627 <draw to level> 2628 } 2629 glTexParameteri(TEXTURE_2D, TEXTURE_BASE_LEVEL, 0); 2630 glTexParameteri(TEXTURE_2D, TEXTURE_MAX_LEVEL, max); 2631 2632 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2633 <draw to the window, reading from the color texture> 2634 } 2635 2636 2637 (6) Pseudo-code example of one method of responding to 2638 FRAMEBUFFER_UNSUPPORTED_EXT 2639 2640 bool done = false; 2641 bool success = false; 2642 int configurationNumber = 0; 2643 GLenum status; 2644 2645 while (!done) 2646 { 2647 for (each framebuffer-attachable image) 2648 { 2649 ChooseInternalFormatForFramebufferAttachableImage(configurationNumber); 2650 2651 CreateFramebufferAttachableImage(); 2652 2653 AttachFramebufferAttachableImageToFramebuffer(); 2654 } 2655 2656 status = glCheckFramebufferStatusEXT(GL_FRAMEBUFFER_EXT); 2657 switch(status) 2658 { 2659 case GL_FRAMEBUFFER_COMPLETE_EXT: 2660 success = true; 2661 done = true; 2662 break; 2663 2664 case GL_FRAMEBUFFER_UNSUPPORTED_EXT: 2665 if (configCount < MAX_NUM_CONFIGS_I_WANT_TO_TRY) 2666 { 2667 printf("current config not supported, trying again); 2668 configurationNumber++; 2669 } 2670 else 2671 { 2672 printf("couldn't find a supported config\n"); 2673 success = false; 2674 done = true; 2675 } 2676 break; 2677 2678 default: 2679 // programming error; will fail on all hardware 2680 FatalError(); 2681 exit(1); 2682 } 2683 } 2684 2685 if (!success) 2686 { 2687 printf("couldn't find a supported config\n"); 2688 FatalError(); 2689 exit(1); 2690 } 2691 2692 // Current framebuffer is supported and complete!! 2693 Draw(); 2694 2695 2696 (7) Render to depth texture with no color attachments 2697 2698 // Given: depth_tex - TEXTURE_2D depth texture object 2699 // fb - framebuffer object 2700 2701 // Enable render-to-texture 2702 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2703 2704 // Set up depth_tex for render-to-texture 2705 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2706 GL_DEPTH_ATTACHMENT_EXT, 2707 GL_TEXTURE_2D, depth_tex, 0); 2708 2709 // No color buffer to draw to or read from 2710 glDrawBuffer(GL_NONE); 2711 glReadBuffer(GL_NONE); 2712 2713 // Check framebuffer completeness at the end of initialization. 2714 CHECK_FRAMEBUFFER_STATUS(); 2715 2716 <draw something> 2717 2718 // Re-enable rendering to the window 2719 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2720 2721 glBindTexture(GL_TEXTURE_2D, depth_tex); 2722 <draw to the window, reading from the depth_tex> 2723 2724 (8) FBO and ARB_draw_buffers 2725 2726 // Given: color_texA - TEXTURE_2D color texture object 2727 // Given: color_texB - TEXTURE_2D color texture object 2728 // depth_rb - GL_DEPTH renderbuffer object 2729 // fb - framebuffer object 2730 2731 // Set up the framebuffer object 2732 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, fb); 2733 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2734 GL_COLOR_ATTACHMENT0_EXT, 2735 GL_TEXTURE_2D, color_texA, 0); 2736 glFramebufferTexture2DEXT(GL_FRAMEBUFFER_EXT, 2737 GL_COLOR_ATTACHMENT1_EXT, 2738 GL_TEXTURE_2D, color_texB, 0); 2739 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, 2740 GL_DEPTH_ATTACHMENT_EXT, 2741 GL_RENDERBUFFER_EXT, depth_rb); 2742 2743 // Enable both attachments as draw buffers 2744 GLenum drawbuffers = {GL_COLOR_ATTACHMENT0_EXT, 2745 GL_COLOR_ATTACHMENT1_EXT}; 2746 glDrawBuffers(2, drawbuffers); 2747 2748 // Check framebuffer completeness at the end of initialization. 2749 CHECK_FRAMEBUFFER_STATUS(); 2750 2751 // Enable fragment program that writes to both gl_FragData[0] 2752 // and gl_FragData[1] 2753 2754 <draw something> 2755 2756 // Disable fragment program 2757 2758 // Re-enable rendering to the window 2759 glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, 0); 2760 2761 // Bind both textures, each to a different texture unit 2762 glActiveTexture(GL_TEXTURE0); 2763 glBindTexture(GL_TEXTURE_2D, color_texA); 2764 glActiveTexture(GL_TEXTURE1); 2765 glBindTexture(GL_TEXTURE_2D, color_texB); 2766 2767 <draw to the window> 2768 2769Issues 2770 2771 (1) We obviously won't call this "ARB_compromise_buffers", so 2772 what name should we use? 2773 2774 RESOLUTION: resolved, EXT_framebuffer_object 2775 2776 Possibilities considered include: 2777 EXT_framebuffer 2778 EXT_framebuffer_object 2779 EXT_renderable_buffers 2780 EXT_renderbuffer 2781 EXT_superbuffers (hah!) 2782 EXT_renderable_image 2783 EXT_render_image 2784 2785 The lead candidates were EXT_renderable_image and 2786 EXT_framebuffer_object Since this extension introduced both 2787 new concepts into OpenGL, this was a bit of a toss up. 2788 EXT_framebuffer_object was chosen based on a weak precedent 2789 given by EXT_texture_object and ARB_vertex_buffer_object 2790 2791 (2) Many developers complain about the OpenGL/glX/WGL/agl pbuffer 2792 API, which they use both to do "render to texture" and to do 2793 general offscreen (non-windowed) accelerated rendering. This 2794 extension is intended to subsume, some and perhaps all of, the 2795 functionality currently handled by pbuffers. Should this 2796 extension (initially?) support only render-to-texture or should 2797 it try to provide an OpenGL API to fully replace the pbuffer 2798 API? 2799 2800 RESOLUTION: This extension should fully replace the pbuffer API. 2801 2802 The implication of this decision is that this API should provide 2803 a way to support rendering to offscreen buffers that are not 2804 textures. 2805 2806 (3) As a consequence of issue (2), this extension adds the concept of 2807 share-able, non-texturable renderable entitites that can be 2808 used as color buffers, depth buffers, stencil buffers, etc. 2809 The OpenGL spec refers to these entities as "logical buffers". 2810 What should this spec call them? 2811 2812 RESOLUTION: "renderbuffer", (one word) 2813 2814 We could just call them "logical buffers", but is there a 2815 better name? 2816 2817 The group considered: 2818 logical buffer - possible, kind of general 2819 render buffer - clear, (one word or two?) 2820 renderable - clear, but may conflict with glx "drawable" 2821 drawable - confusing: glx "drawable" == gl "framebuffer" 2822 render surface - possible 2823 render target - possible 2824 image buffer - may get confused with Tex"Image" 2825 image - may get confused with Tex"Image" 2826 surface buffer - too verbose? 2827 surface - too general 2828 others??? 2829 2830 The group felt "render buffer " (or possibly "renderbuffer") 2831 provides for the clearest expression of the purpose for 2832 these buffers. 2833 2834 We finally decided on "renderbuffer" because we didn't want 2835 to use "render" as an adjective to describe a generic 2836 buffer, but rather decided to coin a new compound word to 2837 describe this concept. 2838 2839 (4) How should the specification refer to the group of 2840 various types of objects that can be attached to the framebuffer 2841 attachment points? 2842 2843 RESOLUTION: The specification will use the phrase 2844 "framebuffer-attachable images" to mean the 2D array of 2845 pixels (image) of a "renderbuffer", a "texture", or any 2846 other items that could be attached to a framebuffer. 2847 2848 Options considered include: 2849 "render target" 2850 "renderable image" 2851 "framebuffer-attachable 2852 2853 Initially, we chose the phrase "render target" for this but 2854 felt it didn't accurately capture the concept of a 2D array 2855 of pixels that was simultaneously useable as the storage of 2856 a texture object and the destination of rendering. 2857 2858 We then tried to borrow the "image" language of OpenGL which 2859 describes texture's pixel arrays as "images" and we chose 2860 the term "renderable image". 2861 2862 However, in the end, we felt that the salient characteristic 2863 of these images was that we could attach them to a 2864 framebuffer and settled on the term "framebuffer-attachable 2865 image". 2866 2867 (5) How should the specification refer to the places in a framebuffer 2868 that can hold a framebuffer-attachable image? 2869 2870 RESOLUTION: This state is called an "attachment point" of 2871 the framebuffer. 2872 2873 "attachment points" will be be used to describe the 2874 framebuffer state that holds a connection to a given 2875 framebuffer-attachable image (a renderbuffer image or a 2876 texture image). The framebuffer attachment points include 2877 the framebuffer's color buffers, stencil buffer, depth 2878 buffer, and aux buffer. 2879 2880 The word "attach" is being used to refer to connecting one 2881 object to another. "bind" refers to connecting an object to 2882 the context state. A texture image can be attached to a 2883 framebuffer object, but a framebuffer object is bound into 2884 the context state vector. 2885 2886 (6) This extension adds the concept of collections of "logical 2887 buffers", to replace the window-system provided collection 2888 (drawable, or window) of logical buffers. What should we call 2889 these? 2890 2891 RESOLUTION: "framebuffer" 2892 2893 For the "collection of logical buffers" object, the group 2894 considered the names: "framebuffer", "renderTarget", 2895 "drawable". We chose "framebuffer" since this is consistent 2896 with how the OpenGL specification already uses the word 2897 framebuffer. 2898 2899 (7) This extension introduces two new object types into the OpenGL: 2900 renderbuffer objects and framebuffer objects. For handling 2901 these objects, there are two main object manipulation 2902 methodology precedents to choose from: 2903 2904 1) "texture/program/vbo" object model: 2905 app-supplied int handles, 2906 Gen/is/Bind/Delete functions 2907 2908 2) "GLSL" object model: 2909 driver-supplied GLhandle handles, 2910 Create/Delete/Attach, etc 2911 2912 Which methodology should this extension use for each new object? 2913 2914 RESOLUTION: Use Option (1), "texture" object methodology, 2915 for both "renderbuffer" objects and framebuffer objects. 2916 2917 This is consistent with the June, 2004 ARB meeting vote to 2918 use the "texture" object methodlogy as the default object 2919 methodology. 2920 2921 (8) Do we need separate framebuffer objects? 2922 2923 RESOLUTION: yes. 2924 2925 The framebuffer object is an object to encapsulate the state 2926 of the framebuffer and the collection of 2927 framebuffer-attachable images attached to the logical buffer 2928 attachment points. A question was raised early on about 2929 whether we should have separate, shareable framebuffer 2930 objects or we should fold a single framebuffer "object" 2931 state vector into the context. 2932 2933 We decided to leave framebuffer objects in the API, with the 2934 understanding that we could easily remove them from the API 2935 and the spec later if a convincing case was argued for 2936 removing it. 2937 2938 There are several reasons why framebuffer objects were 2939 introduced: 2940 2941 FB1. It can be "expensive" (for some definition of 2942 expensive) to validate the framebuffer and all its 2943 attached objects. There is a desire to be able to 2944 easily recognize that a particular state. combination 2945 has been seen and validated previously. 2946 2947 FB2. There is some subset of GL context state which only 2948 makes sense in its relationship to the current 2949 framebuffer and attached images (red bits, green 2950 bits, blue bits, etc, presence or absence of aux 2951 buffers or depth buffers, current value of draw 2952 buffer(s), read buffer, etc. etc). It would be nice 2953 if this state "tracked" changes to the current 2954 framebuffer configuration by being part of the 2955 framebuffer object state. 2956 2957 FB3. For a while, we considered adding "intrinsic" or 2958 "implicit" buffer storage to the framebuffer. This 2959 would be used for buffers that were either hidden 2960 from the user, like the multisample buffer, or 2961 perhaps needed to be explicitly formatted by the 2962 driver. If we did have this kind of "intrinsic" 2963 storage, then framebuffers would be a lot like 2964 textures and would have the same kinds of pressures 2965 to minimize vram, sharing storage across objects and 2966 contexts as textures did. In fact, they would be 2967 similar to cube map texture objects which had 6 2968 attached face images, or mipmaped textures which had 2969 a set of mipmap level images. In the end we decided 2970 not to use intrinsic buffers, - see issue (13) - but 2971 we might decide to add them back in the future. For 2972 instance, one option for supporting multisampling is 2973 to use an implicit multisample buffer. 2974 2975 FB4. We realized that most of the "hard" issues introduced 2976 by this extension were completely orthogonal to the 2977 presence or absence of framebuffer objects. All of 2978 the same issues apply regardless of whether there is 2979 a single non-default framebuffer as part of the 2980 context or multiple framebuffer objects. These 2981 issues about attaching, (binding) objects, 2982 reformatting attached (or bound) images via 2983 TexImage/RenderbufferStorage, pixel format 2984 combinations, framebuffer completeness, and the 2985 relationship between a non-"default" framebuffer and 2986 the legacy window sytem framebuffer and pixel format 2987 all come in to play either way. So there is actually 2988 little implementation or conceptual cost incurred by 2989 the introduction of these framebuffer objects. 2990 2991 There were also a few reasons why we considered *not* adding 2992 framebuffer objects: 2993 2994 NoFB1. In the absence of "intrinsic" buffers, framebuffer 2995 objects only really consist of the attachment 2996 state. It is convenient to encapsulate this state 2997 into an object, but one could ask if it's any more 2998 convenient than say a "blend state" object or a 2999 "texture unit attachment state" object, which to 3000 date, we have chosen not to add into OpenGL. 3001 3002 NoFB2. As a "state-only" object, there's a question about 3003 how much state should be included - at least the 3004 attachment state should be included, but what about 3005 draw buffers state, what about the viewport state, 3006 what about other state? Since drawing the line is 3007 hard, we questioned whether we needed these 3008 objects. 3009 3010 NoFB3. Some amount of the functionality of the framebuffer 3011 objects could be implemented by the application 3012 with the appropriate use of display lists. 3013 3014 In weighing (FB1), expense of validating framebuffer state, 3015 versus (NoFB1), not wanting to introduce "state only" 3016 objects, we realized that framebuffer validation is more 3017 expensive than the blend state (for which there is no object 3018 in GL) and less expensive than a fragment program (for which 3019 there is an object in GL). While it's not exactly clear 3020 precisely where on the spectrum of "expense" the framebuffer 3021 validation lies, we decided that it may be expensive enough 3022 to justify creating a new object type. So we retained 3023 framebuffer objects in the API now, with the understanding 3024 that if we change our minds it's easier to rip them out 3025 later than it is to add them back in later. 3026 3027 (9) Should the routine which allocates a renderbuffer accept an 3028 image to initialize the buffer, analogous to how TexImage 3029 works? 3030 3031 RESOLUTION: no, it should allocate uninitialized storage 3032 3033 We could have allowed a renderbuffer "image" specification 3034 routine, but this would essentially serve the same purpose 3035 as a combined "allocate renderbuffer followed by DrawPixels" 3036 routine so we decided it was extraneous. The primary 3037 purpose of these buffers is to store rendered output anyway, 3038 so there was not sufficient demand to support an optimized 3039 path for data initialization. See related issue (10). 3040 3041 (10) What should we call the routine that allocates storage for the 3042 renderbuffer? This routine would be the moral equivalent of 3043 glTexImage. 3044 3045 RESOLUTION: RenderbufferStorage() 3046 3047 Options included: 3048 RenderbufferStorage() 3049 RenderbufferImage() 3050 others??? 3051 3052 This is really a function of how we resolve issue (9). 3053 3054 RenderbufferImage would be appropriate if the allocation 3055 routine could take an image to initialize the renderbuffer. 3056 3057 RenderbufferStorage would be more appropriate if the 3058 allocation routine does not take an image. 3059 3060 Since the group decided supporting an "initialization" image 3061 for a "renderbuffer" was too much overlapping functionality 3062 with DrawPixels, RenderbufferStorage was chosen. 3063 3064 (11) The routine(s) which attach a texture to a framebuffer 3065 attachment point need to describe which image in the texture 3066 they are using, i.e., which cube map face, mipmap level, or 3D 3067 texture z-slice/depthoffset/image. Should we have one routine 3068 that handles all of these with some arguments ignored for 3069 specific texture types/targets? Or should we have a parallel 3070 set of routines for 1D/2D/3D, like TexImage does? 3071 3072 RESOLUTION: Option (b) 3 routines for texture, 1 for 3073 renderbuffer 3074 3075 Originally, we chose option (b) for reasons of 3076 similarity to glTexImage1D/2D/3D. For TexImage2D and 3077 FramebufferTexture2D, the texture target was used to 3078 select a face on a cube map texture object. Since 3079 glTexImage1D/3D used TEXTURE_1D/TEXTURE_3D texture 3080 targets, we did the same for FramebufferTexture1D/3D. We 3081 also included the texture target in case it was needed 3082 for future expandability. 3083 3084 However, some felt uncomfortable with this resolution 3085 since it adds 3 framebuffer attachment calls for 3086 textures, so we reopened the issue. 3087 3088 Originally we just considered options (a) and (b). We 3089 then reconsidered a few additional flavors: (c), (d), 3090 and (e) 3091 3092 Options include: 3093 3094 a) one routine with arguments that are sometimes "ignored" 3095 3096 For instance <image> is ignored for non-3D textures 3097 and <face> is ignored for non-cube maps, etc. 3098 3099 This gives us: 3100 3101 void FramebufferTexture(enum target, enum attachment, 3102 uint texture, 3103 uint level, enum face, uint image); 3104 3105 b) routines for 1D/2D/3D, use FramebufferTexture2D for 2D, 3106 Cube, Rectangle 3107 3108 Requires use of a texture target to distinguish cube map 3109 faces on FramebufferTexture2D 3110 3111 Includes "redundant" texture target for 1D/3D variants 3112 for consistency and precedent with TexImage1D/3D. 3113 3114 This gives us: 3115 3116 void FramebufferTexture1D(enum target, enum attachment, 3117 enum textarget, uint texture, uint level); 3118 void FramebufferTexture2D(enum target, enum attachment, 3119 enum textarget, uint texture, uint level); 3120 void FramebufferTexture3D(enum target, enum attachment, 3121 enum textarget, uint texture, uint level, uint image); 3122 3123 c) same as (b) but add a dedicated routine for Cubemaps 3124 3125 Question: since we added a Cubemap version, do we need a 3126 Rectangle variant as well? 3127 3128 This gives us: 3129 3130 void FramebufferTexture1D(enum target, enum attachment, 3131 enum textarget, uint texture, uint level); 3132 void FramebufferTexture2D(enum target, enum attachment, 3133 enum textarget, uint texture, uint level); 3134 void FramebufferTextureCubemap(enum target, enum attachment, 3135 enum textarget, uint texture, uint level); 3136 void FramebufferTexture3D(enum target, enum attachment, 3137 enum textarget, uint texture, uint level, uint image); 3138 3139 3140 d) same as (c) but with no texture target parameter 3141 3142 Question: since we added a Cubemap version, do we need a 3143 Rectangle variant as well? 3144 3145 This gives us: 3146 3147 void FramebufferTexture1D(enum target, enum attachment, 3148 uint texture, uint level); 3149 void FramebufferTexture2D(enum target, enum attachment, 3150 uint texture, uint level); 3151 void FramebufferTextureCubemap(enum target, enum attachment, 3152 uint texture, enum face, uint level); 3153 void FramebufferTexture3D(enum target, enum attachment, 3154 uint texture, uint level, uint image); 3155 3156 3157 e) one FramebufferTexture routine with additional arguments 3158 passed in via another routine. 3159 3160 There are no "ignored" arguments in this routine. 3161 3162 The arguments which would be "ignored" by this function 3163 are passed in as selector state by a separate function. 3164 These could be specified as a FramebufferParameter 3165 (implying that they are stored as framebuffer state), or 3166 as a piece of context state that is copied into the 3167 framebuffer attachment point at FramebufferTexture time. 3168 Of the two, context state is much more desirable since 3169 ARB_render_texture made the mistake of putting the 3170 selection state in the pbuffer, and this has real 3171 usability issues for multicontext applications. 3172 3173 This gives us (two routines) 3174 3175 void FramebufferTexture(enum target, enum attachment, 3176 uint texture, uint level); 3177 and 3178 3179 void FramebufferParameter(enum target, enum pname, uint param); 3180 where pname can be one of 3181 GL_{attachment}_TEXTURE_CUBEMAP_FACE 3182 GL_{attachment}_TEXTURE_3D_IMAGE 3183 and param represents the cube map face or z-slice image. 3184 3185 Also, option (e) raises 2 questions: 3186 3187 1. Since the rest of the selection state would come in 3188 through another function, we have to ask when can 3189 these selector state variables be changed? 3190 3191 We had previously decided that we want to pass 3192 selection state in atomically with the attachment 3193 request. To be consistent with this earlier 3194 decision, this would imply that these variables could 3195 not be changed dynamically but would be "snapshotted" 3196 into the framebuffer attachment point at at 3197 FramebufferTexture time. This snapshot could be 3198 thought of as similar to the way ActiveTexture works. 3199 This is also similar to the snapshot of the 3200 transformed raster pos vertex that occurs at 3201 glRasterPos time. It is a copy of one piece of state 3202 into another piece of state, not just a "switch" than 3203 can be updated later that indicates where other state 3204 should be stored. 3205 3206 2. Is the rationale to consolidate FramebufferTexture 3207 from 3 routines to 1 also a reason to consolidate 3208 FramebufferTexture and FramebufferRenderbuffer into a 3209 single attachment routine? I.e., should there just 3210 be one routine called FramebufferAttachableImage()? 3211 3212 If we did this, then we could also move <level> out 3213 of the argument list and rename the function to, 3214 perhaps, FramebufferAttach. 3215 3216 void FramebufferAttach(enum target, enum attachment, 3217 enum objectType, uint name); 3218 and we'd need to create another enum for 3219 FramebufferParameter 3220 GL_{attachment}_TEXTURE_LEVEL 3221 3222 or, avoiding the use of verbs in the function 3223 name, perhaps: 3224 3225 void FramebufferAttachableImage(enum target, enum attachment, 3226 enum objectType, uint name); 3227 3228 3229 Rationale: 3230 3231 (a) was discarded because it was not very extensible in the 3232 event we need to add additional texture selection state in 3233 the future (for instance, what if we add TEXTURE_4D 3234 targets?) 3235 3236 (c) and (d) were discarded because the introduction of a 3237 special cubemap routine was undesirable since we were 3238 considering issue in an attempt to *reduce* the number of 3239 entry points. Additionally, (d) was discarded because it 3240 was felt the texture targets were still required. 3241 3242 (e) was discarded because the intent was that attachment 3243 (and the consequent framebuffer validation) was a 3244 "heavy-weight" operation. By using a separate routine to 3245 set part of the attachment state, developers may be 3246 incorrectly encouraged to assume some attachment state could 3247 be changed more easily than others. It was felt it wasn't 3248 worth this possible misunderstanding just to save some 3249 function entry points. 3250 3251 In the end, it was determined that (b) was the lesser of two 3252 (five?) evils. (b) also has precedent in the specification 3253 of texture images via gl{Copy}TexImage. Finally, (b) is 3254 pretty clearly extensible to new attachment routines for 3255 future object types. 3256 3257 3258 (12) Do we need a "format group" or "format restriction" API? 3259 3260 RESOLUTION: Yes, but put it in a separate extension for 3261 reasons of schedule. 3262 3263 This extension introduces the ability to construct a 3264 collection of logical buffers using images of various 3265 formats into a framebuffer in a very flexible manner. It is 3266 by design more flexible than used to be possible to do by 3267 querying for available pixel formats in the window-system 3268 glX/WGL/agl API's. As a result, it is possible to construct 3269 a framebuffer that is actually not supportable by the 3270 implementation and the reasons for the configuration being 3271 unsupportable are entirely implementation dependent. 3272 3273 This is why we originally added the CheckFramebufferStatus 3274 API. So that the application at least has the ability to 3275 determine that a particular, otherwise legal, configuration 3276 of framebuffer attachments actually will not work on this 3277 implementation. 3278 3279 However, this extension does not provide any very helpful 3280 mechanism to find out why things are not supported or what 3281 to do to reconfigure the attachments into a supported 3282 configuration. 3283 3284 This is a very difficult problem to solve. glX/WGL/agl 3285 solved this problem by allowing the application to specify a 3286 request for a configuration and letting implementation 3287 provide a "best match". Additionally, glX and WGL also 3288 allow for the enumeration of all possible supported 3289 configurations. 3290 3291 Various schemes like these were considered but they were all 3292 quite complicated (possibly as complicated as the windowing 3293 system API's we are trying to replace). Consequently, we 3294 decided to investigate some additional approaches. 3295 3296 One of these approaches is to specify "allocation and usage" 3297 hints prior to the routines which allocate buffers 3298 (TexImage/RenderbufferStorage) that will somehow indicate an 3299 intended configuration and then let the implementation use 3300 this additional information when selecting internal formats 3301 for textures and renderbuffers. The GL already has the 3302 freedom to pick any internal format it wants for textures 3303 and renderbuffers (subject to invariance requirements), and 3304 so we would like to leverage this freedom and influence the 3305 choice with an additional channel of information. 3306 3307 One example, though not the only one, is some API to let the 3308 application specify it would like to be able to use a color 3309 buffer, depth, and stencil buffer. The implementation would 3310 take advantage of this information when allocating textures 3311 and renderbuffers and only choose internal formats for 3312 color, depth, and stencil textures and renderbuffers that 3313 could be guaranteed to be used together. For instance, the 3314 user could call: 3315 3316 FormatRestriction(GL_COLOR | GL_DEPTH | STENCIL); 3317 3318 or perhaps 3319 3320 FormatRestriction(GL_32_BITS_COLOR_DEPTH_STENCIL); 3321 3322 and then when the user called TexImage with a color buffer, 3323 the GL would only pick color formats that could definitely 3324 be used with depth and stencil buffers. The effect of this 3325 API would be to "restrict" the avaible choices to the GL to 3326 the subset of compatible formats. In this way, the 3327 possibility of encountering an implementation-dependent 3328 reason for failing "framebuffer completeness" would be 3329 greatly reduced or perhaps entirely eliminated. 3330 3331 In any event, specifying this "FormatRestriction" API was 3332 going to take additional time and we wished to get this base 3333 EXT_framebuffer_object specification done and shipping as 3334 soon as possible. So we agreed to defer this "format 3335 restriction" API specification to a later extension, with 3336 the intent to develop this API or some other solution to 3337 this problem as soon as possible. 3338 3339 (13) Do we need intrinsic buffers in addition to renderbuffers? 3340 3341 RESOLUTION: no 3342 3343 When intrinsic buffers were initially proposed, the format 3344 and dimensions of an intrinsic buffer could mutate in order 3345 to provide compatibility with the other images attached to a 3346 framebuffer object. After much debate and a series of 3347 votes, intrinsic buffers had lost both of those properties. 3348 (See issue 36.) In the end the working group decided that 3349 the crippled form of intrinsic buffers do not provide enough 3350 added value to justify their existence. 3351 3352 (14) Is it necessary to require that all the logical buffers of a 3353 framebuffer object have the same dimensions? 3354 3355 RESOLUTION: Yes. Matching dimensions are required for 3356 simplicity. If the dimensions do not match, the framebuffer 3357 object will not be "framebuffer complete". 3358 3359 It could be useful to use a single large depth buffer when 3360 rendering to many textures of several different sizes. This 3361 is something that could be added later by a layered 3362 extension that relaxes the matching dimension restriction. 3363 Supporting heterogeneous sized logical buffers requires 3364 defining where in a larger buffer the smaller results are 3365 written, and deciding what guarantees can be made and what 3366 should be left undefined. 3367 3368 (15) What happens when TexImage or CopyTexImage is called on a 3369 texture image that is attached as an image of the 3370 currently bound framebuffer object? 3371 3372 RESOLUTION: resolved, {Copy}TexImage will redefine the 3373 texture image, which can affect the completeness of the 3374 framebuffer to which it is attached, and possibly cause the 3375 currently bound framebuffer to start failing the framebuffer 3376 completeness test. 3377 3378 As far as {Copy}TexImage (or RenderbufferStorage) are 3379 concerned, there is nothing "special" about a texture image 3380 (or renderbuffer) attached to a framebuffer object. Attempts 3381 to redefine attached images in this manner should succeed. 3382 However, if the redefined image is no longer appropriate for 3383 the relevant attachment point in the framebuffer it is 3384 attached to, then it's possible the framebuffer may start 3385 failing the framebuffer completeness test. 3386 3387 Another option that was considered involved having TexImage 3388 and CopyTexImage result in INVALID_OPERATION and do nothing 3389 when the target texture is bound for render-to-texture. This 3390 idea was rejected because, in the multicontext case, one 3391 context could change the attachments of a shared framebuffer 3392 and cause another context to suddenly start generating 3393 errors on {Copy}TexImage calls. This extension has tried to 3394 avoid introducing asynchronous generation of gl errors. 3395 3396 Still another option that was considered was "orphaning" the 3397 old texture memory such that it could still be used as a 3398 framebuffer attachment but the texture would get newly 3399 allocated storage. However, this implied a side-ways copy 3400 of the texture object memory or the image for its continued 3401 use as a framebuffer-attachable image, and was therefore 3402 rejected. 3403 3404 For the purposes of comparison, consider that 3405 ARB_render_texture faced a similar question and resolved it 3406 by implicitly unbinding the texture from the pbuffer when 3407 TexImage is called. 3408 3409 (16) What happens when TexImage or CopyTexImage is called on a 3410 texture object that is attached as an image of a 3411 framebuffer object that is not bound to the current context? 3412 3413 RESOLUTION: resolved, {Copy}TexImage will redefine the 3414 texture image, which can affect the completeness of the 3415 framebuffer object to which it is attached. When the 3416 framebuffer object is bound to the context, it may start 3417 failing the framebuffer completeness test. If the 3418 framebuffer object is bound in another context at the time 3419 {Copy}TexImage is called, then the framebuffer object may 3420 start failing the framebuffer completeness test in the other 3421 context. 3422 3423 The rationale for this decision is the same as for issue 3424 (15). 3425 3426 However, since in this case the relevant framebuffer is not 3427 current, there is no guarantee that this framebuffer 3428 revalidation or invalidation will happen until the next time 3429 the framebuffer is bound to a context. 3430 3431 The texture (or renderbuffer) state is changed immediately, 3432 regardless of whether the texture image (or renderbuffer) is 3433 attached to a framebuffer object. However, a context other 3434 than the one issuing the {Copy}TexImage operation might not 3435 notice the state change until after it has (re)bound the 3436 framebuffer object or reattached the texture image. 3437 3438 This is intended to be similar to what happens in the 3439 multicontext case when the state of a shared texture object 3440 is changed by another context. There is no guarantee that 3441 texture state change will be visible in the current context 3442 until the current context binds the texture object again. 3443 3444 (17) Why is render to vertex array missing? 3445 3446 RESOLUTION: Render to vertex array is separate functionality 3447 from render to logical buffer or render to texture. RTVA 3448 can be added as a separate extension. The framework is 3449 general enough to support more than one way of adding RTVA, 3450 without deciding today on the details of a particular RTVA 3451 implementation. 3452 3453 One idea is to define a way to interpret a vertex array or 3454 buffer object, which is inherently byte-oriented linear, as 3455 a framebuffer, which is inherently component-oriented and 3456 dimensioned, and then call FramebufferArrayEXT like this: 3457 3458 FramebufferArrayEXT(FRAMEBUFFER_EXT, COLOR, buffer_obj); 3459 3460 Another idea is to define a general way to interpret a 3461 component-oriented dimensioned image, such as a texture or a 3462 color buffer, as a byte-oriented vertex stream. Using this 3463 approach one would render vertex attributes to a 3464 renderbuffer, to a texture image, or to an AUX buffer, and 3465 then use the image data directly as a vertex array. 3466 3467 There is controversy over which RTVA method(s) should be 3468 supported. One goal of EXT_framebuffer_object is to ship 3469 render-to-texture and render-to-logical-buffer functionality 3470 today while leaving the door open to add one or more RTVA 3471 solutions in the future. 3472 3473 (18) What function should perform the action of attaching a texture 3474 image to a framebuffer for rendering purposes? 3475 3476 RESOLUTION: The new FramebufferTexture*EXT functions perform 3477 this action. 3478 3479 Options that were considered include overloading 3480 BindTexture, using a FramebufferParameter function, and 3481 adding a new function. 3482 3483 BindTexture is problematic because it creates a new texture 3484 object with default state if the name is previously unused, 3485 but the default state has no dimensions, dimensionality, or 3486 format. 3487 3488 One reason that FramebufferTexture*EXT was well-received is 3489 because it sets, in one atomic operation, all framebuffer 3490 attachment state for both texture image and renderbuffer 3491 type of attachments. Given the polymorphic nature of 3492 framebuffer-attachable images, this guarantees that all 3493 framebuffer attachment state is in a consistent 3494 configuration, without having to define confusing precedent 3495 rules between competing (texture image and renderbuffer) 3496 pieces of framebuffer attachment state, or having to create 3497 enables (either a tri-state enable or separate enables again 3498 with precedence) to select texture image or renderbuffer 3499 attachment state as the "active" set of state. 3500 3501 This decision also makes it simpler to specify how a 3502 framebuffer-attachable image is detached from a 3503 framebuffer--it would be confusing if detaching a texture 3504 image resulted in *attaching* a renderbuffer simply because 3505 texture image attachment state takes precedence over 3506 renderbuffer image attachment state. 3507 3508 (19) What should happen if the texture argument given to 3509 FramebufferTextureEXT is an unused texture name? And 3510 similarly, what should happen if the renderbuffer argument 3511 given to FramebufferRenderbufferEXT is an unused renderbuffer 3512 name? 3513 3514 RESOLUTION: resolved, (a) this is an error. 3515 3516 Options included: 3517 3518 a) throw an error at Framebuffer{Texture|Renderbuffer} 3519 3520 b) texture/renderbuffer is created just like 3521 Bind{Texture|Renderbuffer} 3522 3523 c) no error, but the framebuffer cannot be "framebuffer 3524 complete" until a texture/renderbuffer by that name 3525 has been created and satisfies the rules of 3526 framebuffer completeness. 3527 3528 This is interesting because on the one hand we might like to 3529 adopt the model that we simply catch all the invalid state 3530 combinations when determining framebuffer completeness, 3531 i.e., option (c). This has a certain consistency but then 3532 what does it mean to call FramebufferTexture{1D|2D|3D} when 3533 the target of the texture name is not yet known? How should 3534 the other arguments to those calls be validated? 3535 3536 Option (b) was rejected as it would introduce a second way 3537 to create a texture/renderbuffer object. I.e., both 3538 BindTexture and FramebufferTexture would create the texture 3539 object. 3540 3541 Since there are "target aware" FramebufferTexture{1D|2D|3D} 3542 calls, the app already has to know the target prior to 3543 calling FramebufferTexture. Also, the texture target of a 3544 given object is immutable once set. An app can not set it 3545 and then change it later so this is really just an issue 3546 with the order in which they call the relevant functions. 3547 Consequently, requiring that the user call BindTexture prior 3548 to calling FramebufferTexture does not seem to be a burden. 3549 So this should be an error, since it's probably a mistake on 3550 the user's part in the first place. 3551 3552 (20) What should happen if the texture argument given to 3553 FramebufferTextureEXT is the name of an existing texture 3554 object, but the texture has no texture image (i.e., TexImage 3555 has never been called)? Similarly what should happen if the 3556 renderbuffer argument given to FramebufferRenderbufferEXT is 3557 the name of an existing renderbuffer, but the named 3558 renderbuffer has no storage (i.e., RenderbufferStorage has 3559 never been called?) 3560 3561 RESOLUTION: resolved, option (c) - no error, but the 3562 framebuffer object cannot be "framebuffer complete" until 3563 the state of the texture image satisfies the rules of 3564 framebuffer completeness. 3565 3566 Same options as issue (19), these include: 3567 3568 a) throw an error at Framebuffer{Texture|Renderbuffer} 3569 3570 b) texture/renderbuffer is created just like 3571 Bind{Texture|Renderbuffer} 3572 3573 c) no error, but the framebuffer cannot be "framebuffer 3574 complete" until the texture image or renderbuffer 3575 satisfies the rules of framebuffer completeness. 3576 3577 This is an issue because you could be attempting to attach a 3578 texture (or renderbuffer) to a framebuffer attachment point 3579 prior to the application having called TexImage (or 3580 RenderbufferStorage) to define the width/height/format of 3581 the framebuffer-attachable image. 3582 3583 At first, this seems similar to issue (19), so we could 3584 throw an error in this case too. It is different for two 3585 reasons however. First, there are default values for the 3586 texture object and renderbuffer object state. Second, the 3587 values of the width/height/format/etc for the texture object 3588 are mutable, unlike the texture target of the texture 3589 object. There is really no difference between the case 3590 where GL uses the default values for an object, and the case 3591 where the user explictly set the state equivalent to the 3592 default values using TexImage (or RenderbufferStorage). 3593 Because this state is mutable, it must be tested anyway when 3594 framebuffer completeness is determined. 3595 3596 Therefore, we simply defer the check for whether the 3597 texture/renderbuffer state is appropriate for the 3598 framebuffer attachment point until determination of 3599 framebuffer completeness. If the state is not valid, then 3600 the framebuffer will not be complete, regardless of whether 3601 or not TexImage/RenderbufferStorage has been used to create 3602 storage for the texture level (renderbuffer). 3603 3604 (21) What happens when DeleteTextures is called on a texture that is 3605 attached to a framebuffer object? Similarly, what happens when 3606 DeleteRenderbuffers is called on a renderbuffer that is 3607 attached to a framebuffer object? 3608 3609 RESOLUTION: resolved, see issue (77) 3610 3611 (22) How do you detach a texture or renderbuffer from a framebuffer 3612 object? Should we use two routines or create a detach routine? 3613 3614 RESOLUTION: resolved, 2 routines 3615 3616 If the user calls either FramebufferTexture with a zero 3617 texture name, or FramebufferRenderbuffer with a zero 3618 renderbuffer name, then the it as if nothing is attached to 3619 the specified attachment point. 3620 3621 There was a concern that having two routines be able to set 3622 the framebuffer attachment state to "none" was confusing. 3623 However, the idea is simply that for any object that can be 3624 attached to a framebuffer, there should be a routine that 3625 can set up the attachment and return the framebuffer to the 3626 default "nothing attached" state. 3627 3628 The implication here is that the default state for 3629 framebuffer attachments is: 3630 attachment object type = GL_NONE, and 3631 attached object name = 0 3632 3633 (23) Should it be legal for the framebuffer state to pass through 3634 invalid configurations? (I.e., depth and color buffer sizes 3635 don't match, etc) 3636 3637 RESOLUTION: resolved, "yes" 3638 3639 It's easier for the application if the render target state 3640 is allowed to pass through invalid configurations when 3641 transitioning between two valid configurations. A 3642 consistency check is defined to determine if a configuration 3643 is valid. 3644 3645 As long as everything is valid at render time, transient 3646 invalid states are allowed. 3647 3648 (24) What happens when you try to draw to a framebuffer that 3649 is not "framebuffer complete"? 3650 3651 RESOLUTION: resolved, rendering is disabled, and an error is 3652 generated. See issue (64) as this issue is essentially a 3653 duplicate of that one. 3654 3655 (25) What should happen on a query of framebuffer state while the 3656 framebuffer is invalid? For instance, what does a query of 3657 RED_BITS return if the currently bound framebuffer is not 3658 "framebuffer complete"? 3659 3660 RESOLUTION: resolved, there's no issue here. Attempts to 3661 query bit depths should return the "real" answers. 3662 3663 For instance, if there's no color buffer attached to the 3664 framebuffer attachment point, then attempts to return 3665 RED_BITS could return zero. If there is a color-renderable 3666 image attached, then RED_BITS would return whatever the 3667 RED_BITS are, regardless of the valid/invalid state of the 3668 framebuffer. 3669 3670 Other options include returning some kind of magic value or 3671 generating an error if the framebuffer is invalid. However, 3672 any "magic value" would simply be a duplicated query for the 3673 framebuffer completeness status. Also, returning an error 3674 would be problematic because another context can make a 3675 framebuffer invalid and we have been trying to avoid any API 3676 in which one context can cause another context to start 3677 generating errors asynchronously. 3678 3679 (26) What happens when you try to read (e.g. ReadPixels) from a 3680 framebuffer that is not "framebuffer complete"? Reads cannot 3681 be "disabled" or "ignored" in the same way that rendering can. 3682 3683 RESOLUTION: resolved, generate a GL error. See issue (65). 3684 3685 Originally this was resolved as "undefined pixels are 3686 generated, but no error" 3687 3688 Initially, generating an error was rejected for a few 3689 reasons. First, it is asymmetric with the behavior for 3690 drawing - when the framebuffer is not complete, drawing is 3691 disabled. We would like to be consistent here. Second, 3692 there are no other cases where ReadPixels or 3693 CopyTex{Sub}Image will generate an error based on the state 3694 of the framebuffer and we didn't want to introduce one. 3695 Third, there is already a pixel ownership requirement in 3696 order to get defined results back from reading the 3697 framebuffer, so if we simply behave as if incomplete 3698 framebuffer fails ths pixel ownership test, then we can 3699 leverage that already specified behavior for reading the 3700 framebuffer. 3701 3702 For these reasons, we initially choose to have reads from an 3703 incomplete framebuffer return undefined pixel values and not 3704 generate a GL error. 3705 3706 However, once we subsequntly resolved issue (64) to say that 3707 rendering with an incomplete framebuffer generates an error, 3708 we decided again for reasons of symmetry that reading from 3709 an incomplete framebuffer should also generate an error. 3710 (And most likely the same error.) 3711 3712 So in the end, we decided that reads (e.g., ReadPixels and 3713 CopyTex{Sub}Image) in this case would result in an error to 3714 be named in issue (65). 3715 3716 See also related issue (73), describing ReadPixels of color 3717 data from a complete framebuffer while READ_BUFFER is NONE. 3718 3719 (27) What happens when you query the number of bits per channel 3720 (e.g., DEPTH_BITS) prior to the consistency check being run 3721 when intrinsic buffers are in use, since implementations are 3722 allowed to select a number of bits for an intrinsic buffer at 3723 consistency check time to give a better chance of a consistent 3724 state being reached? 3725 3726 RESOLUTION: This is not an issue since we don't have 3727 intrinsic buffers, see issue (13). We are keeping this 3728 issue in the issues list just in case we ever go back and 3729 add something like this to a future API. 3730 3731 If we would have retained the intrinsic buffer api (i.e., 3732 glFramebufferStorage) or if some future API adds it back in, 3733 then one possible resolution of this problem would have been 3734 to simply say that a query of the number of bits prior to 3735 the consistency check being run will produce an answer that 3736 is subject to change. 3737 3738 This is preferable to some other possible resolutions that 3739 have been discussed (e.g., having the query cause a 3740 validation to occur implicitly, thereby "baking" in the 3741 answer) because it is the one least likely to introduce 3742 unexpected side-effects to an operation as seemingly 3743 innocuous as a query. 3744 3745 A possible variant of this proposed resolution would have 3746 been to have the query return a number of bits that is 3747 guaranteed to be less than or equal to the actual number of 3748 bits that will eventually be used. This may or may not be a 3749 useful guarantee. We could have also had the query return 0 3750 or -1 as a signal that the framebuffer is incomplete. 3751 3752 Again, this is all moot since we decided against this style 3753 of intrinsic buffers in this extension. 3754 3755 (28) What should the <image> parameter to FramebufferTexture3DEXT 3756 actually be called? 3757 3758 RESOLUTION: resolved, "zoffset" 3759 3760 This parameter could have been called <image> or <slice>. 3761 <depth> or <zoffset> might also be appropriate. The reason 3762 the answer here is non-obvious is that normally 3D textures 3763 are specified all at once, not one 2D "slice" at a time 3764 (TexImage3D takes one big array that represents all three 3765 dimensions at once, for example), and because texture 3766 coordinates for TEXTURE_3D targets are normalized 3767 floating-point numbers, just as they are with TEXTURE_2D 3768 targets, not integer indices. 3769 3770 The GL uses the term "image" to mean "slice" in a few 3771 instances. For example, pixel unpack parameters 3772 UNPACK_SKIP_IMAGE and UNPACK_IMAGE_HEIGHT describe state 3773 related to the "slices" a 3d texture. 3774 3775 However, in some ways the act of rendering into a texture is 3776 most similar to CopyTexSubImage3D, which also redefines a 3777 texture's contents (but never its format or dimensions) based 3778 on the contents of the framebuffer. The "zoffset" parameter 3779 to CopyTexSubImage selects a particular 2D image (depth 3780 "slice") of a 3-dimensional texture. "zoffset" is a 3781 coordinate, and the parameter to FramebufferTexture3DEXT is 3782 also a coordinate. "Image" typically refers to an array of 3783 pixels. 3784 3785 We already use the term "image" throughout this extension to 3786 talk about 2d arrays of pixels beyond their use in 3D 3787 textures. It is a little confusing to overload "image" to 3788 also mean Z coordinate in FramebufferTexture3DEXT. 3789 3790 For the sum of these reasons, we decided "zoffset" is a 3791 better name than "image", for the parameter to 3792 FramebufferTexture3DEXT. 3793 3794 (29) Should GenerateMipmap functionality be included in this 3795 extension or put in it's own extension? 3796 3797 RESOLUTION: resolved, yes, include this functionality 3798 3799 It is arguably useful separately, i.e., without all this 3800 machinery. However, it's also kind of required here to have 3801 some kind of way to deal with the interaction with 3802 SGIS_generate_mipmap. Probably we should just include it 3803 here. (maybe also a separate extension?) 3804 3805 It's easier to define when automatic mipmap generation 3806 happens for a traditional non-rendered texture than it is 3807 for a texture that is modified by rendering-to-texture. If 3808 GENERATE_MIPMAP were to cause a rendered-texture's mipmaps 3809 to be automatically generated, presumably generation would 3810 occur when either the texture is detached from the 3811 framebuffer or when the framebuffer is unbound. If neither 3812 of these events occur, should automatic mipmap generation 3813 also occur when the texture is bound to a texture unit (of 3814 same or different context?) 3815 3816 It's believed the recommended way of achieving maximum 3817 performance using this extension is to make all attachments 3818 during initialization, and then not change attachments in 3819 the steady state. This reasoning is, after all, a major 3820 reason for introducing framebuffer objects. If an 3821 application does not detach textures from framebuffers, then 3822 what event triggers mipmap generation? An explicit 3823 GenerateMipmap works well here. 3824 3825 Would the base level have to actually be modified in order 3826 for mipmap generation to occur? How should "modified" be 3827 defined? 3828 3829 If the application rendered to each level of the texture 3830 before detaching the texture or unbinding the framebuffer, 3831 would automatic mipmap generation happen anyway? (This 3832 implies the application needs to set GENERATE_MIPMAP to 3833 FALSE before rendering to the texture, but maybe that's OK.) 3834 3835 Historical background: One reason for introducing 3836 GenerateMipmap in the context of the original uber_buffers 3837 proposal was that uber_buffers lacked a Begin-time 3838 consistency check, but instead prevented the framebuffer 3839 from ever getting into an inconsistent state (once 3840 validated). Operations such as TexImage that can change the 3841 dimensions and format of a tetxture's levels were disallowed 3842 when the texture was attached to a framebuffer. Since 3843 automatic mipmap generation can change the dimensions and 3844 format of a texture's levels, that meant that automatic 3845 mipmap generation could not be performed in some cases, but 3846 there was no good way to communicate this error to the 3847 application. Hence there really was a need for a separate 3848 GenerateMipmap function. This restriction does not apply 3849 to the current API because the semantics of an incomplete 3850 framebuffer are different now. Nevertheless, we decided to 3851 retain this manual mipmap generation as part of this 3852 extension. 3853 3854 (30) Do the calls to deal with renderbuffers need a target 3855 parameter? It seems unlikely this will be used for anything. 3856 3857 RESOLUTION: resolved, yes 3858 3859 Whether we call it a "target" or not, there is *some* piece 3860 of state in the context to hold the current renderbuffer 3861 binding. This is required so that we can call routines like 3862 RenderbufferStorage and {Get}RenderbufferParameter() without 3863 passing in an object name. It is also possible we may 3864 decide to use the renderbuffer target parameter to 3865 distinguish between multisample and non multisample buffers. 3866 Given those reasons, the precedent of texture objects, and 3867 the possibility we may come up with some other renderbuffer 3868 target types in the future, it seems prudent and not all 3869 that costly to just include the target type now. 3870 3871 (31) What should happen if you call FramebufferTexture{1D|2D|3D} 3872 with a texture name of zero? 3873 3874 RESOLUTION: This will detach the image from the specified 3875 attachment point in the currently bound framebuffer object. 3876 3877 For reference, this reason this is problematic because there 3878 is not really a "texture object zero" 3879 3880 Texture name zero does not define an object but defines 3881 context state (one texture named zero, per target, per 3882 context). The textures referred to by the name zero are 3883 never shared across contexts. So the behavior of 3884 framebuffer objects shared by multiple contexts where each 3885 is attached to the context's texture named zero seems odd at 3886 best, and confusing at worst. As such, it was decided to 3887 not allow a framebuffer to attach to texture named zero. 3888 3889 Another option would have been to make this an error. If we 3890 had done this, then we would need a specific function to 3891 detach a texture from an attachment point. That is, we 3892 would have needed to create something like a dedicated 3893 DetachFramebufferAttachableImage() entry point. 3894 3895 (32) Should there be a renderbuffer object with the name of zero? 3896 3897 RESOLUTION: NO. 3898 3899 By way of symmetry with textures, renderbuffer zero, if it 3900 existed, would not be an object. It would be a 3901 non-shareable piece of the context state. There would be 3902 one renderbuffer named zero per target per context. 3903 3904 If we can't share renderbuffer name zero, then also by way 3905 of symmetry with textures, we would not want to support 3906 attaching renderbuffer name zero to a framebuffer. 3907 3908 So, if it can't be used as a rendering destination, then a 3909 renderbuffer name zero would seem to serve no purpose as a 3910 state container. 3911 3912 However, we'd like to retain the use of name zero in certain 3913 routines with special semantics, particularly for detaching 3914 non-zero renderbuffer objects from the framebuffer and 3915 context. See issue (33). 3916 3917 On implication of this decision is that state 3918 setting/getting routines that operate on the currently bound 3919 renderbuffer should throw a GL error if no renderbuffer is 3920 bound/attached. A similar choice was made in the 3921 ARB_vertex_buffer_objects specification which also had 3922 special semantics for object zero. 3923 3924 Also note, another option considered was making object zero 3925 a full fledged, shareable object just like the non-zero 3926 object names. This was rejected as being too different from 3927 texture/program vbo's/etc., possibly leading to confusion. 3928 3929 (33) What should happen if you call FramebufferRenderbuffer or 3930 BindRenderbuffer with a renderbuffer name of zero? 3931 3932 RESOLUTION: This will detach the image from the 3933 specified attachment point in the currently bound 3934 framebuffer object. 3935 3936 This is resolved exactly the same way as issue (31) was 3937 resolved for textures, and for the same reasons. 3938 3939 Similarly, calling BindRenderbuffer with a name of zero will 3940 unbind the currently bound renderbuffer from the context. 3941 3942 (34) Should there be a way to query a framebuffer object for its 3943 attached texture and/or renderbuffers? If so, how, and 3944 what should be the query result when attached textures or 3945 renderbuffers have been deleted? 3946 3947 RESOLUTION: resolved, yes 3948 3949 In general, OpenGL lets you query settable state, so 3950 we allow this. 3951 To see what this query should look like, see related 3952 issue (51) 3953 3954 This issue also raises the question about what values should 3955 be returned for attached objects if the named objects have 3956 since been deleted. This can happen if the textures were 3957 attached to non-currently bound framebuffers or attached to 3958 framebuffers in other contexts. Three possible solutions 3959 include: 3960 3961 a) Don't support this query. 3962 3963 b) Return zero if no texture has ever been attached. 3964 Return zero if the attached texture has been deleted. 3965 3966 c) Return zero if no texture has ever been attached. 3967 Return the name of the texture that was attached even 3968 though it has been deleted. 3969 3970 Option (a) was rejected as we would like settable state 3971 to be queriable. 3972 3973 So, for this extension originally we choose option (c). 3974 However, we have since decided, in issue (21), that 3975 DeleteTexture and DeleteRenderbuffer will first detach 3976 the texture/renderbuffer from any attached framebuffer 3977 objects *in this context*. In principle, the 3978 application can't tell the difference between the 3979 texture getting deleted now or later, so whether the 3980 texture is actually detached from the current 3981 framebuffer now and other framebuffers when they are 3982 bound, or the texture is actually detached from all 3983 framebuffers at once is moot. In practice, this means 3984 that options (b) and (c) are essentially 3985 indistinguishable for a single context case. 3986 3987 However, it's worth noting that if the texture is 3988 deleted and attached to a framebuffer which is current 3989 in another context, the standard rules about undefined 3990 behavior of state modifcations of shared objects in 3991 other contexts will still applye. 3992 3993 This means that the texture may or may not be detached 3994 (and thus deleted) from that other context's current 3995 framebuffer until the next BindFramebuffer (or 3996 FramebufferTexture/FramebufferRenderbuffer?) in the 3997 other context. 3998 3999 (35) Earlier proposals included a way to create some memory and then 4000 attach it to a texture object. Should this extension include 4001 this feature? 4002 4003 RESOLUTION: no. 4004 4005 This was considered when this extension was intended 4006 to be a more general purpose memory manager. Since this 4007 extension has been retasked to focus in on render-to-X 4008 functionality, this feature was not necessary. 4009 4010 (36) Earlier proposals had renderable memory constructs which could 4011 change internal format or dimensions to meet intra-framebuffer 4012 compatibiltiy requirements of individual vendors' hardware 4013 platforms. Should this extension have these kind of malleable 4014 format objects? 4015 4016 RESOLUTION: no. 4017 4018 Such malleability leads to invariance problems when formats 4019 change. For example, if bits per pixel is decreased then 4020 increased back to the original value, some precision is 4021 lost. 4022 4023 Some IHVs wanted to require format conversion of existing 4024 contents in all cases where the format changes. This sort 4025 of invariance would be an acceptable side-effect. The 4026 suggestion was to think of the action of rendering to a 4027 texture as an extended non-atomic TexImage call. TexImage 4028 is allowed to change the format of an existing texture 4029 image. It was claimed that such intrinsic buffers are more 4030 convenient in many applicaitons than are the explicitly 4031 managed renderbuffers. 4032 4033 Other IHVs expressed a strong opinion against implicit 4034 format conversions, but instead wanted to invalidate the 4035 buffer's contents whenever the format changed. It was 4036 difficult to define the set of operations that might cause 4037 the format to change, so it was difficult to define when the 4038 contents could become invalidated. If the contents were 4039 invalidated by a format change, the API under consideration 4040 made it cumbersome for the application to detect and handle 4041 this condition. In the end, under the buffer content 4042 invalidation approach, application code would not be any 4043 better off than if the appliation instead used the explicit 4044 renderbuffers. For the type of intrinsic buffers that could 4045 not change format and dimensions dynamically, the claim that 4046 intrinsic buffers were more convenient than renderbuffers 4047 was no longer true. 4048 4049 The working group voted for the latter: no implicit format 4050 changes. Instead the format would be immutable once it is 4051 known. 4052 4053 A secondary issue is the question: are the buffer contents 4054 invalidated when the dimensions change, are the contents 4055 scaled, or are the contents are clipped/padded (with some 4056 sort of gravity). This issue could be avoided by requiring 4057 explicit, rather than implicit, resize of intrinsic buffers. 4058 4059 The working group voted for no implicit change in the 4060 dimensions of intrinsic buffers, and finally for the removal 4061 of intrinsic buffers altogether. 4062 4063 (37) In order to abstract hardware dependent compatibility 4064 requirements, this API introduces a function called 4065 CheckFramebufferStatus to check for compatibility prior to 4066 rendering. CheckFramebufferStatus returns a value which 4067 indicates whether or not the framebuffer object is "framebuffer 4068 complete", and framebuffer completeness depends in part on 4069 hardware dependent constraints. The hardware dependent aspect 4070 represents a new concept in OpenGL. Therefore, should an app 4071 be required to call this function to help "enforce" the notion 4072 that apps should be on the lookout for failure? 4073 4074 RESOLUTION: no. Calling CheckFramebufferStatus is not 4075 required. 4076 4077 The group considered requiring a call to 4078 CheckFramebufferStatus after changing framebuffer state or 4079 attachment points in order to "enable" rendering. It was 4080 hoped that requiring a call to CheckFramebufferStatus would 4081 push developers to write code which is more platform 4082 independent. Ultimately though, since the API can't require 4083 applications to actually observe and deal with a validation 4084 failure, that it was not worth it to make this function call 4085 required. There was also feedback from some developers that 4086 requiring this call would be cumbersome and undesirable. 4087 4088 Note, however, that the framebuffer is effectively validated 4089 implicitly at every rendering (and reading) entry point. 4090 These include glBegin, gl{Multi}Draw{Arrays|Elements}, 4091 gl{Draw|Copy|Read}Pixels, glCopyPixels, glReadPixels, 4092 glCopyTex{Sub}Image, etc. 4093 4094 Applications are strongly advised to test framebuffer 4095 completeness with CheckFramebufferStatus after setting up or 4096 changing the configuration of a framebuffer object, and to 4097 handle the possible failure cases with a fallback plan that 4098 selects a different set of internal formats of attached 4099 images. See usage example 6. Section 4.4.4.2 lists the 4100 operations that can cause the framebuffer's status to 4101 change. 4102 4103 In addition, a "format group" API, has been proposed as a 4104 means of programmatically determining a set of internal 4105 formats that are guaranteed to be compatible with respect to 4106 framebuffer completeness. This API would be specified in a 4107 layered extension as suggested in issue (12) 4108 4109 (38) Do we need to support multiple render targets, i.e., 4110 ARB_draw_buffers? 4111 4112 RESOLUTION: Yes. 4113 4114 ARB_draw_buffers is going to be part of OpenGL 2.0 so we'd 4115 better support it. 4116 4117 (39) How should we support ARB_draw_buffers? 4118 4119 RESOLUTION: refactored into the following issues: 4120 (53), (54), (55), (56), and (57) 4121 4122 (40) (How) should we support accum buffers? 4123 4124 RESOLUTION: defer this until (shortly) after this extension. 4125 4126 Accum buffers appears to be very simple to specify and 4127 implement. Basically, we would need to add a new internal 4128 ACCUM format that can be passed to RenderbufferStorage. We 4129 would also need to add an ACCUM attachment point in the 4130 framebuffer that could be used to point to one of these 4131 ACCUM format renderbuffers. A new ACCUM format is needed 4132 because the ACCUM buffer is defined by GL to be signed 4133 floating point value, unlike other internal formats. 4134 4135 Also note, the above solution is the exact same one we are 4136 using for STENCIL buffers as well (i.e., an internal format 4137 enum and an attachment point). 4138 4139 We could also decide if this new ACCUM internal format can 4140 be used with textures in addition to renderbuffers, for 4141 creating images that can be attached to the accum buffer 4142 attachment point. 4143 4144 Supporting accum was deferred for this extension, primarily 4145 for time-to-market reasons, and as it was not critical for 4146 most render-to-texture applications. However, we intend to 4147 work on some kind of "EXT_accum_renderbuffer" extension 4148 shortly. 4149 4150 Since this was deferred, we need to define what happens when 4151 you call the various Accum operations on a non-default 4152 framebuffer object. We considered adding spec language that 4153 would generate an error on Accum operations. However, it 4154 seems like we can simply leverage whatever legacy behavior 4155 is currently defined for when the pixel format has no accum 4156 buffer. This is the case in this extension as we have 4157 defined no way to attach or enable an accum buffer. Chapter 4158 4 on page 188 already says that "If there is no accumulation 4159 buffer, or if the GL is in color index mode, Accum generates 4160 the error INVALID OPERATION", so we don't actually need any 4161 additional language of our own. 4162 4163 (41) (How) should we support multisample buffers? 4164 4165 RESOLUTION: defer this until (shortly) after this extension. 4166 4167 Supporting multisample was deferred for this extension, 4168 primarily for time-to-market reasons and because it's not 4169 entirely clear what is the "best" API for exposing 4170 multisample. However, we intend to work on some kind of 4171 "EXT_multisample_renderbuffer" extension shortly. 4172 4173 Since this feature was deferred, we need to define what 4174 happens when you try to enable multisample on a non-default 4175 framebuffer object. For now we need some way to *not* do 4176 multisampling. This can either be that we set SAMPLES 1 and 4177 SAMPLE_BUFFERS to 0, or we say that 4178 Enable/Disable(MULTISAMPLE) is ignored. This is actually 4179 related to issue (62) - should SAMPLE_BUFFERS change when 4180 using a non-default framebuffer or when attachments change? 4181 When/if we define and export "EXT_multisample_renderbuffer" 4182 extension, this state will again have significance. 4183 4184 A discussion of how we might support this feature follows: 4185 4186 There are several considerations here: First, we'd like 4187 something simple to specify, implement, and use. Second, 4188 we'd like to not delay this extension's approval, 4189 implementation or adoption for this particular feature. 4190 Third, we are trying to replace pbuffer functionality, which 4191 does support multisampling (at least in principle), so we'd 4192 like to not take a step backward in functionality if 4193 possible. 4194 4195 However, this extension is *not* trying to "improve" the 4196 traditional multisample support. If we do anything, we will 4197 simply expose the existing multisample buffer semantics 4198 without causing undue implementation burden. 4199 4200 Finally, if an implementation is currently taking short-cuts 4201 to GL's traditional "per-pixel-resolve" multisample 4202 semantics, we'd like for this extension to continue to allow 4203 the exact same short-cuts (to whatever extent the core GL 4204 spec does or does not allow those short-cuts). If someone 4205 later decides to go an revamp multisampling support in 4206 general, they can update this extension at the same time. 4207 4208 Given the above, it appears that the options include: 4209 4210 A) Don't support it. In other words, you can't use 4211 mulitsampling and EXT_framebuffer_object. The 4212 multisample state is either ignored, or causes the 4213 framebuffer to not be complete, or generates some kind 4214 of error. 4215 4216 B) Create a separate multisample renderbuffer that can be 4217 attached to a new framebuffer attachment point. 4218 4219 The reason that we might need a separate 4220 RESOLUTION_BUFFER is that all renderable color buffer 4221 formats might not be usable for multisampling on all 4222 implementations. 4223 4224 Also, this option would allow multiple framebuffers to 4225 share the storage for multisample buffers under the 4226 control of the application. 4227 4228 Depth sample buffers and stencil sample buffers 4229 wouldn't necessarily need resolution buffers, but that 4230 could be added by some future extension. 4231 4232 This option has several variants: 4233 4234 B1) Create MULTISAMPLE and/or RESOLUTION_BUFFER 4235 internal formats for renderbuffer objects that 4236 can be used with RenderbufferStorage. The 4237 samples buffer and the resolution buffer would be 4238 allocated and attached to the framebuffer 4239 separately. Having them be separate allows the 4240 samples to be deleted after rendering if desired. 4241 4242 One issue with this option is that somehow you'd 4243 need to specify the number of samples maybe using 4244 glFramebufferParameter or 4245 glRenderbufferParameter. 4246 4247 B2) Perhaps, instead of using a single internal 4248 format called MULTISAMPLE, use a set of internal 4249 formats like MULTISAMPLE_1_SAMPLE, 4250 MULTISAMPLE_2_SAMPLE, MULTISAMPLE_4_SAMPLE, etc. 4251 This is problematic for supporting depth/stencil 4252 multisampling unless we want an explosion of 4253 color/depth/stencil multisample internal formats. 4254 It's also problematic if MRT draw buffers need to 4255 be multisampled because we'd need a number of 4256 enums able to support 1 to N draw buffers times 4257 the number of sample patterns we support. 4258 4259 B3) Have RenderbufferStorage always take a number of 4260 samples. We could do this if option (B2) is 4261 insufficient due to the need to support DEPTH or 4262 STENCIL multisampling, which we probably will. 4263 We would then allow the internal format to choose 4264 DEPTH, STENCIL, or RGBA/etc. This is clean but 4265 it means that the user would always need to 4266 specify a number of samples even when the value 4267 is "1". 4268 4269 B4) Pass in a variable length argument list to the 4270 renderbuffer allocation routine, and some of the 4271 arguments would indicate intended usage 4272 (COLOR/DEPTH/MULTISAMPLE) others would indicate 4273 internal format (RGBA/DEPTH24) and others would 4274 indicate number of samples. This is how 4275 EXT_compromise_buffers dealt with this problem, 4276 though people didn't seem to like this variable 4277 length argument list. EXT_render_target didn't 4278 deal with this problem so doesn't offer any 4279 guidance here. 4280 4281 B5) Create a new RENDERBUFFER_MULTISAMPLE 4282 renderbuffer target type and a corresponding 4283 allocation routine, perhaps called 4284 RenderbufferMultisampleStorage(). This is 4285 analogous to how textures have their own 4286 allocation routine per target type 4287 (TexImage1D/2D/3D, etc). 4288 4289 With this option, we could preclude 4290 non-multisample targets from being attached to 4291 non-multisample attachment points as well. 4292 4293 B6-B10) Any of the above options can be implemented 4294 with either a single monolithic mulitsample 4295 buffer that contains the samples for all draw 4296 buffers, depth and stencil and a single 4297 attachment point, *OR* with independent 4298 multisample buffers for each draw buffer and 4299 depth and stencil and independent attachment 4300 points for each. 4301 4302 C) Use some kind of "behind the scenes" mulitsample buffer. 4303 4304 This option also has several variants: 4305 4306 C1) An "implicit" multisample buffer that is simply a 4307 property of the framebuffer object. Each 4308 framebuffer object could have its own multisample 4309 buffer(s). Multisampling would be enabled with 4310 some kind of FramebufferParameter call. This 4311 implies that each framebuffer has memory 4312 allocated with it. It further implies that the 4313 contents of the multisample buffer are 4314 framebuffer state and are thus retained with the 4315 framebuffer object. 4316 4317 C2) We don't say anything except that we say the 4318 value of the glEnable(MULTISAMPLE) is still 4319 respected and we render as directed. This is 4320 similar to (C1) but we don't go so far as to say 4321 that the multisample buffer(s) is/are retained 4322 per framebuffer object. In other words, a call 4323 to BindFramebuffer() and changes to framebuffer 4324 attachments may or may not retain multisample 4325 buffer contents. Valid implmentations of this 4326 would include a multisample buffer per 4327 framebuffer or one per context. 4328 4329 D) something else (hopefully simpler?) 4330 4331 (42) What set of framebuffer targets should the initial extension 4332 support? 4333 4334 RESOLUTION: resolved, (D) single target 4335 4336 Basic possibilities include: 4337 4338 (A) DRAW_AND_READ_FRAMEBUFFER_EXT 4339 4340 (B) DRAW_FRAMEBUFFER_EXT 4341 READ_FRAMEBUFFER_EXT 4342 4343 (C) DRAW_FRAMEBUFFER_EXT 4344 READ_FRAMEBUFFER_EXT 4345 DRAW_AND_READ_FRAMEBUFFER_EXT 4346 4347 (D) FRAMEBUFFER_EXT 4348 4349 The fundamental question is: must framebuffer binding points 4350 mimic the expressiveness of the window-system function 4351 MakeContextCurrent, which is described in the glX spec and 4352 the ARB_make_current_read extension? 4353 4354 It was not immediately clear how to specify the distinction 4355 between a READ and a DRAW framebuffer in the context of the 4356 existing read/draw buffer semantics, given that this 4357 extension relaxes the "compatibility" requirement between 4358 read and draw drawables. How would the value of RED_BITS 4359 for the read framebuffer be queried if it is different than 4360 the value of RED_BITS for the draw framebuffer? What 4361 exactly is the set of implementation dependent state (see 4362 the "Implementation Dependent *" state tables in chapter 6) 4363 that can differ between read and draw framebuffer objects? 4364 4365 When using MakeContextCurrent, the context's and drawable's 4366 FBconfig (or pixel format) must be "compatible" or else the 4367 results are implementation dependent. But 4368 EXT_framebuffer_object cannot afford to swing such a large 4369 "undefined" stick, because it is more likely that 4370 framebuffer objects are incompatible in this sense, and 4371 because the "pixel format compatility" of a framebuffer 4372 object is dynamic--by changing attachments or redefining the 4373 internal format of an attached texture image. 4374 4375 The value added by ARB_make_current_read through 4376 MakeContextCurrent is less relevant to 4377 EXT_framebuffer_object. EXT_framebuffer_object enables 4378 rendering to a texture, and textures are objects with a 4379 clearly defined mechanism for use as the source of a pixel 4380 copy: rather than using CopyPixels to move pixels from the 4381 READ_BUFFER to the DRAW_BUFFER(s), an application can simply 4382 use the source data as a texture and then draw a 4383 screen-aligned textured quad to the framebuffer. 4384 4385 Additionally, adding separate DRAW and READ bindings in the 4386 future is pretty straightforward. One solution would be to 4387 say that FRAMEBUFFER_EXT is the DRAW framebuffer, and name 4388 the new READ framebuffer FRAMEBUFFER_READ_EXT. Add a new 4389 BindFramebuffer-like function which takes two framebuffer 4390 names--one for DRAW and one for READ. The current 4391 BindFramebuffer function binds a single object to both 4392 FRAMEBUFFER_EXT and FRAMEBUFFER_READ_EXT. 4393 4394 So, we defer the additional targets until need has been 4395 proven, and go with the simpler option (D) for now. 4396 4397 (43) In order for a framebuffer object to be "framebuffer complete", 4398 must all textures attached to the framebuffer be mipmap 4399 complete (or mipmap cube complete if cubemap texture)? 4400 4401 RESOLUTION: resolved, no 4402 4403 The reason this is a consideration is that some 4404 architectures require framebuffer-attachable images to be 4405 located in graphics memory when rendered to, and it may be 4406 more convenient to allocate and store a texture in graphics 4407 memory only if the texture is mipmap (cube) complete--i.e., 4408 the size and format of all levels are consistent in the 4409 normal sense of texture compeleteness. 4410 4411 However, since framebuffer attachment points only really 4412 deal with single images of a texture level, it seems 4413 excessive to require the state of the other levels of a 4414 texture to affect the validty of the framebuffer object 4415 itself. 4416 4417 Addtionally, the same difficulties around "incomplete" 4418 textures already apply to traditional CopyTexSubImage, and 4419 we have been trying to make the render-to-texture semantics 4420 similar to CopyTexSubImage. 4421 4422 Therefore, we chose not to treat render to texture any 4423 differently than CopyTexSubImage and do not require that the 4424 attached texture is mipmap (cube) complete. 4425 4426 (44) What should happen if a texture that is currently bound to the 4427 context is also used as an image attached to the 4428 currently bound framebuffer? In other words, what happens if a 4429 texture is used as both a source for texturing and a 4430 destination for rendering? 4431 4432 RESOLUTION: resolved, (b2) - results are undefined because 4433 the framebuffer is not "framebuffer complete". 4434 4435 Originally this was resolved as causing framebuffer to fail 4436 the completeness test--i.e., rendering would be disabled (b1) 4437 4438 As background, the reason this is an issue in the first 4439 place is that simultaneously reading from, and writing to, 4440 the same texture image is likely to be problematic on 4441 multiple vendors' hardware without paying performance 4442 penalties for excessive synchronization and/or data copying. 4443 4444 There are, however, certain cases where this functionality 4445 would arguably be useful, supportable, and well-defined. In 4446 particular, we can consider the case of custom mipmap 4447 generation using one level's image as source data to render 4448 into other levels of the same texture. 4449 4450 So, at a minimum, we would like to support rendering to a 4451 currently bound texture object if the source texture object 4452 has the BASE_LEVEL and MAX_LEVEL texture parameters set such 4453 that the level being used as a framebuffer-attachable image 4454 is excluded from texture fetches. 4455 4456 This was our original rationale: 4457 4458 a1) is problematic because one context could modify the 4459 base/max level on a shared texture causing another 4460 context which is using the texture as a destination to 4461 throw an error. This idea was rejected as it 4462 essentially meant that the error would need to be 4463 thrown at render timer which people found unacceptable. 4464 4465 b1) has the same kind of multicontext behavior but no 4466 error. One context can cause a framebuffer shared in 4467 another context to become invalid, but this is already 4468 true and can happen for a variety of reasons if the 4469 participating framebuffer-attachable images and/or 4470 framebuffer attachments are modified by either context. 4471 4472 At the time, we also considered the following 4473 questions: should the specification require the 4474 framebuffer to fail the framebuffer completeness test? 4475 Or is the framebuffer simply "allowed" to not be 4476 complete in this case? The latter choice would imply 4477 that the framebuffer might still be considered 4478 "framebuffer complete" on some implementations. See 4479 issue (46) 4480 4481 c1) is the easiest to specify and has an advantage that 4482 some implementations may be relying on this behavior 4483 already. However, this was rejected as it is the least 4484 portable of the three options. 4485 4486 We originally chose option (b1), though we considered that 4487 later on, individual hardware vendors may offer layered 4488 extensions that change this "framebuffer completeness" 4489 failure into a success with either defined or undefined 4490 rendering behavior. 4491 4492 However, this issue was re-opened becaues the subsequent 4493 resolution of issue (66) was that there should be no 4494 "context-dependent" reasons for framebuffer incompleteness. 4495 If we had stuck with option (b1), then we would be making 4496 the framebuffer completeness predicated on a piece of 4497 context state (the current texture binding). Consider the 4498 case where texture T is attached to a framebuffer. Then 4499 this would have meant that a framebuffer could be complete 4500 in one context (that didn't have texture T bound as a 4501 texture) and incomplete in another context (that did have 4502 texture T bound). 4503 4504 When reconsidering this issue, we realized that we would not 4505 throw an error at Begin time without disabling rendering, so 4506 we really only considered the following revised set of 4507 options: 4508 4509 a2) throw an error and disable rendering, but don't 4510 affect framebuffer completeness 4511 b2) the behavior is undefined 4512 4513 The issue was resolved the second time as: 4514 b2) Undefined behavior 4515 4516 Another option that was briefly considered was to make this 4517 another type of error (unrelated to trying to render with an 4518 incomplete framebuffer). However, part of the rationale for 4519 throwing an error at glBegin time when trying to render with 4520 an incomplete framebuffer was that if you already have to 4521 test for framebuffer completeness, then throwing an error is 4522 no additional implementation burden. Yet, since it was 4523 decided that the "texture-from-destination" condition is not 4524 part of framebuffer completeness - issue (66) - then it is 4525 an additional burden to perform the 4526 "texture-from-destination" check just so that an error can 4527 be generated. The concern was some implementations might 4528 not need to check for this case at all and we didn't want to 4529 burdern those implementations with an additional Begin-time 4530 error check. 4531 4532 Also, for what it's worth, if we had left the 4533 "texture-from-destination" case in the framebuffer 4534 completeness test then any language describing how 4535 framebuffer completeness is affected when a currently bound 4536 texture is used as both source and destination needs to be 4537 explicit that the texture has to be currently bound *and* 4538 enabled. For instance, consider the case where a user has a 4539 cubemap texture object name N bound to unit X and a 2D 4540 texture object name M also bound to unit X. What if the 4541 user would like to use the 2D texture M as a source while 4542 rendering to the faces of the cubemap texture N? We would 4543 like to support this scenario, so the language about a 4544 currently bound texture object would have needed to take the 4545 target into account. And to make matters more interesting, 4546 this means we would have needed to take texture enables and 4547 fragment shaders into account in this decision. In the end, 4548 we decided that "context-state" would not affect the 4549 defintion of framebuffer completeness we avoided this 4550 complexity (or at least moved it out of the framebuffer 4551 completeness test). 4552 4553 (45) Are framebuffer configurations with no color attachments allowed? 4554 4555 RESOLUTION: resolved, yes 4556 4557 The reason this is an issue is that the GL spec assumes 4558 there is always a color buffer. If a framebuffer with no 4559 images attached to any of the color buffer attachment points 4560 can be "framebuffer complete", then the core GL spec will 4561 need to be modified to relax the assumption that a color 4562 buffer always exists. 4563 4564 However, since one of the possible likely uses of this 4565 extnesion is to support depth texture rendering and stencil 4566 rendering for shadowing techniques, it seems like requiring 4567 an unused "dummy" color buffer in some cases is both 4568 inconvenient and a waste of memory. 4569 4570 Therefore, framebuffers do not require color attachments to 4571 be valid. Perhaps though we should require that a 4572 framebuffer with *no* attachments is invalid. 4573 4574 It also should be stated that attempting to render without 4575 the "appropriate" buffers attached needs to be defined. For 4576 instance, presumably, for depth rendering with no depth 4577 buffer attached, the depth test is disabled, as it is in 4578 traditional GL. 4579 4580 (46) In the framebuffer completeness criteria, this extension 4581 introduces the idea that rendering can fail for implementation 4582 dependent reasons. Framebuffer completeness also considers 4583 implementation *independent* reasons for failure. 4584 4585 Do we need to make special distinction between the cases where 4586 a framebuffer is not complete because of implementation 4587 dependent or because of implementation indepenent reasons? 4588 4589 RESOLUTION: resolved, yes, though this is really tied into 4590 how we resolve the minimum requirements for supporting this 4591 extension. See issue (61) 4592 4593 Examples where a framebuffer may be incomplete on some 4594 implementations but not others include: 4595 - 16 bit z-buffer used with 8 bit stencil buffer 4596 - 32 bit color buffer with 16 bit depth buffer 4597 - others? 4598 4599 Examples where framebuffer MUST be incomplete on all 4600 implementations include: 4601 4602 - color-renderable image attached to a non-color 4603 attachment point 4604 4605 - depth-renderable image attached to a non-depth 4606 attachment point 4607 4608 - stencil-renderable image attached to a non-stencil 4609 attachment point 4610 4611 - all images attached to a framebuffer do not have the 4612 same dimensions 4613 4614 - multiple render targets of different bit depths 4615 4616 - texture image attached to the framebuffer is part of a 4617 currently bound and enabled texture and the image is 4618 within the range of mipmap levels that can be fetched 4619 by rendering. 4620 4621 To make this determination we need to describe the criteria 4622 we should use to determine whether a framebuffer *can* or 4623 *must* be incomplete. 4624 4625 The arguments for putting state vectors into the "can" fail 4626 case is that a later extension can come along and simply 4627 relax those portions of the framebuffer completeness 4628 definiton with no additional API. State vectors classified 4629 as "must" fail cases would at least require the later 4630 extension to add an additional enable to start passing. 4631 4632 (47) Certain state-modification operations can cause a change to the 4633 validated state of a framebufffer. (I.e., can make a 4634 framebuffer that was complete become incomplete, or 4635 vice-versa). Do we want to list exactly which 4636 state-modification routines can cause this to happen? If so 4637 what is the list? 4638 4639 RESOLUTION: resolved, the answer is: yes we want to 4640 delineate exactly which routines can cause validation state 4641 changes. 4642 4643 Currently any routine which changes any of the following 4644 state can potentially cause framebuffer completness to 4645 change: 4646 4647 framebuffer state 4648 state changes to attached objects 4649 currently bound fragment program 4650 texture enable state 4651 4652 The list of operations that can cause framebuffer a change 4653 to framebuffer completeness are spelled out in section 4654 4.4.4.2. 4655 4656 (48) What information should be returned from 4657 CheckFramebufferStatusEXT()? 4658 4659 New RESOLUTION: resolved: 8 possible enum values, see issue 4660 (55) 4661 4662 Previous RESOLUTION: resolved, return one of three enumerated values: 4663 1. GL_FRAMEBUFFER_COMPLETE_EXT 4664 2. GL_FRAMEBUFFER_UNSUPPORTED_EXT 4665 3. GL_FRAMEBUFFER_INCOMPLETE_EXT 4666 where the three values mean the following: 4667 1. framebuffer is complete and supported 4668 2. framebuffer is not supported for implementation *dependent* reason 4669 3. framebuffer is incomplete for implementation *independent* reason 4670 4671 We considered the following two sets of enums: 4672 Set 1: 4673 GL_FRAMEBUFFER_COMPLETE_EXT 4674 GL_FRAMEBUFFER_NOT_COMPLETE_EXT 4675 GL_FRAMEBUFFER_NOT_SUPPORTED_EXT 4676 4677 Set 2: 4678 GL_FRAMEBUFFER_COMPLETE_EXT 4679 GL_FRAMEBUFFER_INCOMPLETE_EXT 4680 GL_FRAMEBUFFER_UNSUPPORTED_EXT 4681 4682 New resolution is Set 2. 4683 4684 NOTE: In order to fully resolve issue (55), we expanded this set 4685 of enums to identify all of the implementation-independent 4686 causes for a failure of the framebuffer completeness test. 4687 4688 Originally, we had decided to have a query where the 4689 query returns one of three possible values 4690 4691 One possible set of names that could be returned included: 4692 FRAMEBUFFER_COMPLETE, and 4693 FRAMEBUFFER_HW_DEPENDENT, and 4694 FRAMEBUFFER_HW_INDEPENDENT 4695 4696 How much information we return from CheckFramebufferStatus 4697 is a function of how we expect the return value to be used. 4698 A framebuffer object that is not complete for implementation 4699 *indepednent* reasons is really an indication of a 4700 programming error (like mismatched sizes) and should only 4701 occur during development phase of an application. The 4702 correct response to this failure is to modify the 4703 application to fix the bug. After application development, 4704 a framebuffer object that is not complete for implementation 4705 *dependent* reasons is possible. However, it's not yet 4706 clear whether we can easily characterize these reasons for 4707 failure in a programmatic fashion that would really offer 4708 the application enough information to do something different 4709 at runtime. Perhaps a human readable info log, intended 4710 just as an application debugging aid, would be more 4711 appropriate. 4712 4713 We also considered whether we needed two separate queries: 4714 One that queried whether the framebuffer was complete 4715 according to the spec, and one that queried whether the 4716 framebuffer was supported. This was a little problematic as 4717 it might not be possible to answer the 4718 "IsFramebufferSupported" query until the framebuffer was 4719 complete. A possible solution would have been to return 4720 UNKNOWN from the "IsFramebufferSupported" query until the 4721 "IsFramebufferComplete" query returned TRUE. 4722 4723 In any event, we decided a single query was a simpler 4724 solution. 4725 4726 In addition, the proposed "format group / format 4727 restriction" API (see issue 12) should make the 4728 implementation-dependent framebuffer incomplete case much 4729 less likely (and perhaps impossible) to occur. 4730 4731 Note that if a framebuffer's state violates more than one of 4732 the framebuffer completeness rules described in section 4733 4.4.4.2, then it is undefined which of the enumerated value 4734 corresponding to one of the violated rules will be returned 4735 by CheckFramebufferStatusEXT. Since the initial state of a 4736 framebuffer violates multiple rules from section 4.4.4.2, 4737 it is therefore undefined exactly which value is returned if 4738 CheckFramebufferStatusEXT is called while bound to a newly 4739 created framebuffer object. 4740 4741 (49) When this extension is used in conjunction with MRT (multiple 4742 render targets), it would naively be possible to create a 4743 framebuffer that had different color bit depths/formats for 4744 various color attachment points. Should this be allowed? 4745 4746 RESOLUTION: resolved, no, not in this extension. 4747 A soon to follow extension may add this feature. 4748 4749 This feature could be supported by simply not requiring that 4750 all of the FRAMEBUFFER_COLOR_ATTACHMENTn images share the 4751 same internal format. We decided against doing so, however. 4752 4753 ARB_draw_buffers and OpenGL-2.0 do not provide any mechanism 4754 to support rendering to multiple color buffers of different 4755 formats. Consequently, we chose not to extend OpenGL in 4756 this manner as part of the EXT_framebuffer_object extension. 4757 4758 Presumably, a future layered extension could easily add this 4759 feature. There are some open questions about exactly how 4760 this might work. For instance, what should a query of 4761 RED_BITS return if the attached color-renderable images have 4762 different formats? In any event, we leave the details of 4763 rendering to differently formatted MRT for a future 4764 extension to define. 4765 4766 (50) This extension introduces the concept of attaching one GL 4767 object (texture, renderbuffer) to another GL object 4768 (framebuffer). In many ways this situation is analogous to a 4769 previously poorly specified situation where a GL object could 4770 be attached to multiple contexts and the issues this raises 4771 with deletion and state propogation are similar. Several 4772 issues resolutions have been predicated on the assumption that 4773 as we specify this container/member relationship, the 4774 generation of GL errors should never be triggered in one 4775 context based on the asychronous actions of another context. 4776 Is this a valid premise? 4777 4778 In other words, should we be using the prevention of 4779 asynchronously generated GL errors as a design constraint? 4780 4781 RESOLUTION: resolved, no. 4782 4783 We didn't officially decide on this as a design constraint. 4784 However, we essentially decided it by proxy. We decided in 4785 issue (26) and (66) that an incomplete framebuffer can cause 4786 GL errors on rendering or reading the framebuffer. 4787 Consequently, this means a framebuffer shared by two 4788 contexts can be made incomplete by either context, and 4789 therefore each context can effectively cause the other 4790 context to start generating errors asynchronously. 4791 4792 We would expect that the state of framebuffer completness, 4793 like all the state of all shared objects, is not 4794 "guaranteed" to show up in another context until that 4795 context makes an "atomic" request to the server (like a 4796 BindFramebuffer for instance). Until that point, it is 4797 undefined whether the state change will show up in the other 4798 context, just like any state change made on a shared texture 4799 object. 4800 4801 (51) What api should we use to query the attachments of 4802 the currently bound framebuffer? 4803 4804 RESOLUTION: resolved, (b) 4805 4806 This is an issue because the relevant state 4807 for a specific attachment point is a function 4808 of the type of object attached to that that attachment point. 4809 The attachment point state needs to select a 4810 an image from an object which may have 4811 a collection of images, for instance 4812 the faces of a cube map texture. 4813 4814 This introduces a kind of "polymorphism" into the 4815 framebuffer attachment point that is problematic 4816 for queries. 4817 4818 We have a few options: 4819 4820 a) Some kind of single atomic query that 4821 returns a variable number of values in an array: 4822 4823 GetFramebufferParameteriv(enum target, 4824 enum pname, 4825 int* params); 4826 where 4827 <target> = a framebuffer target 4828 <pname> = {attachment_point} 4829 4830 Upon success "params" will contain an array of 4831 values where 4832 4833 params[0] = {NONE | TEXTURE | RENDERBUFFER} 4834 4835 if params[0] == TEXTURE then 4836 params[1] = texture object name 4837 params[2] = level 4838 params[3] = face 4839 params[4] = image 4840 else if params[0] = RENDERBUFFER then 4841 params[1] = renderbuffer name 4842 4843 Elements of the params array not explicitly defined 4844 above will have undefined values. 4845 4846 One problem with (a) is that we would potentially also 4847 need a query to identify how many state variables will 4848 come back in this query. Consider the case where in the 4849 future we add a new attachable object type that needs 4850 more selections tate or even add new selection state to 4851 existing object types. Applications coded to expect a 4852 maximum of n values returned today may break in the 4853 future unless they have a way to dynamically learn how 4854 many attachment state params will come back from the 4855 query. 4856 4857 4858 b) individual queries for all the possible attachment 4859 state values. 4860 4861 We create a new routine to add a new <attachment> 4862 argument, otherwise we'd have an explosion of 4863 permutations of attachment points and possible attachment 4864 selection state values 4865 4866 This could look like 4867 4868 void GetFramebufferAttachmentParameteriv(enum target, 4869 enum attachment, 4870 enum pname, 4871 int *param); 4872 4873 where 4874 <target> = a framebuffer target 4875 <attachment> = {attachment_point} 4876 <pname> = one of 4877 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT 4878 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT 4879 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT 4880 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT 4881 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT 4882 4883 Upon success, param will be filled out as follows: 4884 4885 if pname is FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT, 4886 then param will contain one of: 4887 { NONE | TEXTURE | RENDERBUFFER }, 4888 4889 else if pname is 4890 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, and 4891 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT = TEXTURE, 4892 then param will contain: 4893 { name of attached texture } 4894 4895 else if pname is 4896 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT, and 4897 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT = 4898 RENDERBUFFER, then param will contain: 4899 { renderbuffer object name } 4900 4901 else if pname is 4902 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT, and 4903 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT = TEXTURE, 4904 then param will contain: 4905 { selected mipmap level of attached texture } 4906 4907 else if pname is 4908 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_EXT, 4909 and FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT = 4910 TEXTURE, then param will contain: 4911 { selected face of attached cube map texture } 4912 { 0 if texture target is not TEXTURE_CUBE_MAP } 4913 4914 else if pname is 4915 FRAMEBUFFER_ATTACHMENT_TEXTURE_ZOFFSET_EXT, and 4916 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT = TEXTURE, 4917 then param will contain: 4918 { selected z-slice/image of attached 3D texture } 4919 { 0 if texture is not 3-dimensional } 4920 4921 otherwise, param will contain the value 0. 4922 4923 4924 One problem with option (b) is that it is a little 4925 heavy-handed as every piece of state needs its own query 4926 and enum 4927 4928 Given the above choices, and the problems of extending option 4929 (a) in the future, (b) is probably the better of the two 4930 choices. It really only adds a few enums, and though it does 4931 require an independent function call to obtain each piece of 4932 state, this is well-precedented behavior throughout GL. 4933 4934 (52) Should manual mimpap generation via GenerateMipmap apply to 4935 textures regardless of whether they are attached to framebuffer 4936 objects? Should automatic mimpap generation apply to all 4937 textures regardless of whether they are attached to framebuffer 4938 objects? 4939 4940 RESOLUTION: resolved, (a) - both apply to both. 4941 4942 This is an issue because the introduction of GenerateMipmap is 4943 intended both to address long standing complaints about the 4944 existing "automatic" mipmap generation API and to provide a 4945 clear trigger for render to texture API's to know when to do 4946 the mipmap generation. 4947 4948 These API's could be considered completely orthogonally. It's 4949 clear how they could interoperate. The question is should they 4950 interoperate, or should one supercede the other? 4951 4952 There are a couple of ways to address this issue: 4953 4954 a) "automatic" mipmap generation applies always and is 4955 triggered by any gl{Copy}Tex{Sub}Image call if 4956 GENERATE_MIPMAP is set to TRUE. "Manual" mipmap 4957 generation applies always and is triggered by a call to 4958 GenerateMipmap 4959 4960 b) "automatic" mipmap generation applies only 4961 to textures which are not attached to framebuffer 4962 objects, calls to GenerateMipmap on "unattached" textures 4963 are ignored. 4964 4965 "manual" mipmap generation applies only to textures which 4966 are attached to framebuffer objects, the value of 4967 GENERATE_MIPMAP for "attached" textures is ignored 4968 4969 c) Like option (b), but allow GenerateMipmap to 4970 apply to all textures and only let automatic mipmap 4971 generation apply to "non-attached" textures. 4972 4973 d) Create an enable or other piece of state 4974 to toggle between allowing automatic and allowing manual 4975 generation. 4976 4977 We disregarded (d) because it's not clear why an application 4978 that had the freedom to set this new enable bit wouldn't 4979 simply just turn off the legacy automatic mimpap generation 4980 to start with. 4981 4982 Of the remaining choices, (a) is the most "orthogonal". The 4983 intent of adding GenerateMipmap is to provide a cleaner and 4984 saner interface to mipmap generation that we would encourage 4985 developers to use over the automatic method. Given that, it 4986 seems like restricting the "manual" generation to certain 4987 cases doesn't serve that goal, so we wish to allow its use 4988 on any textures, attached or not. 4989 4990 (53) When supporting ARB_draw_buffers, do we need the level of 4991 indirection between fragment color outputs and attached 4992 mages provided in that API? 4993 4994 RESOLUTION: yes 4995 4996 ARB_draw_buffers allows the user to set up an "indirection 4997 table" between the fragment color outputs ("result.color[n]" 4998 in ARB_fragment_program, and "gl_FragData[n]" in GLSL) and 4999 the attached draw buffers (FRONT, BACK, LEFT, RIGHT, etc). 5000 5001 Since EXT_framebuffer_object is creating new non-visible 5002 framebuffer objects for which the legacy attachment points 5003 may not be appropriate, we could consider naming the 5004 attachment points by numerical index (COLOR0 ... COLORn) in 5005 which case we could consider dropping this level of 5006 indirection and allowing the fragment shader to output 5007 directly into the numerically specified COLOR0 attachment 5008 point with no indirection. 5009 5010 However, this indirection is deemed to be useful becaues it 5011 allows the application to redirect the fragment color 5012 outputs without changing either the fragment shader itself 5013 or the current framebuffer attachments, both of which are 5014 believed to be heavier-weight state change operations than 5015 simply changing the indirection table via glDrawBuffers.. 5016 5017 Therefore, we elect to retain this level of indirection. 5018 This leaves open the question of what to call the attachment 5019 points. See issue (54). 5020 5021 (54) What should we name the logical buffer attachment points, 5022 bearing in mind the relationship to ARB_draw_buffers? 5023 5024 RESOLUTION: resolved, option (E), which is a modified 5025 version of (C). Specifically, we use the names 5026 COLOR_ATTACHMENT0_EXT through COLOR_ATTACHMENTn_EXT, 5027 DEPTH_ATTACHMENT_EXT, and STENCIL_ATTACHMENT_EXT (and any 5028 future attachment points also get the ATTACHMENT suffix). 5029 5030 The reason this is an issue is that prior to 5031 EXT_framebuffer_object, the names of the various color 5032 logical buffer "attachment points" were heavily influenced 5033 by their intended usage in a graphical window-system. 5034 Logical buffers for BACK and FRONT_LEFT make sense in the 5035 context of double buffering and stereo presentation, but 5036 their use in off-screen rendering situations is 5037 anachronistic at best and perhaps even confusing. 5038 5039 There are several options: 5040 5041 Option (A): stick with the "legacy" names 5042 5043 This would have us use all of the legacy names which are 5044 used to identify a single buffer: FRONT_LEFT, 5045 FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, and AUX0..AUXn. 5046 5047 This option would require no change to DrawBuffersARB(). 5048 5049 Option (B): AUXn names 5050 5051 If we wish to avoid using the legacy names, one option 5052 is to re-use another numerically named set of color 5053 buffers, the AUX buffers, and only allow framebuffer 5054 objects to support AUX0..AUXn attachment points. 5055 5056 This has the advantage of being easy to specify, and 5057 numerically delimit, but is a little strange as 5058 framebuffer objects could conceivably support the same 5059 number of AUX buffers as the implementation supports 5060 multiple render targets. This would have the awkward 5061 consequence of allowing framebuffer objects to support 5062 more AUX buffers than the default framebuffer could 5063 support via the pixel format selection mechanism. 5064 5065 This option would require no specific change to 5066 DrawBuffers but might require non-default framebuffers 5067 to support more AUX buffers than the default framebuffer 5068 controlled by the window-system pixel format. 5069 5070 Option (C): COLORn names 5071 5072 Another option is to rename the color buffer attachment 5073 points for application-created framebuffer objects to 5074 COLOR0..COLORn. This has the advantage of avoiding the 5075 legacy window-centric names, and avoiding the confusion 5076 with AUX buffers. When considered in conjunction with 5077 the decision in issue (53) to support a level of 5078 indirection when using ARB_draw_buffers, however, the 5079 user of the names COLOR0..COLORn may be confusing. For 5080 instance, if an ARB fragment program contains color 5081 output to "result.color[3]", it will not necessarily 5082 output to COLOR3. It will actually write to the buffer 5083 specified by DrawBuffersARB for DRAW_BUFFER3 which may 5084 or may not be COLOR3. 5085 5086 This option would require an update to DrawBuffers to 5087 accept the new COLOR0..COLORn values as valid draw 5088 buffers and would require a change to DrawBuffers to 5089 disallow the "legacy" names. Or at the very least we 5090 would need some language to describe what happens if the 5091 DrawBuffers are using the legacy names when the 5092 currently bound framebuffer is not the default window 5093 system framebuffer. 5094 5095 Option (D): DATAn names 5096 5097 Yet another option is to call these attachment points 5098 DATA0..DATAn. This is the same as option (C) but uses 5099 the word DATA instead of COLOR. This has the advantage 5100 of avoiding the above problems with COLOR0..COLORN, but 5101 introduces a similar conflict with GLSL which uses the 5102 "gl_FragData[n]" name for its output. Additionally, 5103 since we only support multiple render targets for color 5104 logical buffers, it may be that using the word DATA is 5105 considered too abstract/general. 5106 5107 Option (E): add ATTACHMENT to *ALL* names 5108 5109 In order to avoid the confusion of option (C) and (D), 5110 we can choose to be more verbose. We can add the word 5111 _ATTACHMENT to distinguish these enums from the color 5112 outputs of a fragment program or fragment shader. For 5113 symmetry we also add _ATTACHMENT to the DEPTH and 5114 STENCIL (and any other to-be-added) attachment points. 5115 5116 Similar to (C) and (D), this option requires an update 5117 to DrawBuffers to at least accept the new enum values. 5118 We could choose to make it illegal to specify the legacy 5119 values for non-default framebuffers as well. This is 5120 essentially covered by issue (55). 5121 5122 Here is an pseudo-code example using option (E): 5123 5124 // Assume presence of color renderbuffers 5125 // with names 1000, 2000, 3000, 4000 5126 5127 GLuint db[4] = 5128 { COLOR_ATTACHMENT4, COLOR_ATTACHMENT7, 5129 COLOR_ATTACHMENT1, COLOR_ATTACHMENT2 }; 5130 5131 glDrawBuffers(4, db); 5132 5133 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, COLOR_ATTACHMENT4, 5134 GL_RENDERBUFFER_EXT, 1000); 5135 5136 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, COLOR_ATTACHMENT7, 5137 GL_RENDERBUFFER_EXT, 2000); 5138 5139 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, COLOR_ATTACHMENT1, 5140 GL_RENDERBUFFER_EXT, 3000); 5141 5142 glFramebufferRenderbufferEXT(GL_FRAMEBUFFER_EXT, COLOR_ATTACHMENT2, 5143 GL_RENDERBUFFER_EXT, 4000); 5144 5145 Then in ARB_fragment_program 5146 result.color[0] writes to COLOR_ATTACHMENT4 (i.e., renderbuffer 1000) 5147 result.color[1] writes to COLOR_ATTACHMENT7 (i.e., renderbuffer 2000) 5148 result.color[2] writes to COLOR_ATTACHMENT1 (i.e., renderbuffer 3000) 5149 result.color[3] writes to COLOR_ATTACHMENT2 (i.e., renderbuffer 4000) 5150 5151 And in ARB_fragment_shader 5152 gl_FragData[0] writes to COLOR_ATTACHMENT4 (i.e., renderbuffer 1000) 5153 gl_FragData[1] writes to COLOR_ATTACHMENT7 (i.e., renderbuffer 2000) 5154 gl_FragData[2] writes to COLOR_ATTACHMENT1 (i.e., renderbuffer 3000) 5155 gl_FragData[3] writes to COLOR_ATTACHMENT2 (i.e., renderbuffer 4000) 5156 5157 5158 See also issue (57) for discussion on querying the number of 5159 available color buffers. 5160 5161 (55) What should happen if the current DRAW_BUFFER(s) point to a 5162 non-existent logical buffer? Likewise for READ_BUFFER. 5163 5164 RESOLUTION: resolved 5165 5166 partial resolution #1: DrawBuffer(s)/ReadBuffer throws 5167 an error if the buffer does not "exist" for all 5168 framebuffers (default and non-default). 5169 5170 Should it be an error to call drawBuffer on a 5171 non-default framebuffer if named buffer does not 5172 exist? 5173 5174 Resolved: yes 5175 5176 partial resolution #2: The test for having a valid draw 5177 and read buffer should be part of framebuffer 5178 completeness test. 5179 5180 Should be part of completeness test and should all 5 5181 indpenent reasons add 5 enums? 5182 5183 Resolved: yes 5184 5185 partial resolution #3: we should create an enum for 5186 each implementation independent reason for failing 5187 the framebuffer completeness test of section 4.4.4.1 5188 5189 Current names (could change...) 5190 FRAMEBUFFER_COMPLETE_EXT 5191 FRAMEBUFFER_INCOMPLETE_ATTACHMENTS_EXT 5192 FRAMEBUFFER_INCOMPLETE_IMAGES_EXT 5193 FRAMEBUFFER_INCOMPLETE_DIMENSIONS_EXT 5194 FRAMEBUFFER_INCOMPLETE_FORMATS_EXT 5195 FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER_EXT 5196 FRAMEBUFFER_INCOMPLETE_READ_BUFFER_EXT 5197 FRAMEBUFFER_UNSUPPORTED_EXT 5198 5199 NOTE: as per resolution of issue (78) 5200 FRAMEBUFFER_INCOMPLETE_ATTACHMENTS_EXT 5201 became 5202 FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT 5203 and 5204 FRAMEBUFFER_INCOMPLETE_IMAGES_EXT 5205 was dropped. 5206 5207 This issue is intertwined with issue (56), which discusses 5208 whether the DRAW_BUFFER and READ_BUFFER are context or 5209 framebuffer object state. 5210 5211 First, some background: If DRAW_BUFFER state is part of the 5212 context state vector rather than the framebuffer object 5213 state vector (see issue 56), then there are three ways to 5214 cause DRAW_BUFFER to reference a color buffer attachment 5215 point that "does not exist" in the currently bound 5216 framebuffer. If DRAW_BUFFER is part of the framebuffer 5217 object state vector, then (A) still applies but (B) and (C) 5218 do not. 5219 5220 A) The first case is by detaching, from the currently 5221 bound framebuffer object, the image that is attached to 5222 attachment point named by the value of DRAW_BUFFER. If 5223 an image is attached to COLOR_ATTACHMENTn_EXT in the 5224 current framebuffer object and DRAW_BUFFER is set to 5225 COLOR_ATTACHMENTn_EXT, and then the application 5226 detaches the image from COLOR_ATTACHMENTn_EXT, then 5227 DRAW_BUFFER will end up specifying a buffer that "does 5228 not exist" in the currently bound framebuffer object. 5229 5230 There is no analogue to this case in OpenGL prior to 5231 EXT_framebuffer_object. Before this extension, the 5232 pixel format or fbconfig of a window or pbuffer is 5233 immutable once one of these drawables has been created. 5234 By design, framebuffer objects (which essentially 5235 represent a new type of drawable) have mutable "pixel 5236 formats". 5237 5238 B) The second case is by binding between two user-created 5239 framebuffer objects, where the two framebuffer objects 5240 do not have images attached to the same set of color 5241 attachment points. If an image is attached to 5242 COLOR_ATTACHMENTn_EXT in the current framebuffer object 5243 and DRAW_BUFFER is set to COLOR_ATTACHMENTn_EXT, and 5244 then the user binds to a new framebuffer for which 5245 there is no image attached to COLOR_ATTACHMENTn_EXT, 5246 then DRAW_BUFFER will end up specifying a buffer that 5247 "does not exist" in the newly bound framebuffer object. 5248 5249 This is morally equivalent to calling MakeCurrent to 5250 bind a context to a different drawable (window or 5251 pbuffer) which does not have bitplanes for the color 5252 buffer named by the context's value of DRAW_BUFFER. 5253 For example, MakeCurrent to a double-buffered window, 5254 set DRAW_BUFFER to BACK, then MakeCurrent to a 5255 single-buffered window. 5256 5257 C) The third case is by binding between the default 5258 framebuffer and a user-created framebuffer object. The 5259 attachment points of a user-created framebuffer object 5260 are named COLOR_ATTACHMENTn_EXT, DEPTH_ATTACHMENT_EXT, 5261 STENCIL_ATTACHMENT_EXT, etc. These are also the legal 5262 values of DRAW_BUFFER when a user-created framebuffer 5263 object is bound. The default framebuffer, on the other 5264 hand, does not use the _ATTACHMENT names but instead 5265 uses names such as FRONT_LEFT, BACK_RIGHT, and AUXn as 5266 legal DRAW_BUFFER values. Because the two sets of 5267 names do not overlap, no value of DRAW_BUFFER is valid 5268 for both the default framebuffer and a user-created 5269 framebuffer object. 5270 5271 This is somewhat equivalent to case (B), except that in 5272 case (C) there is a guarantee that DRAW_BUFFER will 5273 become invalid, whereas in case (B) it is only 5274 _possible_ that DRAW_BUFFER will become invalid. 5275 5276 The very problem of invalid DRAW and READ buffers was 5277 already a feature of OpenGL (and the window-system APIs) 5278 before the introduction of the EXT_framebuffer_object 5279 extension. The GLX specification specifically addresses 5280 what happens when MakeCurrent is used to bind a context to a 5281 different drawable (window or pbuffer) which does not 5282 possess one of the color buffers referenced by the context's 5283 current values of DRAW_BUFFER and READ_BUFFER. GLX 5284 addresses this by saying that no GL error is generated, but 5285 invalid DRAW_BUFFER behaves as if DRAW_BUFFER were NONE, and 5286 reads produce undefined results when READ_BUFFER is invalid. 5287 5288 Now, back to the question of how EXT_framebuffer_object 5289 should handle the situation when a framebuffer object is 5290 bound and DRAW_BUFFER or READ_BUFFER is not valid while 5291 bound to a user-created framebuffer object. 5292 5293 Obviously one option is to resolve the issue the same way is 5294 handled by MakeCurrent in the GLX spec. Invalid DRAW_BUFFER 5295 acts as if DRAW_BUFFER were NONE, and invalid READ_BUFFER 5296 causes read operations to generate undefined results. 5297 5298 A second option is to modify the framebuffer completeness 5299 test to fail if the current DRAW_BUFFER or READ_BUFFER 5300 reference an attachment point to which no image is attached. 5301 This solution would also result in no rendering being 5302 performed, but would also generate a GL error when rendering 5303 is attempted while in this state, as determined by issue 5304 (64). When rendering to a framebuffer object, invalid 5305 DRAW_BUFFER would cause generation of GL errors; but when 5306 rendering to a window, invalid DRAW_BUFFER would not cause 5307 generation of GL errors. 5308 5309 Consider also that, because of the resolution of issue (66), 5310 depending on how issue (56) is decided, failing the 5311 framebuffer completeness test due to a "non-existent" 5312 DRAW_BUFFER or READ_BUFFER may not be a viable option, 5313 because the framebuffer completeness test is not allowed to 5314 examine context state. 5315 5316 Additionally, there are two sub-issues that fall out of this 5317 issue: 5318 5319 sub-issue 1: Error at DrawBuffer call time or not? 5320 sub-issue 2: DRAW_BUFFER in or out of completeness test? 5321 5322 [sub-issue 1]: First, what should be the behavior of 5323 DrawBuffer(s) and ReadBuffer if the specified buffer does 5324 not exist at the time DrawBuffer(s) or ReadBuffer is called? 5325 5326 For default framebuffer (window-system drawables), an error 5327 is currently thrown. We can not (or do not wish to) change 5328 this legacy behavior of window-system supplied drawables. 5329 Consequently, we must resolve several questions here: 5330 5331 For instance: 5332 5333 - Should we do the same thing (error at DrawBuffer time) 5334 for user framebuffer objects? 5335 5336 - Is this decision influenced by the fact that 5337 user-created framebuffer objects can change their 5338 attachments one buffer at a time while window-system 5339 supplied drawables can not (i.e., must change all 5340 attachments atomically)? 5341 5342 - Also, on other places in this API, such as assembling 5343 a framebuffer from framebuffer-attachable images, we 5344 have allowed the system to move through "invalid" 5345 states without generating an error as long as the 5346 system was back in a "valid" state by rendering time 5347 (or "validation" time). Should we adhere to that 5348 principle here, or is this case different somehow? 5349 5350 - Do we wish to retain the legacy window-system 5351 DrawBuffer(s) behavior for application-created 5352 framebuffer objects for the sake of maintaining 5353 consistency? i.e., Does the benefit of treating 5354 default and non-default framebuffers consistently 5355 outweigh the earlier decision to delay validation of 5356 "invalid" states? 5357 5358 - Both resolutions are examples of "state combination" 5359 errors where an error may or may not be generated 5360 depending on the order state-changing function calls 5361 are made. For instance, in the legacy behavior 5362 DrawBuffers does or does not throw an error on user 5363 framebuffer objects depending on when you call 5364 DrawBuffer relative to when you made your image 5365 attachments. On the other hand, if we decided to not 5366 throw an error at DrawBuffer time for user framebuffer 5367 objects, then DrawBuffer does or does not throw an 5368 error depending on whether one is bound to a default 5369 or non-default framebuffer. Is one of these "state 5370 combination" errors better or worse than the other? 5371 5372 [sub-issue 2]: Should having a DRAW_BUFFER that names a 5373 non-existent buffer cause the framebuffer completeness test 5374 to fail? 5375 5376 Since image attachments can be changed after 5377 DrawBuffer(s) is called, even if we throw an error at 5378 Drawbuffer(s) time, we still must decide how to handle 5379 having an invalid DRAW_BUFFER at render (or "validation") 5380 time. Our options include failing the completeness test, 5381 (thus disabling rendering and generating an error at render 5382 time) or just behaving as if DRAW_BUFFER is NONE (thus 5383 disabling rendering but generating no error at render time). 5384 5385 If the answer is "fail completeness test", then since 5386 currently framebuffer completeness can only be affected by 5387 framebuffer state, then one of two things has to happen: 5388 Either the drawbuffer state must be framebuffer object 5389 state, or we have to revisit our decision that framebuffer 5390 completeness is solely a property of the framebuffer state 5391 and can not be affected by "per context" state. 5392 5393 If the answer is "do not fail completeness test", then the 5394 practical consequence of this decision is that having an 5395 invalid DRAW_BUFFER behaves as if DRAW_BUFFER is NONE, and 5396 no error is generated at render time. Also, in this case, 5397 DRAW-BUFFER state can be either per-context or 5398 per-framebuffer object state without violating any 5399 previously decided issues. 5400 5401 (56) Should the value of DRAW_BUFFER, the corresponding draw buffers 5402 indirection table for ARB_draw_buffers, and the value of 5403 READ_BUFFER, be part of the context state vector or part of the 5404 the framebuffer object state vector? 5405 5406 RESOLUTION: resolved, per-framebuffer object 5407 5408 This issue is intertwined with issue (55), which discusses 5409 what happens when the DRAW_BUFFER or READ_BUFFER references 5410 a color buffer that "does not exist" in the current 5411 framebuffer. 5412 5413 Please first read the "First, some background" section of 5414 issue (55), which could be, but is not, replicated here. 5415 Note that depending on how issue (56) is decided, cases (B) 5416 and (C) from issue (55) might become moot. Specifically, if 5417 the DRAW_BUFFER and READ_BUFFER state are added to the 5418 framebuffer object state vector, then neither case (B) nor 5419 case (C) remains relevant. Only case (A) would continue to 5420 be an issue. 5421 5422 The discussion over this issue centered around the following 5423 areas: 5424 5425 i) There must be a unique per-context value of DRAW_BUFFER 5426 for the default window-system-provided framebuffer. 5427 5428 In GL, before EXT_framebuffer_object, the DRAW_BUFFER 5429 was considered context state because: 5430 5431 1) When two contexts are rendering to the same drawable, 5432 each context can use a different value of 5433 DRAW_BUFFER. 5434 5435 2) When MakeCurrent alternately binds a single context 5436 to each of two different drawables, after MakeCurrent 5437 DRAW_BUFFER retains the value it had immediately 5438 before calling MakeCurrent. This is true even if the 5439 last time the context was bound to a given drawable, 5440 DRAW_BUFFER had a different value than it does when 5441 that drawable is next bound to the context. 5442 5443 Therefore, a per-context value of DRAW_BUFFER must 5444 exist, and must be in effect when the 5445 FRAMEBUFFER_BINDING_EXT is zero. 5446 5447 Two ways of satisfying this requirement that we have 5448 considered include: 5449 5450 A) DRAW_BUFFER is part of the context state vector, but 5451 is not part of the framebuffer object state vector. 5452 5453 B) Every framebuffer, including the per-context default 5454 window-system-provided framebuffer, has its own value 5455 for DRAW_BUFFER. 5456 5457 ii) MakeCurrent vs. BindFramebuffer 5458 5459 As described above, the context state vector must 5460 contain a value for DRAW_BUFFER that applies to the 5461 default window-system-provided framebuffer, which is 5462 used after a call to BindFramebuffer(0). When 5463 MakeCurrent is used to bind the context to a different 5464 drawable (window or pbuffer), the context's value of 5465 DRAW_BUFFER remains unchanged. In other words, the 5466 choice of drawable does not affect the value of 5467 DRAW_BUFFER. 5468 5469 An application-created framebuffer object is another 5470 type of drawable. When the framebuffer binding is 5471 changed via BindFramebuffer, issue (56) speaks to the 5472 way in which DRAW_BUFFER is or is not updated. If 5473 DRAW_BUFFER is part of the context state vector, then 5474 DRAW_BUFFER remains unchanged after calling 5475 BindFramebuffer, just like it remains unchanged after 5476 calling MakeCurrent. On the other hand, if DRAW_BUFFER 5477 is part of the framebuffer object state vector, then 5478 after calling BindFramebuffer DRAW_BUFFER may change 5479 along with the rest of the per-framebuffer state (i.e., 5480 the image attachments). 5481 5482 By defining DRAW_BUFFER as context state, the behavior 5483 of BindFramebuffer and MakeCurrent are similar, with 5484 respect to their effect on the value of DRAW_BUFFER. 5485 5486 On the other hand, by defining DRAW_BUFFER as 5487 framebuffer object state, then BindFramebuffer and 5488 MakeCurrent differ in their impact on the value of 5489 DRAW_BUFFER. 5490 5491 iii) Multiple contexts and shared framebuffer objects 5492 5493 If DRAW_BUFFER is part of the framebuffer object state 5494 vector, then a single value of DRAW_BUFFER, like all of 5495 the framebuffer object state, will be shared by any 5496 context bound to a given framebuffer object. This can 5497 be considered either a feature or a restriction 5498 depending on whether or not it is desirable for multiple 5499 contexts to be able to share a single the value of 5500 DRAW_BUFFER. 5501 5502 Note that WGL_ARB_pbuffer plus WGL_ARB_render_texture 5503 API has limitations due to the fact that the texture 5504 image selection state is stored in the pbuffer drawable. 5505 For example, that API does not support six different 5506 contexts (in six different threads) simultaneously 5507 rendering to the six faces of a cube map pbuffer. It 5508 offers no way to share the images without also sharing 5509 the pbuffer, and the pbuffer contains a single set of 5510 texture image selection state. 5511 5512 EXT_framebuffer_object differs from ARB_render_texture, 5513 however, however, in that EXT_framebuffer_object allows 5514 the same images of a texture to be attached to multiple 5515 framebuffer objects. Consequently, the above cubemap 5516 example can be implemented in EXT_framebuffer_object in 5517 one or two ways, depending on the resolution of issue 5518 (56): 5519 5520 1) Create six framebuffer objects. Attach a different 5521 face of a cubemap texture to each of the six 5522 framebuffer objects. Each of the six contexts binds 5523 to a unique framebuffer object. Technically, this 5524 option is available whether DRAW_BUFFER is context or 5525 framebuffer state. However, if it is context state, 5526 then there is no reason to create six framebuffer 5527 objects since the value of the DRAW_BUFFER will 5528 already be unique per context. 5529 5530 2) On the other hand, if DRAW_BUFFER is defined as 5531 context state, then a second option is available. 5532 Using a single framebuffer object, attach each face 5533 of the cube map texture to a different attachment 5534 point in the framebuffer object. Each of the six 5535 contexts binds to the same framebuffer object, but 5536 each context uses a different value of DRAW_BUFFER. 5537 5538 iv) Frequency of DrawBuffer calls: 5539 5540 Whether DRAW_BUFFER is part of context or framebuffer 5541 state will have an effect on how often one must call 5542 DrawBuffer after modifying framebuffer state. 5543 5544 If DRAW_BUFFER is part of the context state vector, then 5545 DRAW_BUFFER is guaranteed to become invalid after 5546 calling BindFramebuffer to switch between the default 5547 framebuffer and a user-created framebuffer object [i.e., 5548 this is case (C) in issue (55)]. DRAW_BUFFER may become 5549 invalid after switching between two user-created 5550 framebuffer objects if the framebuffer objects do not 5551 have images attached to the same set of color attachment 5552 points. When DRAW_BUFFER is invalid, it is necessary to 5553 call DrawBuffer to set DRAW_BUFFER to a valid value or 5554 else rendering is disabled. 5555 5556 If, on the other hand, DRAW_BUFFER is part of the 5557 framebuffer object state vector, then it should never be 5558 necessary to call DrawBuffer after calling 5559 BindFramebuffer. DRAW_BUFFER would only become invalid 5560 if an image was detached from the framebuffer, or if 5561 MakeCurrent bound the default framebuffer to a drawable 5562 with a different set of color buffers. (The latter was 5563 possible prior to this extension.) 5564 5565 Note that there are several state-modifying routines 5566 that may also need to get called after a framebuffer 5567 state change, like Viewport, Scissor, etc. We are not 5568 proposing that these other routines be part of 5569 framebuffer state. One could think of DrawBuffer as 5570 being similar to these other routines which you may also 5571 need to call when you bind between framebuffer objects. 5572 On the other hand, some have questioned whether an 5573 invalid DRAW_BUFFER is really in the same class of 5574 problems as an out-of-bounds viewport or scissor 5575 because: 1) an invalid viewport or scissor never 5576 generates a GL error, and 2) prior to the 5577 EXT_framebuffer_object extension an invalid DRAW_BUFFER 5578 would generate INVALID_ENUM inside DrawBuffer. 5579 5580 v) Effect on framebuffer completeness test: 5581 5582 By resolution of issue (66), if the draw buffer is 5583 context state, then the fact that the draw buffer names 5584 a non-existent buffer can not affect the result of the 5585 framebuffer completeness test. Note that this still 5586 could be considered a "do not render" case, but would 5587 separate from the framebuffer completeness test. 5588 5589 If the draw buffer(s) and read buffer are part of the 5590 framebuffer object state then having a draw or read 5591 buffer name a non-existent buffer can (if we choose) be 5592 part of the framebuffer (in)completeness test. 5593 5594 Note, by resolution of issue (64), failing the 5595 framebuffer completeness test causes a GL error to be 5596 generated when draw or read operations are attempted. 5597 Prior to EXT_framebuffer_object, it was already possible 5598 to have an invalid value of DRAW_BUFFER if a call to 5599 MakeCurrent bound the context to a drawable that did not 5600 contain a color buffer corresponding to the context's 5601 value of DRAW_BUFFER. However, no GL error would be 5602 generated if DRAW_BUFFER obtained an invalid value 5603 through this method. 5604 5605 vi) Draw buffer(s) error behavior: 5606 5607 Prior to the EXT_framebuffer_object extension, it was an 5608 error to call DrawBuffer or ReadBuffer with a value that 5609 did not correspond to one of the logical color buffers 5610 of the currently bound drawable (window or pbuffer). 5611 Although it was not possible to set DRAW_BUFFER to an 5612 invalid value by calling DrawBuffer, it was actually 5613 possible for DRAW_BUFFER to have an invalid value after 5614 a call to MakeCurrent, as describe in issue (55). 5615 5616 It has not been decided yet whether 5617 EXT_framebuffer_object will relax the requirement that 5618 the argument to DrawBuffer references a color buffer 5619 that "exists" in the currently drawable. 5620 5621 In working group discussions, there was a perception 5622 that such an error during DrawBuffer can be generated 5623 only if DRAW_BUFFER is part of the framebuffer object 5624 state vector. Then when the default framebuffer (window 5625 or pbuffer) is current, the legal values of the argument 5626 to DrawBuffer would be determined by the pixel format or 5627 fbconfig. When a user-created framebuffer object is 5628 current, the legal values of DrawBuffer would either be 5629 any of the COLOR_ATTACHMENTn_EXT names or only the names 5630 of attachment points to which an image is presently 5631 attached. 5632 5633 However, given the precedent set by MakeCurrent and 5634 DRAW_BUFFER, it seems reasonable to retain the 5635 preexisting requirement that the argument to DrawBuffer 5636 names a buffer that "exists" in the current drawable. 5637 In other words, there already exists precedent that says 5638 it is OK for DrawBuffer to generate an error in all the 5639 cases described in the preceeding paragraph, even if 5640 DRAW_BUFFER is defined as part of the context state 5641 vector. 5642 5643 (57) Should we have a query to define the maximum number of 5644 attachable color buffers (to support ARB_draw_buffers)? 5645 5646 RESOLUTION: yes, MAX_COLOR_ATTACHMENTS. 5647 5648 Currently an application can query the GL for the maximum 5649 number of supported AUX buffers. An application can also 5650 query for MAX_DRAW_BUFFERS_ARB in the ARB_draw_buffers 5651 extension. Given that we have named the color logical 5652 buffer attachment points, COLOR_ATTACHMENT0_EXT through 5653 COLOR_ATTACHMENTn_EXT, it seems natural that we should have 5654 a query to find the maximum value "n". 5655 5656 One thought was that we might be able to use 5657 MAX_DRAW_BUFFERS_ARB to store this value, but that value 5658 really describes the maximum number of colors that can be 5659 simultaneously output which is not the same thing as the 5660 number of buffers which can be attached and then selected 5661 among using DrawBuffersARB(). 5662 5663 This question is related to issue (54), which covers the 5664 names of the user-created framebuffer object color 5665 attachment points. Using the names COLOR_ATTACHMENT0_EXT 5666 through COLOR_ATTACHMENTn_EXT rather than the legacy color 5667 buffer attachment names (FRONT_LEFT et. al.) for 5668 user-created framebuffer objects has an advantage that the 5669 number of color buffer attachment points could be queried 5670 independent of the number of AUX buffers and existence of 5671 front/back & left/right color buffers as specified in the 5672 pixelformat. The number of available offscreen attachment 5673 points really should be independent of the properties of the 5674 current drawable's pixelformat, especially since MakeCurrent 5675 can bind a context to a drawable with a different 5676 pixelformat and thus different set of color buffers. 5677 5678 One implication of this query is that the value of 5679 MAX_COLOR_ATTACHMENTS_EXT is possibly still dependent on the 5680 context/pixel format but independent of the currently bound 5681 framebuffer. In other words, MAX_COLOR_ATTACHMENTS_EXT can 5682 not change simply because the user called BindFramebuffer(). 5683 Or can it? See issue (62) 5684 5685 (58) What should we do about rendering to textures with borders? 5686 (besides attempt to fervently wish them out of existence, I mean) 5687 5688 RESOLUTION: resolved, borders are fully supported 5689 5690 Should we allow rendering to textures with borders at 5691 all? 5692 Resolved: yes 5693 5694 If we allow this, can you render to the border pixels? 5695 Resolved: yes 5696 5697 The reason this is an issue is that (a) everyone hates 5698 supporting borders, and (b) it's not clear what it means to 5699 render to a texture with borders. 5700 5701 To disallow rendering to a texture image with non-zero 5702 border size, we could add a test for non-zero border size to 5703 the definition framebuffer completeness. This might be 5704 preferrable to an error at FramebufferTexture, since the 5705 user could always redefine the texture to have borders after 5706 attachment, and so the framebuffer completeness test is 5707 necessary anyway. 5708 5709 However, since borders do exist today and we are not 5710 planning to rip them out of OpenGL everywhere else, we 5711 decided to support them. It seemed odd that you could still 5712 specify borders via TexImage but not render into the same 5713 texture so we leave them supported. Note that it's quite 5714 possible that implementations which don't support borders 5715 may continue to either not support them or fall to software 5716 rasterization. 5717 5718 If someday we decide to disallow borders in general, they 5719 will be disallowed from this extension as well. 5720 5721 One additional note: section 3.8.2, page 137, of the OpenGL 5722 1.5 specification, states that {Copy}TexSubImage uses 5723 negative offsets to refer to border texels. We choose not 5724 to do this because negative window-coordinates are 5725 undefined. (NOTE: Are negative window coordinates actually 5726 undefined? Or are they just not commonly used in practice?) 5727 5728 (59) Should we support named bit depths for stencil renderbuffers? 5729 5730 RESOLUTION: resolved, yes, choose 4 common formats. 5731 5732 We intend to support using renderbuffers to store stencil 5733 data. This means we need to consider what kind of "internal 5734 format" request we provide for stencil formatted 5735 renderbuffers. 5736 5737 We choose to allow a "named" format request for the internal 5738 format. This is essentially equivalent to the named 5739 internal format request of the TexImage calls. It is merely 5740 a request and the driver will attempt to satisfy it as best 5741 as possible but may approximate the requested format with 5742 another format. Additionally, this request is subject to 5743 the same invariance constraints as the texture internal 5744 format requests. 5745 5746 For the initial extension we choose the following four sized 5747 internal formats, as well as the base internal format 5748 STENCIL_INDEX: 5749 5750 STENCIL_INDEX1_EXT 5751 STENCIL_INDEX4_EXT 5752 STENCIL_INDEX8_EXT 5753 STENCIL_INDEX16_EXT 5754 5755 (60) If depth buffer is disabled when a user-created framebuffer 5756 object is bound and an image is attached to GL_DEPTH, does the 5757 depth buffer factor into framebuffer validity determination or 5758 is the depth buffer ignored? Similar for other types of 5759 logical buffers. 5760 5761 RESOLUTION: resolved, consider all attached images when 5762 determining framebuffer completeness, even if the images are 5763 "irrelevant" based on the state of the framebuffer. 5764 5765 The main reason to consider not paying attention to certain 5766 images (i.e., ignoring the image attached to the depth 5767 buffer when depth test is disabled) would be developer 5768 convenience. The developer wouldn't need to explicitly 5769 detach a buffer, but could set the state to ignore it 5770 (disable depth test, or disable color mask, reset draw 5771 buffer, etc). 5772 5773 However, this raises the possibility that by simply changing 5774 this other state (depth test, stencil test, color mask, etc) 5775 the query for framebuffer completeness could change values. 5776 This was deemed undesirable. We'd like to be able to 5777 minimize the amount of state changes that can cause the 5778 framebuffer completeness query to change. 5779 5780 Another strange effect of ignoring "irrelevant" images when 5781 considering framebuffer completeness is that we could get an 5782 undesirable interaction between draw buffer and the pixel 5783 format for the framebuffer. A framebuffer is considered 5784 incomplete if the color buffers do not all have the same 5785 internal format. But, consider the following case: 5786 5787 - an application attaches a floating point 5788 color-renderable image to COLOR_ATTACHMENT1, and 5789 5790 - the application attaches a fixed point 5791 color-renderable image to COLOR_ATTACHMENT2 and 5792 5793 - the application sets the DRAW_BUFFER to 5794 COLOR_ATTACHMENT1, then 5795 5796 If we ignored the attached images not pointed to by 5797 DRAW_BUFFER(s} when evalutating framebuffer completeness, we 5798 could consider this framebuffer complete. This framebuffer 5799 would use floating point rendering. Now, if the application 5800 simply changes the DRAW_BUFFER to COLOR-ATTACHMENT2, then we 5801 would also say the framebuffer is complete but now the 5802 framebuffer would be using fixed point rendering. We didn't 5803 want to allow a change to DRAW_BUFFER to effectively change 5804 the pixel format. On the other hand if we always considered 5805 all attached images, then in this case described above, the 5806 framebuffer would always be incomplete while the formats of 5807 the color-renderable images were inconsistent. 5808 5809 To avoid the above complications, we choose to have 5810 framebuffer completeness queries consider all attached 5811 buffers, regardless of whether they would be "used" 5812 according to the current state vector or not. 5813 5814 (61) What are the "minimum requirements" to support this extension? 5815 5816 RESOLUTION: resolved, language added to end of 4.4.4.2 5817 5818 For instance, is it a requirement that there must be at 5819 least one renderable color, depth, and stencil format that 5820 can all work together? is it a requirement that you must be 5821 able to render to *any* "color-renderable" texture format? 5822 5823 Since this extension specifically pulling in functionality 5824 that used to be in the domain of the window sytem, we would 5825 like to use as a starting point for our requrirements, the 5826 language from the GLX 1.3 spec, page 15, which lists the 5827 minimum requirements langauge for a conformant GLX 5828 implementation. 5829 5830 Questions to answer: 5831 5832 - is the GLX spec a good starting point? 5833 5834 - do we want the same requirements as the GLX spec? 5835 5836 - do we want stronger requirements than the GLX spec? 5837 5838 - do we want some kind of requirement that states that 5839 to support this extension, there must be at least one 5840 "gl conformant" framebuffer configuration that can be 5841 constructed on a given implementation? If so, how do 5842 we phrase this? 5843 5844 Anyway, the GLX spec states: 5845 5846 "Servers are required to export at least one GLXFBConfig 5847 that supports RGBA rendering to windows and passes 5848 OpenGL conformance (i.e., the GLX RENDER TYPE attribute 5849 must have the GLX RGBA BIT set, the GLX DRAWABLE TYPE 5850 attribute must have the GLX WINDOW BIT set and the GLX 5851 CONFIG CAVEAT attribute must not be set to GLX NON 5852 CONFORMANT CONFIG). This GLXFBConfig must have at least 5853 one color buffer, a stencil buffer of at least 1 bit, a 5854 depth buffer of at least 12 bits, and an accumulation 5855 buffer; auxiliary buffers are optional, and the alpha 5856 buffer may have 0 bits. The color buffer size for this 5857 GLXFBConfig must be as large as that of the deepest 5858 TrueColor, DirectColor, PseudoColor, or StaticColor 5859 visual supported on framebuffer level zero (the main 5860 image planes), and this confguration must be available 5861 on framebuffer level zero." 5862 5863 So if we did a direct translation of these requirements into 5864 our spec, we'd end up with something approximately like the 5865 following: 5866 5867 Although GL defines a wide variety of internal formats 5868 for textures and renderbuffers, some implementations may 5869 not support particular combinations of internal formats 5870 for the images attached to the framebuffer. For a 5871 framebuffer with these unsupported combinations of 5872 internal formats, calls to CheckFramebufferStatusEXT() 5873 will return FRAMEBUFFER_UNSUPPORTED_EXT. 5874 5875 There must exist, however, at least one combinations of 5876 internal formats for the images attached to the 5877 framebuffer for which CheckFramebufferStatusEXT() will 5878 *not* return FRAMEBUFFER_UNSUPPORTED_EXT. 5879 5880 Specifically, implementations are required to support at 5881 least one set of internal formats for the images 5882 attached to a framebuffer such that 5883 5884 - the image attached to the color buffer supports 5885 RGBA rendering, and 5886 5887 - the image attached to the color buffer has at 5888 least as many bits as the deepest visual supported 5889 by the window-system, although the alpha buffer 5890 can have 0 bits, and 5891 5892 - the image attached to the depth buffer has at 5893 least 12 bits, and 5894 5895 - the image attached to the stencil buffer has at 5896 least 1 bit, and 5897 5898 - rendering to this framebuffer passes OpenGL 5899 conformance." 5900 5901 However, it looks like no one is seriously using the 5902 NON_CONFORMANT_CONFIG bit under GLX or AGL, and on WGL, 5903 there is no such bit, so we'd like to "assume" conformance 5904 and drop the last clause. Additionally, we'd like to just 5905 piggy back on the existing requirements without duplicating 5906 them here so we will simplify this language to leave out the 5907 last paragraph and list of clauses altogether. 5908 5909 We do wish to retain the notion that there must be some 5910 configuration for which FRAMEBUFFER_UNSUPPORTED_EXT is not 5911 returned. 5912 5913 (62) Exactly which, if any, queriable state can change after a call 5914 to BindFramebuffer and/or a change in framebuffer attachments? 5915 5916 RESOLUTION: resolved, at the Sept. 2004 ARB meeting we 5917 resolved in principle that there is a small subset of 5918 "framebuffer-related" state that can change. We just need 5919 to define exactly the subset. The current subset as listed 5920 in section 4.4.5 is below: 5921 5922 AUX_BUFFERS 5923 MAX_DRAW_BUFFERS 5924 MAX_COLOR_ATTACHMENTS 5925 RGBA_MODE 5926 INDEX_MODE 5927 DOUBLEBUFFER 5928 STEREO 5929 SAMPLE_BUFFERS 5930 SAMPLES 5931 {RED|GREEN|BLUE|ALPHA}_BITS 5932 DEPTH_BITS 5933 STENCIL_BITS 5934 ACCUM_{RED|GREEN|BLUE|ALPHA}_BITS 5935 5936 The reason this is an issue is that traditionally there are 5937 some GL context state queries that are dependent on pixel 5938 format and window-system state. For instance, doing a 5939 GetIntegerv of DEPTH_BITS returns the bit depth of the 5940 window-system allocated depth buffer which is a function of 5941 the pixel format. If DEPTH_BITS is zero, this means that no 5942 depth buffer was present in the pixel format. Other context 5943 state queries like MAX_DRAW_BUFFERS, MAX_ACCUM_BUFFERS, 5944 SAMPLES, etc are all possibly functions of the current pixel 5945 format, and have traditionally been constant over the 5946 lifetime of a given context. 5947 5948 However, this extension specifically subsumes some of the 5949 operations and state of the window-system pixel format 5950 mechanism. So an obvious question is: what should these 5951 queries return for things like DEPTH_BITS and 5952 MAX_DRAW_BUFFERS when using a non-default framebuffer 5953 object? 5954 5955 If we allow these queries to return a value that is a 5956 function of the current framebuffer object, then a 5957 consequence is that the values returned by these queries can 5958 change after a call to BindFramebuffer and/or a change in 5959 the attachments of the currently bound framebuffer object. 5960 5961 This may be desirable: for instance, a user may rightly 5962 expect that querying RED_BITS returns the red bits of the 5963 currently attached color buffer(s). But is the user also 5964 expecting that MAX_DRAW_BUFFERS might change? What about 5965 SAMPLES or SAMPLE_BUFFERS? What about 5966 MAX_COLOR_ATTACHMENTS? 5967 5968 Consider that in developing ARB_draw_buffers it was stated 5969 that some implementations might want to set MAX_DRAW_BUFFERS 5970 to 1 for pixel formats that also supported multisampling. 5971 This would allow implementations to control which 5972 capabilities they exported. What facilities do we have for 5973 this in this extension - can MAX_DRAW_BUFFERS change if we 5974 supported multisampling on a non-default framebuffer object? 5975 5976 Fundamentally, all of the state in table 6.28-6.31 of the 5977 OpenGL 1.5 spec (the MAX_* queries) can in theory change as 5978 the result of the pixel format changing. Since this 5979 extension does an effective pixel format change, what if any 5980 of this state can/should be allowed to change when 5981 framebuffer attachments are changed? 5982 5983 (63) Should we change ValidateFramebuffer into an explicit 5984 enum-based query for framebuffer completeness? 5985 5986 RESOLUTION: resolved, separate API function rather than a 5987 Get query, to emphasize the "on-demand" state examination. 5988 5989 We did choose a different name for ValidateFramebuffer(). 5990 In issue (67) we decided to rename this function 5991 CheckFramebufferStatus(). 5992 5993 For reference the reason this is an issue is that, as 5994 originally described, ValidateFramebuffer (now called 5995 CheckFramebufferStatus) served three purposes: 5996 5997 First, it forced an "on-demand" examination of the current 5998 framebuffer state (including framebuffer attachment state) 5999 and the state of the attached images. On some 6000 implementations this examination might be expensive, and 6001 therefore there was a desire to control exactly when the 6002 operation would occur. 6003 6004 Second, because of the implementation dependent reasons that 6005 a framebuffer might be considered not complete, 6006 ValidateFramebuffer served as a query for an application to 6007 determine at run-time if a seemingly compatible combination 6008 of attached images is actually incompatible on the current 6009 GL implementation. 6010 6011 Third, ValidateFramebuffer was more than just a query. It 6012 was a function that would set a piece of framebuffer state 6013 that "enabled" rendering if the framebuffer was determined 6014 to be complete. After certain changes to framebuffer state, 6015 or in the initial default state, unless ValidateFramebuffer 6016 was called prior to rendering, and unless framebuffer 6017 validation "passed", rendering would be disabled. 6018 6019 However, now that it is no longer required to call 6020 ValidateFramebuffer prior to rendering, ValidateFramebuffer 6021 doesn't really set any state. The third reason is no longer 6022 pertinent. 6023 6024 This leaves us with the first and second reasons. The first 6025 reason in particular seems to be driven by convenience. It 6026 is convenient to be able to control when this operation 6027 happens, but it is arguably also convenient to be able to 6028 force the examination/validation of a wide variety of other 6029 pieces of GL state, yet we don't have specific on-demand 6030 "ValidateTexture" or "ValidateBlendState" routines. In 6031 addition, on some implementations framebuffer validation may 6032 be less expensive than originally thought. 6033 6034 So if we ignore the first reason for a moment, we are left 6035 the second reason for ValidateFramebuffer - a query of the 6036 framebuffer completeness. We do wish to retain this query 6037 somehow, so we could choose to leave it in its current form, 6038 or we could choose to make it look like other more 6039 traditional queries, i.e., some kind of GetInteger, 6040 GetFramebuffer, or GetFramebufferParameter call. 6041 6042 If we feel like the first reason is still valid, we could 6043 also choose to retain a ValidateFramebuffer call to get the 6044 "on-demand" state examination and still choose to make 6045 separate query for the framebuffer completeness. 6046 6047 Either way, if we decide to make an enum-based query we need 6048 to choose the form. We could choose to use GetInteger and 6049 query for COMPLETENESS. (If we do this, we'd need a 6050 "per-target" variant of the enum, i.e., 6051 FRAMEBUFFER_COMPLETE, and if a read framebuffer target is 6052 added later, READ_FRAMEBUFFER_COMPLETE would need to be 6053 added as well.) This would be similar to how texture 6054 bindings are queried on a per target basis as in 6055 GetIntegerv(TEXTURE_BINDING_2D, ¶m). Another option is 6056 to add a target-aware query routine, i.e., 6057 GetFramebufferiv(FRAMEBUFFER, COMPLETE, ¶m); this is 6058 similar to what the ARB vertex/fragment program API's did to 6059 query per-target state like PROGRAM_NATIVE_INSTRUCTIONS_ARB. 6060 6061 (64) Should it be a GL error to attempt to render with an incomplete 6062 framebuffer? 6063 6064 RESOLUTION: resolved, "YES" 6065 6066 In looking at other GL resources that can be considered 6067 "incomplete" for rendering, there were two precedents to 6068 draw on here: (a) textures and (b) programs/shaders. 6069 6070 a) For textures, the GL behaves as if the incomplete 6071 resource is simply not available. That is, if an 6072 application attempts to render with an incomplete texture, 6073 then the GL behaves as if texturing is simply disabled. No 6074 error is thrown. 6075 6076 b) For ARB_vertex_program and ARB_fragment_program, and GLSL 6077 shaders, if a program or shader is invalid, then the GL 6078 throws an error at "Begin" time. 6079 6080 Originally, we choose style (a): treat an incomplete 6081 framebuffer similar to a "pixel ownership test failure". 6082 This means that no fragments are generated, reads of the 6083 framebuffer generate undefined pixels, and no error is 6084 thrown. 6085 6086 [NOTE: Technically, according to the GL spec, the fate of 6087 rendered fragments that fail the pixel ownership test is 6088 left up to the window-system and is therefore implementation 6089 dependent. A better way to handle this is to mimic 6090 make_current_read's language "as if DRAW_BUFFER is NONE"] 6091 6092 However, since the a query of framebuffer completeness can 6093 only answer the question "is the framebuffer complete right 6094 now?", but doesn't indicate whether the application may have 6095 attempted to render with an incomplete framebuffer earlier, 6096 we decided to throw an error in this case as an aid to the 6097 developer. Throwing an error has an advantage in that the 6098 error state is retained, like all GL errors until the user 6099 calls GetError(). 6100 6101 Another option that was considered was to extend the 6102 framebuffer completeness query to indicate that the 6103 framebuffer is complete now, but was incomplete during 6104 earlier rendering. The downside of this option was that 6105 then there would then be two return values for the query 6106 that would mean "framebuffer complete right now". So in the 6107 end, we simply decided to leverage the existing GetError 6108 semantics to capture this "sticky" error behavior. 6109 6110 One additional concern was that gl errors are traditionally 6111 only used to indicate programming errors on the part of the 6112 application, but the framebuffer completeness test may have 6113 failed simply because of implementation dependencies through 6114 no fault of the application. We decided to adopt the notion 6115 is that it is an error to attempt to render with an 6116 incomplete framebuffer, on all implementations, and so it 6117 actually *is* a programming error if an application does not 6118 attempt to deal with an incomplete framebuffer prior to 6119 rendering. 6120 6121 (65) If it is an error to render to or read from an incomplete 6122 framebuffer, should we use INVALID_OPERATION or create a new 6123 error? 6124 6125 RESOLUTION: resolved, INVALID_FRAMEBUFFER_OPERATION_EXT 6126 6127 We resolved to create a new error at the September ARB 6128 meeting and then resolved the name of the error within 6129 the work group. 6130 6131 We agreed that if we throw an error here, we'd like a 6132 new error enum, particularly because the error may have 6133 been triggered by a framebuffer which is incomplete for 6134 implementation dependent reasons. 6135 6136 Some options for the new error name which were discussed: 6137 6138 OPERATION_ON_INCOMPLETE_FRAMEBUFFER 6139 INCOMPLETE_FRAMEBUFFER 6140 IMPLEMENTATION_DEPENDENT_FAILURE 6141 INVALID_FRAMEBUFFER 6142 INVALID_FRAMEBUFFER_OPERATION 6143 6144 (66) There are several issues related to how we treat DrawBuffer(s) 6145 and other context state with respect to framebuffer 6146 completeness. We'd like a self-consistent model here and this 6147 may affect the resolution of issue (8), (44), (55), and (56). 6148 6149 RESOLUTION: resolved, (d) - no context state in framebuffer 6150 completeness test, but context state can affect whether 6151 rendering takes place, does not take place, or is undefined. 6152 Note option (d) required us to revisit issue (44). 6153 6154 The first question we had to answer was: 6155 6156 Is it desireable that "framebuffer completeness" be 6157 purely a property of the set of framebuffer state (which 6158 includes the state of the images attached to the 6159 framebuffer)? Or can a framebuffer's completeness 6160 depend on "non-framebuffer" context state as well? 6161 6162 For instance, there are currently two pieces of context 6163 state that can affect framebuffer completeness: texture 6164 binding state and draw buffer state. 6165 6166 First, in issue (44), we decided that attaching an image of 6167 a currently bound and enabled texture to a framebuffer can 6168 cause a framebuffer to be incomplete. The texture binding 6169 is context state and there are pieces of the texture object 6170 state (base level, max level) that can also affect the 6171 determination of framebuffer completeness. (Additionally if 6172 we add render-to-vertex-array functionality later, we might 6173 expect to have a framebuffer completeness requirement that 6174 examines the state of the currently bound vertex array.) 6175 6176 One way to avoid this context dependency is to revisit issue 6177 (44) and say that this "texture-from-destination" case 6178 simply generates undefined rendering but does not affect 6179 framebuffer completeness. This would replace the "expressly 6180 disabled" rendering and framebuffer incompleteness with 6181 "undefined rendering", but would also let implementations 6182 avoid checking context state during the validation of the 6183 framebuffer state. 6184 6185 The second piece of context state that might cause 6186 framebuffer validation failures is the draw buffer(s) and/or 6187 read buffer state. It has been suggested in issue (55) that 6188 if the draw buffers specify attachment points with no 6189 attached images, then the framebuffer might be considered 6190 incomplete. If we choose to do this, then we would have 6191 context state influencing framebuffer completeness state. 6192 However, if we resolve issue (56) to say that the draw 6193 buffer state is part of the framebuffer object state, then 6194 the draw buffer is no longer context state and this 6195 particular dependency of framebuffer completeness on context 6196 state goes away. 6197 6198 The above discussion leaves us with several self-consistent, 6199 but different sets of decisions: 6200 6201 (a) Remove context dependencies from framebuffer 6202 completeness. 6203 6204 To do this we would: 6205 6206 - Move draw buffer state from context into 6207 framebuffer: issue (56) 6208 6209 - Make "texture-from-destination" undefined instead 6210 of a reason for framebuffer incompleteness: issue 6211 (44) 6212 6213 - Presumably, if we created a render-to-vertex-array 6214 extension layered on this one, we would likely 6215 also make rendering into the currently bound 6216 vertex array undefined as well. 6217 6218 With option (a), we can say that having draw buffer 6219 set to an non-existent buffer is a reason for 6220 framebuffer incompleteness and there are no context 6221 dependencies. This would resolve issue (55). 6222 6223 (b) Allow context dependencies in framebuffer 6224 completeness. 6225 6226 Essentially this means that the result of a query of 6227 framebuffer completeness is dependent on the context 6228 making the query - or put another way, the 6229 framebuffer completeness state is context state not 6230 framebuffer state. 6231 6232 If we choose this option (b), then we are esentially 6233 free to resolve issues (44), (55), and (56) 6234 however we want. In other words: 6235 6236 - draw buffer can be either context or 6237 framebuffer state: issue (56) 6238 6239 - "texture-from-destination" can be either 6240 undefined or a reason for framebuffer 6241 incompleteness 6242 6243 - draw buffer specifying a non-existent buffer 6244 can be a reason for framebuffer incompleteness 6245 or could result in undefined behavior: issue 6246 (55) 6247 6248 (c) Remove the framebuffer object and make the 6249 framebuffer state part of the context. 6250 6251 This option redefines the issue by not making a 6252 distinction between framebuffer "object" state and 6253 "context" state, therefore framebuffer completeness 6254 depends only on "context" state because all of the 6255 "framebuffer" state is now "context" state. 6256 6257 This would mean that there is now a subset of state 6258 in the context that can be considered the 6259 "framebuffer state" of the context. This is the set 6260 of state that would presumably be pushed/popped 6261 under a theoretical FRAMEBUFFER_BIT for 6262 PushAttrib(). 6263 6264 Regardless of whether there is a framebuffer object, 6265 framebuffer completeness may or may not still depend 6266 on pieces of other "context" state that are not part 6267 of subset of context state related to the 6268 "non-default" framebuffer (for instance, texture 6269 bindings and/or draw buffer state). 6270 6271 If we choose this option (c), 6272 6273 - we remove the framebuffer object: issue (8) 6274 This means: 6275 6276 - removing gen/is/bind/delete framebuffer 6277 object 6278 6279 - moving the attachment state into the 6280 context 6281 6282 - creating new context bind points for 6283 framebuffer attachments and creating new 6284 BindFramebufferAttachableImage calls or 6285 using the FramebufferTexture() calls to do 6286 context binds of framebuffer-attachable 6287 images 6288 6289 - we decide whether there is a single set of 6290 draw/read buffer context state or a 2nd set of 6291 draw/read buffer context state to be used for 6292 "non-default" framebuffer objects. Either way 6293 it's "context" state but we need to know if we 6294 have one set of state or two. This is a 6295 variation on issue (56). 6296 6297 - as in option (b), "texture-from-destination" 6298 can be either undefined or a reason for 6299 framebuffer incompleteness 6300 6301 - as in option (b), a draw buffer specifying a 6302 non-existent buffer can either be a reason for 6303 framebuffer incompleteness or could result in 6304 undefined behavior: issue (55) 6305 6306 - all the framebuffer attachments become context 6307 state 6308 6309 - we add a framebuffer enable/disable bit to use 6310 to distinguish between the "default" and 6311 "non-default" framebuffer 6312 6313 (d) Create a new category of reasons that you can't use 6314 a framebuffer for rendering in a specific context, 6315 but that are not part of the test for "framebuffer 6316 completeness" 6317 6318 Essentially, this is a kind of hybrid of options (a) 6319 and (b). There are no context dependent reasons for 6320 framebuffer incompleteness, but at the same time 6321 there are some additional context-dependent 6322 constraints on using a framebuffer. In other words, 6323 a framebuffer can be complete but still not suitable 6324 for rendering by a given context. 6325 6326 This creates two categories of tests that can be 6327 used to disable rendering - the set of 6328 context-independent test that are used to determine 6329 framebuffer completeness, and the set of tests that 6330 are context-dependent and not used to determine 6331 framebuffer completeness. 6332 6333 An open question is: should we add a separate query 6334 for this second set of context-dependent tests 6335 and/or a "meta-query" that would cover both sets. 6336 This "meta-query" would return "true" if and only if 6337 the framebuffer is complete *and* it can be used in 6338 this context. 6339 6340 Note that while the "is framebuffer complete" query 6341 is required by the fact that a framebuffer can be 6342 incomplete because of implementation dependent 6343 reasons, the second query of the context-dependent 6344 test results and the "meta query" are primarily 6345 debugging aids, though perhaps convenient ones. 6346 6347 The framebuffer completeness query is analogous to 6348 asking if a texture is "mipmap complete". The 6349 question, "can I render into my framebuffer", is 6350 analgous to asking the question, "is texturing 6351 enabled." A bound texture may be "complete", but 6352 texturing can still be disabled due to an 6353 unfortunate combination of non-texture-object 6354 context state. Option (d) is basically saying the 6355 same thing of framebuffer objects. 6356 6357 To implement option (d), we'd do the following: 6358 6359 - If draw buffer is defined as "context state" it 6360 can not affect framebuffer completeness, but if 6361 draw buffer is defined as framebuffer state it 6362 might affect framebuffer completeness. See issues 6363 (55) and (56). 6364 6365 - Make "texture-from-destination" undefined instead 6366 of a reason for framebuffer incompleteness: issue 6367 (44). Technically, this could still be an error 6368 unrelated to framebuffer completeness, but we are 6369 trying to avoid creating a precedent for arbitrary 6370 "errors at begin time". When this case was 6371 included in the "framebuffer completeness" 6372 validation, the additional cost of generating the 6373 error was free. But if this 6374 "texture-from-destination" case is not part of 6375 framebuffer completeness, then it is an additional 6376 cost at begin time to detect this in order to flag 6377 an error (and/or disable rendering). To avoid 6378 this cost, we would make this undefined. 6379 6380 - Presumably, if we later create a 6381 render-to-vertex-array extension layered on this 6382 one, we would likely also choose the same 6383 resolution for rendering into the currently bound 6384 vertex array as we choose for the currently bound 6385 texture. 6386 6387 (67) In issue (63) we decided we want to use a dedicated API 6388 function to test framebuffer completeness. We might want to 6389 change the name of "ValidateFramebuffer" however. If so, what 6390 name should we use? 6391 6392 RESOLUTION: resolved, CheckFramebufferStatus() 6393 6394 One reason we decided to retain an explicit API function 6395 instead of just using a GetInteger style query is to 6396 emphasis the "on-demand" state examination that takes place 6397 when making this query. 6398 6399 However, some were uncomfortable with the name 6400 ValidateFramebuffer for this purpose. Some felt that it 6401 implied a requirement to call the function, and others felt 6402 it was too similar in name to the GLSL function 6403 ValidateProgram which served a related but slightly 6404 different purpose. So we chose a new name. 6405 6406 Some options we considered: 6407 ValidateFramebufferCompleteness() 6408 CheckFramebufferCompleteness() 6409 CheckFramebufferStatus() 6410 IsFramebufferComplete() 6411 6412 (68) Exactly which levels should by generated by GenerateMipmapEXT? 6413 6414 RESOLUTION: resolved, from TEXTURE_BASE_LEVEL+1 through q 6415 6416 Automatic mipmap generation via GENERATE_MIPMAP generates 6417 from TEXTURE_BASE_LEVEL+1 through p, which is the 1x1 level. 6418 However, applications frequently don't want to waste 6419 computation generating past q, which is the min of 6420 TEXTURE_MAX_LEVEL and p. The only recourse is to accept the 6421 performance hit or to not use GENERATE_MIPMAP. 6422 6423 Arguably GENERATE_MIPMAP should have been specified to 6424 generate only through q. We have the opportunity to "fix" 6425 this problem by "correctly" specifying the new function 6426 GenerateMipmapEXT to generate only from TEXTURE_BASE_LEVEL+1 6427 through q. 6428 6429 As the specification of GenerateMipmapEXT is currently 6430 written, GenerateMipmapEXT only generates levels 6431 TEXTURE_BASE_LEVEL+1 through q. 6432 6433 (69) What should we call the framebuffer objects to distinguish 6434 them from the default framebuffer? 6435 6436 RESOLUTION: resolved, "application-created" 6437 6438 Currently we call these "application-created" framebuffers 6439 Some places in the spec have also referred these as 6440 "GL-allocated" framebuffers. Whichever term we use, we 6441 should use it consistently. 6442 6443 Some terms we considered: 6444 6445 "application-created" framebuffers 6446 "application-allocated" framebuffers 6447 "non-default" framebuffers 6448 "GL-created" framebuffers 6449 "GL-allocated" framebuffers 6450 "dynamically-created" framebuffers 6451 etc. 6452 6453 The GL spec already talks about "creating" textures, not 6454 "allocating" them, so "*-created" seems like a better 6455 choice. 6456 6457 It's a bit of a toss-up between "GL-created" and 6458 "application-created". Technically, the "GL" really creates 6459 and manages these objects but it only does so at the request 6460 of the application. Going with "application-created" for 6461 now. 6462 6463 (70) With which, if any, attribute bit does the framebuffer binding 6464 push and pop? The same question applies to the current 6465 renderbuffer? 6466 6467 RESOLUTION: resolved, don't push/pop framebuffer binding 6468 bit for now. If desired, we may add this in the ARB/core 6469 update of this spec. 6470 6471 There are a few precedents to choose from. 6472 6473 The ARB_vertex/fragment_program extensions chose to *not* 6474 push/pop the current program object binding. It's not clear if 6475 this was intentional or which existing attribute bit was 6476 appropriate to use or if there was a desire to not create a new 6477 attribute bit. 6478 6479 ARB_vertex_buffer_object buffer objects and GL core texture 6480 objects do push/pop the bindings with the existing VERTEX_ARRAY 6481 and TEXTURE bits respectively. In addition, the texture enables 6482 are push/pop'ed with the TEXTURE bit. 6483 6484 If we do wish to push/pop the FRAMEBUFFER_BINDING_EXT state we 6485 probably need a new FRAMEBUFFER bit. 6486 6487 We could also consider adding a RENDERBUFFER_BIT to cover the 6488 current renderbuffer binding or allow this renderbuffer binding 6489 to push/pop with the FRAMEBUFFER bit. However, it's less clear 6490 that push/pop'ing the renderbuffer binding is useful since the 6491 renderbuffer binding is not used for rendering. The 6492 renderbuffer binding is only used to set the current 6493 renderbuffer for renderbuffer storage allocation and queries. 6494 6495 Also, there are a related set of questions about how much state 6496 should push/pop with a new FRAMEBUFFER bit. Should we push/pop 6497 all of the framebuffer object state in addition to the current 6498 binding? Similar to the way vertex array's can be attached to 6499 VBO's, use of VBO, framebuffers can be attached to other GL 6500 objects. The TEXTURE_BIT covers both per object (min/mag 6501 filter) and per context (texture environment and enable) state. 6502 It's not clear if this is useful or desirable to have per-object 6503 state push/pop. With the addition of object semantics, it seems 6504 like the need for push/pop of object state is reduced. 6505 6506 In the end, since we'd need to create a new bit anyway, we 6507 decided to defer adding push/pop semantics until we understand 6508 the implementation ramifications better. If we decide to create 6509 the bit later on in the ARB or Core revision of this extension, 6510 we can add it in a backward-compatible fashion. 6511 6512 (71) Should we spell out precisely which rendering and reading 6513 routines can cause us to generate an error at the time the 6514 rendering or reading functions are called? 6515 6516 RESOLUTION: resolved, keep the same language as ARB 6517 vertex/fragment program and GLSL for now, with the 6518 addtitions relevant for reading the framebuffer, but 6519 recommend the ARB look at this when doing the next core GL 6520 spec revision. 6521 6522 Currently GL has a few cases that can cause errors at render 6523 time. Specifically, attempting to render with a mapped vertex 6524 buffer object, an invalid low-level vertex or fragment program, 6525 or an invalid GLSL program object all generate errors at "Begin" 6526 time. 6527 6528 This extension adds a new error at "begin" time. Attempting to 6529 render with an "incomplete" framebuffer generates 6530 INVALID_FRAMEBUFFER_OPERATION_EXT. In addition, this extension 6531 adds the same error at "read" time if the application tries to 6532 read from an "incomplete" framebuffer. 6533 6534 The ARB vertex program, ARB fragment program, and GLSL extension 6535 specs state that an app which tries to use an "invalid" object 6536 can generate errors when Begin, RasterPos, or any command that 6537 performs an explicit Begin is called. 6538 6539 This extension has adopted similar language. So the question 6540 asked by this issue is: do we need ot be more explicit. 6541 6542 There are some ambiguities. For instance, it is an error to 6543 write pixels using an "implicit Begin" operation like DrawArrays 6544 if the current vertex program is invalid, but it is not an error 6545 to do an Accum operation which also writes pixels to the 6546 framebuffer. 6547 6548 This issue applies to all of these extensions. 6549 6550 Options include: 6551 6552 - listing all routines which can render or read from the 6553 framebuffer and stating that they can cause an error if 6554 the framebuffer is incomplete, solving the problem for 6555 this extension only. 6556 6557 - adding to the GL core a table of "routines that read 6558 pixels" and "routines that write pixels" and referencing 6559 those tables in the language for each of these extensions. 6560 6561 Because each extension is doing something a little different, 6562 it's not even clear if the second option is a viable option. 6563 It's possible each extension would need its own list of routines 6564 which can generate errors anyway. 6565 6566 Basically, this is a larger problem than this 6567 EXT_framebuffer_object extension. For now, we choose to use the 6568 same (vague-ish) language adopted by the 6569 ARB_vertex/fragment_program and GLSL extnesions. 6570 6571 We do recommend, however, that the ARB address this issue in the 6572 next GL core revision. 6573 6574 (72) Should the framebuffer completeness test include a clause that 6575 says "at least one color attachment" has been made? Or "at 6576 least one attachment of any type"? Or is the framebuffer 6577 still complete when there are no attachments at all? 6578 6579 RESOLUTION: resolved, a framebuffer must have at least one 6580 color-renderable, depth-renderable, or stencil-renderable 6581 image attached to be complete. 6582 6583 While a framebuffer with only depth, or only color 6584 attachments seems plausible, we couldn't come up with a 6585 sensible use for a framebuffer with no attachments at all, 6586 so the assumption is that this is an unintended error on the 6587 part of the application. Therefore, we choose to make it 6588 part of the framebuffer completeness test. 6589 6590 We could make this its own clause in the framebuffer 6591 completeness test. If we choose to do so, we should 6592 probably come up with a new FRAMEBUFFER_INCOMPLETE_* to 6593 conform to our previous practice of keeping one enum per 6594 clause. 6595 6596 However, since this is really related to the attachment 6597 state, we could just piggy back this on the first clause and 6598 same all the attachment points must be "attachment complete" 6599 and there must be at least one color, depth, or stencil 6600 buffer attached. 6601 6602 If we choose this latter option, we can continue to use the 6603 FRAMEBUFFER_INCOMPLETE_ATTACHMENT enum to cover this case. 6604 6605 (73) This clause from framebuffer completeness (before it was 6606 reworded, see below): 6607 6608 * The value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT must 6609 not be NONE for any color attachment point named by 6610 READ_BUFFER. 6611 6612 basically requires at least one color attachment is non-NULL. 6613 But this is not what we want. So what should we do? 6614 6615 RESOLUTION: resolved, (4a) READ_BUFFER can be NONE 6616 6617 The reason is: READ_BUFFER is not allowed to be NONE, which in 6618 turn means to be framebuffer complete, READ_BUFFER must be 6619 COLOR_ATTACHMENTn_EXT for some n which has an image attached. 6620 However, we don't wish to preclude a no-color framebuffer. 6621 What should we do? 6622 6623 Options include: 6624 6625 4a) Allow READ_BUFFER of NONE, reads of color from the 6626 framebuffer when read buffer is none, generate error 6627 INVALID_OPERATION 6628 6629 4b) Generate an error when a read operation (ReadPixels, 6630 CopyPixels, etc) is attempted while the color 6631 attachment point referenced by the READ_BUFFER does 6632 not have an attached image. 6633 6634 4c) Reverse earlier decision to allow complete 6635 framebuffer not to have any color attachments. 6636 Instead, require at least one color attachment. 6637 READ_BUFFER must point to a valid color attachment 6638 or else the framebuffer object is incomplete. 6639 6640 (4c) seems to require the user attach a color buffer just to be 6641 able to read the depth buffer of a depth-only framebuffer. 6642 6643 (4b) seems to suffer from the same problem (unless we move the 6644 "valid read buffer" test out of the completeness test). 6645 6646 Of these choices, (4a) seems to be the most palatable. We 6647 choose the allow the value of READ_BUFFER to be NONE, but reads 6648 of color buffers when READ_BUFFER is NONE will generate an 6649 error, in order to be consistent with the decision in issues 6650 (26) and (65). 6651 6652 Note: that clause was eventually reworded to say: 6653 6654 * If READ_BUFFER is not NONE, then the value of 6655 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT must not be NONE for 6656 the color attachment point named by READ_BUFFER. 6657 6658 (74) What should CheckFramebufferStatusEXT return if 6659 FRAMEBUFFER_BINDING_EXT is zero? 6660 6661 Secondary question: what should CheckFramebufferStatusEXT 6662 return if there is an error? 6663 6664 RESOLUTION: resolved, default fb returns COMPLETE always, 6665 and CheckFramebufferStatusEXT returns 6666 FRAMEBUFFER_STATUS_ERROR if there is an error (bad target) 6667 6668 This goes to a larger question of whether all framebuffers 6669 including the default window-system-provided framebuffer 6670 have a "completeness" state, or if "completeness" is only a 6671 property which applies to application-created framebuffers. 6672 6673 For the case where the current FRAMEBUFFER_BINDING_EXT is 6674 zero, options include: 6675 6676 - CheckFramebufferStatusEXT returns an error when 6677 FRAMEBUFFER_BINDING_EXT is zero. 6678 6679 - CheckFramebufferStatusEXT always returns 6680 FRAMEBUFFER_COMPLETE_EXT when FRAMEBUFFER_BINDING_EXT 6681 is zero. 6682 6683 For the case CheckFramebufferStatusEXT generates an error, 6684 options include: 6685 6686 - reworking CheckFramebufferStatus into a "get" style 6687 routine that returns a value (or not) in an input 6688 parameter like GetIntegerv 6689 6690 - returning a known value like NONE or 0 6691 6692 - returning undefined results 6693 6694 (75) How are state values for the stencil index write mask and 6695 stencil reference value affected by this extension? 6696 6697 RESOLUTION: 6698 a) index write mask is stored as 32 bit value, default 6699 is all 1's, and 6700 b) reference value is not clamped on specification but 6701 rather is clamped on use and query, and 6702 c) we need to add the stencil reference value 6703 to the state table that lists the state values that 6704 might change after a framebuffer state change 6705 6706 The reason this is an issue is that the current GL 6707 specification indicates that the stencil index write mask 6708 and the stencil reference value are masked/clamped according 6709 to the number of stencil bitplanes. However, in this 6710 extension the number of stencil bitplanes can now change 6711 dynamically as the image attached to the framebuffer is 6712 changed. 6713 6714 For instance, if these values are clamped/masked according 6715 to the bitdepth of the currently attached stencil buffer, 6716 what should happen if the user later attaches a stencil 6717 buffer of a different bit depth? Must the stencil reference 6718 value or index write mask be respecified? 6719 6720 For the index write mask: we decide to treat this value as 6721 "all 1's" as the current specification allows, but further 6722 define the number of 1's to be 32 (the minimum width of an 6723 integer in GL), and a likely maximum stencil bitdpeth for 6724 the forseeable future. This should retain backward 6725 compatbility and still handle the case where the bitdepth of 6726 the stencil buffer can change dynamically. 6727 6728 For the stencil reference value, we decide to treat this 6729 state similar to way various clamped colors are treated in 6730 the ARB floating point pixel extensions. Specifically, the 6731 state values are clamped against the current logical buffer 6732 bitdepths as they are used for rendering and queried, but 6733 are not clamped on specification. This means that these 6734 state values do not need to be respecified just because the 6735 logical buffer bit depth changes, and retains backward 6736 compatibility to the behavior prior to this extension. 6737 6738 We will update the appropriate sections of the specification 6739 to describe this behavior. 6740 6741 (76) Currently framebuffer objects are shared, should we make them 6742 not shared across contexts? 6743 6744 RESOLUTION: yes, framebuffers are shared like display lists 6745 and textures are shared. 6746 6747 Initially it was suggested that some complicated 6748 multi-context semantics might be avoided if if the namespace 6749 for framebuffer objects were not shared across contexts. 6750 Specifically, some members of the group felt that by not 6751 sharing framebuffer objects, we could avoid the situation 6752 where: 6753 6754 a) one context can change the draw buffer of a 6755 framebuffer object in use by another context. 6756 6757 b) one context can change the attachments of a 6758 framebuffer object which may be in use by another 6759 context. 6760 6761 However, after some discussion, we realized that even if we 6762 didn't share framebuffer objects, there were still 6763 interactions similar to those listed above because the 6764 underlying images could still be shared. Consequently, one 6765 context could still affect the completeness and attachments 6766 of the framebuffers in another context by modifying or 6767 deleting the framebuffer-attachable images shared by both 6768 contexts. 6769 6770 So in the end, we decided to retain the share-ability of 6771 framebuffer objects rather than introduce an asymmetry with 6772 other GL objects like textures. 6773 6774 ADDITIONAL COMMENTS: 6775 6776 See the "Dependencies on ARB_framebuffer_object and OpenGL 3.0" 6777 section above for the interaction behaviour between EXT and 6778 non-EXT FBO interfaces. 6779 6780 (77) If the application deletes an object and that object contains 6781 an image which is attached to a framebuffer object, exactly 6782 when and how is the image detached from the framebuffer? 6783 6784 RESOLUTION: resolved, option (1): images are detached from 6785 the currently bound framebuffer on delete, but images remain 6786 attached to any non-bound framebuffers. 6787 6788 This is issue is somewhat related to the multi-context 6789 object-sharing discussion currently going on in the ARB. 6790 6791 This extension presupposes that framebuffer attachments 6792 represent a reference to the attached image (or more 6793 correctly - a reference to the object containing the 6794 attached image). Since having a reference to an object 6795 affects when the object (and/or its name) is deleted, object 6796 deletion semantics are tied into the notion when the state 6797 describing these references is modified. In other words, 6798 the semantics of when objects are deleted are affected by 6799 the details concerning when a change to the framebuffer 6800 attachment state takes place. 6801 6802 Prior to the EXT_framebuffer_object and GLSL extensions, the 6803 only way in which an object not currently bound to this GL 6804 context could be modified, was when the object was modified 6805 by another GL context. 6806 6807 Both the EXT_framebuffer_object and GLSL extensions allow an 6808 object (texture, renderbuffer, shader) to be attached to a 6809 "container" object (framebuffer, program). With the 6810 introduction of "attachment", an object could be bound to 6811 the context at more than one binding point. For example, a 6812 texture can be bound to TEXTURE_2D_BINDING, and it can also 6813 be indirectly bound through the FRAMEBUFFER_BINDING if it is 6814 attached to the framebuffer object bound to the 6815 FRAMEBUFFER_BINDING. 6816 6817 Furthermore, a texture can be attached (by reference) to a 6818 framebuffer object that is not bound to any context, while 6819 at the same time the texture *is* bound to context's 6820 TEXTURE_2D_BINDING. Because the texture state is a part of 6821 the framebuffer object's state, it is now possible for 6822 modification of a texture through TEXTURE_2D_BINDING to 6823 cause modification of a framebuffer object, even though the 6824 framebuffer object is not bound to any context at the time 6825 it is modified. 6826 6827 One conceptual model for dealing with this situation is to 6828 treat attachment similar to bind, but instead of binding to 6829 a context, you are "binding" to another object. For the 6830 purposes of managing object references, object lifetimes, 6831 state propogation semantics, etc., these attachments can be 6832 considered to be "just like" a bind operation. [A "bind" 6833 and an "attach" are not exactly equivalent, however; see 6834 issue (82) for a further discussion on Bind vs. Attach.] 6835 6836 If we agree on the above conceptual model, then we may wish 6837 to look to the multi-context situation for guidance on how 6838 to treat state changes to non-currently-bound framebuffer 6839 objects. 6840 6841 Unfortunately, the multi-context semantics are poorly 6842 defined by OpenGL. If we decide to use them as a guide, we 6843 should at least define what they are and this is why the 6844 larger ARB is looking at this issue now. 6845 6846 For EXT_framebuffer_object, there are three choices for 6847 behavior. In each case, we defer to the larger ARB the 6848 details about when an object name is available for reuse. 6849 For the purposes of this discussion, we are looking only at 6850 state changes governing the attachments. The three choices 6851 are listed below: 6852 6853 For the sake of concrete simplicity, this discussion 6854 speaks to the images of a texture object; but it applies 6855 equally to the image of a renderbuffer object. 6856 6857 If you delete a texture object while one of the texture's 6858 images is attached to a framebuffer object (or multiple 6859 framebuffer objects), then: 6860 6861 (1) The image is automatically detached from the currently 6862 bound framebuffer object only. 6863 6864 If the image is also attached to any other framebuffer 6865 objects, then the image is NOT automatically detached 6866 from those. 6867 6868 The application is responsible for manually detaching 6869 images from the other framebuffer objects, by 6870 rebinding each framebuffer in turn and performing an 6871 explicit detach operation. 6872 6873 Until the application manually detaches the image from 6874 the other framebuffers, those framebuffers continue to 6875 use the image for rendering. The other framebuffer 6876 objects have a reference to the image until the image 6877 has been detached from them. In this way, attachment 6878 behaves as if the image was "bound to the framebuffer 6879 object". 6880 6881 (2) The image is automatically detached from the currently 6882 bound framebuffer object. Also during DeleteTexture, 6883 the image is automatically detached from any other 6884 framebuffer object to which it is attached; however, 6885 the image is not guaranteed to be detached from the 6886 other framebuffer objects until the next time those 6887 framebuffer objects are bound via BindFramebufferEXT. 6888 6889 Similar to option (1), in order to "really" delete the 6890 object, the application is responsible for rebinding 6891 all the framebuffer objects to which the deleted image 6892 was attached. However, unlike option (1), the 6893 application need not actually perform an explicit 6894 detach operation. The application can merely bind the 6895 framebuffer. 6896 6897 Until the application actually rebinds the framebuffer 6898 the images are not actually detached and deleted. The 6899 other framebuffer objects continue to hold a reference 6900 (like a binding) to the image until the next time the 6901 framebuffer objects are bound. 6902 6903 (3) The image is automatically detached from all 6904 framebuffers objects during DeleteTextures, including 6905 the currently bound framebuffer as well as any other 6906 framebuffers to which the image is attached. 6907 6908 The application need not explicitly bind to, and 6909 detach the image from, any framebuffer that is not 6910 bound at the time DeleteTextures was called. 6911 6912 Because the framebuffer object has a reference to the 6913 texture object, and the texture object's state is 6914 considered part of the framebuffer object's state, 6915 this resolution implies that DeleteTextures may 6916 modifiy the state of a framebuffer object that is not 6917 the currently bound object. 6918 6919 With reference to the object-sharing discussion that is 6920 going on in the ARB right now, for (a)-style 6921 implementations, options (2) and (3) are indistinguishable. 6922 However, for (b)-style implementations, implementing (3) 6923 would require textures to store a list of all attached 6924 framebuffers while (2) would not. 6925 6926 Options (2) and (3) essentially treat the currently-bound 6927 and non-currently-bound framebuffers the same--i.e., 6928 deleting the image (ultimately) detaches it from all 6929 framebuffer. This may be desirable as a convenience to the 6930 application. 6931 6932 On the other hand, Option (1) treats the currently bound 6933 framebuffer special, in that deletions are performed 6934 automatically much like textures are unbound automatically 6935 from the current context's binding points, but they are not 6936 unbound automatically from other contexts' binding points. 6937 Also, Option (1) leaves the application in control of when 6938 the images are detached, which also may be desirable. 6939 6940 We choose option (1) because it is the simplest, and it also 6941 does not unduly burden implementations regardless of their 6942 choice of (a) versus (b) object-sharing model. 6943 6944 If an implementation has the (a)-style object sharing model, 6945 then the fact that images remain attached to non-bound 6946 objects has no affect on when the object name may be 6947 re-used. If the implementation has a (b)-style 6948 object-sharing model, then the outstanding attachments will 6949 delay re-use of the object name until the image has been 6950 detached. Regardless of whether the ARB chooses (a) or (b) 6951 behavior, or even if the ARB chooses to leave this behavior 6952 undefined, we can "piggy-back" on the name-reuse semantics 6953 they decide. 6954 6955 Also, option (1) means that if the application deletes a 6956 texture while one of the texture's images is attached to a 6957 framebuffer object that is not bound, then the application 6958 may continue to render into the image after the framebuffer 6959 is bound again, regardless of the (a) vs. (b) choice. 6960 6961 Finally, note that if a context deletes an object containing 6962 an image attached to the currently bound framebuffer, then 6963 we first detach the image from the bound framebuffer. This 6964 means that the state change to the framebuffer (the detach 6965 operation) is guaranteed to be picked up by any other 6966 context the next time the framebuffer is bound in one of the 6967 other contexts. 6968 6969 (78) Should we collapse the notions of "framebuffer-attachable image 6970 completeness" and "framebuffer attachment completeness" into a 6971 single type of completeness (probably retaining the name 6972 "framebuffer attachment completeness" 6973 6974 RESOLUTION: resolved, yes, eliminate "framebuffer-attachable 6975 image completeness" and add a "non-zero-area" requirement to 6976 the "framebuffer attachement completeness" test. 6977 6978 Originally this extension had several layers of which 6979 affected framebuffer completness. They were: 6980 6981 - framebuffer-attachable image completeness 6982 * image has non-zero width/height/depth 6983 * image has color, depth, or stencil format 6984 * image is not from a proxy texture 6985 6986 - framebuffer attachment completeness 6987 * attached image is textures/renderbuffer 6988 * attached image is from existing object 6989 * attached image has format appropriate 6990 for attachment point (depth buffer 6991 has depth format, etc) 6992 6993 - framebuffer completeness 6994 * all attachment points are "attachment complete" 6995 * all images are "framebuffer-attachable image complete" 6996 * all color buffers have same format 6997 * draw buffer is attached 6998 * read buffer is attached 6999 * framebuffer format combination is supported 7000 7001 However, upon further reflection of the 7002 "framebuffer-attachable image completeness" tests, we 7003 realized that 7004 7005 a) the requirement that the renderble image is not a 7006 "proxy" texture was already covered by the fact that 7007 it's illegal to attach a proxy texture to a 7008 framebuffer, and 7009 7010 b) the requirement that the format be color, depth, or 7011 stencil is essentially already covered by the 7012 "framebuffer attachment completeness" test 7013 requirement that the format is appropriate for the 7014 attachment point. 7015 7016 This left only the "non-zero-area" test, so we decided to 7017 fold this requirement into the "framebuffer attachement 7018 completeness" test and eliminate the concept of 7019 "framebuffer-attachable image completeness". This decision 7020 required the elimination of one of the 7021 FRAMEBUFFER_INCOMPLETE_* enums as they correspond to the 7022 conditions in the "framebuffer completeness" test of section 7023 4.4.4 7024 7025 (79) Should the internal format chosen by GL for a texture (or 7026 renderbuffer) be invariant with respect to the state of the 7027 current framebuffer and its attached images? 7028 7029 RESOLUTION: yes, the choice of internal format must be 7030 invariant with respect to framebuffer state changes. 7031 7032 This means that the GL must choose texture internal format 7033 based only on the arguments to TexImage and ignore the 7034 current framebuffer state in this selection process. 7035 7036 Similarly, the GL must choose renderbuffer internal format 7037 based only on the arguments to RenderbufferStorage and 7038 ignore the current framebuffer state in this selection 7039 process. 7040 7041 This issue is a variant of issue (62). The OpenGL 2.0 7042 specification (p.152, paragraph 4) states that: 7043 7044 "A GL implementation may vary its allocation of 7045 internal component resolution or compressed internal 7046 format based on any TexImage3D, TexImage2D (see below), 7047 or TexImage1D (see below) parameter (except target), 7048 but the allocation and chosen compressed image format 7049 must not be a function of any other state and cannot be 7050 changed once they are established." 7051 7052 Consider that prior to this extension, some implementations 7053 may have considered the the bitdepths of the logical buffers 7054 of the framebuffer or the bitdepth of the display when 7055 choosing an internal format for textures. Since, in 7056 practice, these bitdepths typically were immutable for the 7057 lifetime of a GL context, the invariance requirements were 7058 met. 7059 7060 With the introduction of EXT_framebuffer_object, however, 7061 the logical buffer bitdepths can change over the lifetime of 7062 the context. So this issue examines whether or not 7063 framebuffer state is allowed to affect texture internal 7064 format selection. 7065 7066 After some discussion, we felt it was too problematic to 7067 introduce this type of invariance. So this extension makes 7068 no modifications to the invariance language, and adds 7069 similar invariance language applicable to renderbuffer 7070 objects. As long as the app provides the same arguments to 7071 TexImage{1D|2D|3D} or RenderbufferStorage, then the GL must 7072 always choose the same internal format. 7073 7074 Note, however, that the GL is not required to provide the 7075 same internal format resolution for renderbuffers as it does 7076 for textures. 7077 7078 (80) Should attachment routines be display-list'able? 7079 7080 RESOLUTION: no, in fact none of the routines introduced in 7081 this extension are included in display lists. 7082 7083 Initially, we were just considering whether or not the 7084 framebuffer attachement routines should be included in 7085 display lists. The rationale for not including them was 7086 that since query routines can not be in display lists, and 7087 well-behaved apps should call the query routine 7088 CheckFramebufferStatusEXT() after calling making changes to 7089 framebuffer attachments, it was not possible to write a 7090 well-behaved app that uses display lists to build up and use 7091 a framebuffer. So, one possible solution was to simply 7092 disallow from display lists the routines that change change 7093 the result of CheckFramebufferStatusEXT(). 7094 7095 However, we realized on further consideration that other 7096 routines which can affect the results of 7097 CheckFramebufferStatusEXT are already allowed in display 7098 lists. Namely, the routines which affect textures (TexImage 7099 and friends). So, disallowing the attachment routines is a 7100 partial solution at best. 7101 7102 We also looked for various precedents and found some mixed 7103 results: 7104 7105 - VBO bind operations are not display-list'able, but 7106 this is primarily because the VBO bindings are 7107 considered client-state 7108 7109 - texture bindings are display-list'able 7110 7111 In the end, though we decided to not include the routines 7112 introduced by this extension in display lists for reasons of 7113 simplicity more than anything else. 7114 7115 It's possible we may need to add support for display lists 7116 back in during promotion of this extension if we determine 7117 that it is needed later, but for now, we leave this out. 7118 7119 (81) How should PushAttrib and PopAttrib work with this extension? 7120 7121 RESOLUTION: mostly deferred for now, may revisit later 7122 7123 This extension introduces no new push/pop attrib bits to 7124 cover the state introduced by this extension (for instance 7125 there is no FRAMEBUFFER_BIT). So the only real question to 7126 answer is what effect should Push/Pop attrib have on any 7127 existing state as it relates to this extension. 7128 7129 In particular, how should Push/PopAttrib of the 7130 COLOR_BUFFER_BIT which covers the DRAW_BUFFER and 7131 READ_BUFFER state interact with this extension? Does the 7132 COLOR_BUFFER_BIT affect the per-object DRAW_BUFFER and 7133 READ_BUFFER state? 7134 7135 Currently, the answer is yes. PushAttrib(COLOR_BUFFER_BIT) 7136 saves the DRAW_BUFFER value of the currently bound 7137 framebuffer object. If the app later calls PopAttrib() this 7138 saved value will be restored even if the framebuffer bound 7139 at the time PopAttrib is called is different from the 7140 framebuffer bound at the time PushAttrib was called. 7141 7142 In other words, one are considering whether or not it is 7143 strange that PushAttrib(COLOR_BUFFER_BIT) affects a piece of 7144 per-object state. Note that this is somewhat similar to the 7145 way that a PushAttrib(TEXTURE_BIT) can save off 7146 per-texture-object state and a later call to PopAttrib can 7147 restore that per-object state even if the texture bound at 7148 PopAttrib time has since been changed/ deleted/modified in 7149 some way. 7150 7151 There are some differences with the texture analogy though. 7152 Namely, the TEXTURE_BIT does include the texture bindings so 7153 at least the texture object binding is restored in 7154 conjunction with the per-texture-object state. Also, some 7155 may consider the fact that the TEXTURE_BIT affects 7156 per-texture-object state more intuitive than the fact that 7157 the COLOR_BUFFER_BIT affects per-framebuffer-object state. 7158 7159 Also, there is a larger discussion going on in the ARB right 7160 now about whether PushAttrib/PopAttrib save references to 7161 existing bound objects or only the state values which name 7162 an existing bound object. 7163 7164 For now, we have deferred further discussion of the 7165 PushAttrib/PopAttrib semantics in this extension until the 7166 larger issues are cleared up. 7167 7168 (82) What is the relationship between a "binding" and an 7169 "attachment"? 7170 7171 RESOLUTION: resolved, the concept of attachment is described 7172 below, though final implications will be affected by larger 7173 ARB discussions about object sharing and multiple context 7174 semantics. 7175 7176 "Attaching" is the act of connecting one object to 7177 another object. 7178 7179 An "attach" operation is similar to a "bind" operation 7180 in that both represent a reference to the attached or 7181 bound object for the purpose of managing object 7182 lifetimes and both enable manipulation of the state of 7183 the attached or bound object. 7184 7185 However, an "attach" is also different from a "bind" in 7186 that "binding" an unused object creates a new object, 7187 while "attaching" does not. Additionally, "bind" 7188 establishes a connection between a context and an 7189 object, while "attach" establishes a connection between 7190 two objects. 7191 7192 Finally, if object "A" is attached to object "B" and 7193 object "B" is bound to context "C", then in principle, 7194 we treat "A" as if it is <implicitly> bound to "C". 7195 7196 The larger ARB is currently attempting to more clearly 7197 define the mutliple context semantics as they relate to 7198 object sharing and binding. The final implications for 7199 EXT_framebuffer_object may not be clear until those 7200 discussions are resolved. This extension may need an 7201 update once those issues are addressed. 7202 7203 (83) We use a non-zero framebuffer binding to enable the use of this 7204 extension. Should we instead consider using an explicit 7205 enable? 7206 7207 RESOLVED: no, retain the "non-zero-binding means enable" 7208 semantics. 7209 7210 Currently we enable the use of an application-created 7211 framebuffer by binding a non-zero framebuffer object to 7212 FRAMEBUFFER_EXT binding point. If the framebuffer binding 7213 is zero, then the extension is disabled (i.e., we use the 7214 window-system-provided framebuffer). 7215 7216 It might be cleaner to be able to say things like, "when 7217 FRAMEBUFFER_OBJECT is enabled", rather than "when the 7218 framebuffer binding is not zero", and add an explicit 7219 enable. Doing so would also allow changing framebuffer 7220 object attachments while FBO is disabled, which might result 7221 in the driver doing less validation while the application is 7222 setting up framebuffer objects. It would also provide a 7223 cleaner way to explain that the permitted DRAW_BUFFER and 7224 READ_BUFFER values change when the extension is 7225 enabled/disabled. 7226 7227 There are a few object model precedents to choose from: 7228 Textures and ARB Vertex and Framgment Program extensions use 7229 the explicit enable state. However, Vertex Buffer Objects, 7230 Pixel Buffer Objects, and GLSL Vertex and Fragment shaders 7231 use a non-zero-binding to enable the use of those features. 7232 7233 If we used an explicit enable, then we could allow creation 7234 of an object named zero. Precedent dictates that an object 7235 named zero is never shared in the context share group. All 7236 other framebuffer objects are shared across the share group. 7237 It might be cleaner to disallow creation of an object named 7238 zero anyway. 7239 7240 Since binding to zero disables the extension, one way to 7241 think about this is that there is an object named zero which 7242 is managed through MakeCurrent, MakeContextCurrent, and the 7243 window manager. All other objects are managed through 7244 FramebufferTexture, FramebufferRenderbuffer, and the 7245 operations that define/modify texture and renderbuffer 7246 images. When looked at in this light, lack of an explicit 7247 enable is not as strange. 7248 7249 (84) Do we need to add any language to describe the y-orientation of 7250 framebuffer-attachable images? Specifically, what coordinate 7251 system is used by images attached to the framebuffer? 7252 7253 Resolution: unresolved 7254 7255 GL defines the rendering origin at the lower-left corner. 7256 Yet, because of the differences between orientation storage 7257 of textures and images, pbuffer rendering is often 7258 implemented using a "y-inverted" coordinate system. Is this 7259 y-inversion exposed in the API? 7260 7261 Is the origin in the lower-left? Upper-left? Do we need to 7262 say anything about this at all, or is it already covered by 7263 existing GL language? 7264 7265 Currently there is place-holder text in section 4.4.2.3 7266 7267 The intent of this specification is simply to mirror the 7268 y-orientation issues of the pbuffer style render to texture 7269 API's. What's unclear is whether this requires any new 7270 language in this specification or not. 7271 7272 (85) Explain what happens when the FBO has a different width/height 7273 from the window? 7274 7275 An FBO takes on the width/height of its attachments. This 7276 width/height can be different than the width/height of the 7277 window (of framebuffer "zero"). 7278 7279 In such cases, after calling BindFramebuffer, it is the 7280 application's responsibility to set the glViewport and the 7281 glScissor (if necessary) to match that of the new 7282 framebuffer binding. 7283 7284 Some background: The default viewport for a context is 7285 defined by the dimensions of the window to which the context 7286 is first made current. When the window is resized, or when 7287 the context is bound to a different window, the viewport 7288 does not change automatically. It has always been the 7289 application's responsibility to set the viewport after one 7290 of these events. FBO is no different; after BindFramebuffer 7291 it is the application's responsibility to set the viewport 7292 if the new framebuffer binding has a different width/height 7293 than the old binding.. 7294 7295 (86) Are any one- or two- component formats color-renderable? 7296 7297 Presently none of the one- or two- component texture formats 7298 defined in unextended OpenGL is color-renderable. The R 7299 and RG float formats defined by the NV_float_buffer 7300 extension are color-renderable. 7301 7302 Although an early draft of the FBO specification permitted 7303 rendering into alpha, luminance, and intensity formats, this 7304 this capability was pulled when it was realized that it was 7305 under-specified exactly how rendering into these formats 7306 would work. (specifically, how R/G/B/A map to I/L/A) 7307 7308 To resolve this we seem to have two options: 7309 7310 A) Add new R and RG formats like NV_float_buffer did. 7311 7312 B) For the existing one- and two- component formats, define 7313 the mapping from RGBA components to ILA components. 7314 7315 The superbuffers group has informally decided that option A 7316 is preferable. 7317 7318 (87) What happens if a single image is attached more than once to a 7319 framebuffer object? 7320 7321 RESOLVED: The value written to the pixel is undefined. 7322 7323 There used to be a rule in section 4.4.4.2 that resulted in 7324 FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT_EXT if a single 7325 image was attached more than once to a framebuffer object. 7326 7327 FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT_EXT 0x8CD8 7328 7329 * A single image is not attached more than once to the 7330 framebuffer object. 7331 7332 { FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT_EXT } 7333 7334 This rule was removed in version #117 of the 7335 EXT_framebuffer_object specification after discussion at the 7336 September 2005 ARB meeting. The rule essentially required an 7337 O(n*lg(n)) search. Some implementations would not need to do that 7338 search if the completeness rules did not require it. Instead, 7339 language was added to section 4.10 which says the values 7340 written to the framebuffer are undefined when this rule is 7341 violated. 7342 7343Revision History 7344 #123, October 6, 2016: Jon Leech 7345 - Remove STENCIL_REF from list of state moved to become framebuffer 7346 dependent (Bug 8422). 7347 #122, May 3, 2016: Kevin Rogvin, James Jones 7348 - Specify behaviour of mixing EXT and ARB_framebuffer_object / 7349 OpenGL 3.0 framebuffer objects so that the aliases of the 7350 functions are correctly observed (Bug 1485) 7351 #121, September 23, 2013: Jon Leech 7352 - Specify that undefined behavior results when mixing EXT and 7353 ARB_framebuffer_object / OpenGL 3.0 API framebuffer objects 7354 (Bug 10738). 7355 #120, April 22, 2008: Jeremy Sandmel & Jon Leech 7356 - Update errors section so detaching renderbuffers and textures 7357 using object name zero is not an error. 7358 #119, February 13, 2007: Jon Leech 7359 - Corrected typos in 'GenerateMipmap'. 7360 #118, April 5, 2006: jjuliano 7361 - Improve language related to which formats are 7362 color-renderable, and describe format conversions when reading 7363 from and writing to the framebuffer. Lays groundwork for 7364 making additional formats color-renderable. 7365 - Add section 4.4.6. 7366 - Selecting same attachment multiple times via DRAW_BUFFERs 7367 writes undefined value to the buffer. 7368 - Clarify effect of framebuffer completeness on values of state 7369 table 9.nnn. 7370 - Describe interaction with NV_float_buffer and 7371 NV_texture_shader. 7372 #117, September 26, 2005: jjuliano 7373 - Remove FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT_EXT. 7374 - Add language to section 4.10 explaining that duplicate 7375 attachments result in undefined behavior 7376 - Add issue (87) to discuss the change. 7377 - List EXT_packed_depth_stencil as affecting this extension. 7378 7379 #116, September 16, 2005: jjuliano 7380 - Add example (8) demonstrating FBO + ARB_draw_buffers. 7381 - Add issue (85) discussing window and FBO of different sizes. 7382 - Add issue (86) about one- and two- component texture formats. 7383 - State that OpenGL 1.1 is required. 7384 7385 #115, July 25, 2005: jjuliano 7386 - Improve wording around ReadPixels of color data while 7387 READ_BUFFER is NONE. (INVALID_OPERATION). Clarify that it is 7388 legal to read depth/stencil while READ_BUFFER is NONE. 7389 - In section 4.4.4.2 (Framebuffer Completeness), clarify that 7390 READ_BUFFER can be NONE, and if NONE then framebuffer 7391 completeness does not require a color attachment. 7392 7393 #114, June 16, 2005: jjuliano 7394 - Eliminate the name STENCIL_INDEX_EXT. The name STENCIL_INDEX 7395 is already defined in the core specification. 7396 - Add some missing errors to the errors section. 7397 - Add _ARB suffix to TEXTURE_RECTANGLE, and describe interactions 7398 with ARB_texture_rectangle. 7399 - In errors section, say that it is an error if cube map texture 7400 passed to GenerateMipmapEXT is not cube complete. 7401 7402 #113, May 27, 2005: jsandmel, jjuliano, chris niederauer, alex eddy, barthold lichtenbelt 7403 - improved langage and added some tables (10.nnn and 11.nnn) in 7404 another attempt to clarify the DrawBuffer(s)/ReadBuffer error 7405 semantics 7406 - added additional errors to the summary at the end 7407 - fixed typo in FramebufferTexture3D where <zoffset> was 7408 compared against MAX_3D_TEXTURE_SIZE and should have been 7409 compared against (MAX_3D_TEXTURE_SIZE - 1). 7410 - note that issue (21) is a duplicate of issue (77) and 7411 mark issue (21)'s resolution with a reference to issue (77) 7412 - the resolution of issue (75) indicated that STENCIL_REF is now 7413 dependent on the current framebuffer state, but STENCIL_REF 7414 was inadvertantly left off of table 9.nnn 7415 - fixed the bullet item in section 4.4.1 that stated that when bound to 7416 an application-created framebufer, the value of SAMPLES is 1. 7417 it should have said 0. 7418 - added missing queries of renderbuffer bit depths that were 7419 inadvertantly left out of the spec. 7420 7421 #112, April 28, 2005: jsandmel, jjuliano, chris niederauer 7422 - updated contributors list 7423 - Improve language pertaining to "render to texture source" loop. 7424 - Fixed typo where CheckFramebufferStatusEXT was accidentally 7425 listed twice in additions to chapter 5's list of 7426 non-display-listed commands 7427 - fixed typo in prototype conventions 7428 - as per workgroup meeting decision on April 4, 2005, 7429 DrawBuffer(s) and ReadBuffer no longer generate an error when 7430 specifying an attachment point for which there is no image 7431 attached. The rationale is that the user can always attach 7432 (or detach) after DrawBuffer(s)/ReadBuffer is called anyway. 7433 We retain the test in CheckFramebufferStatusEXT that makes 7434 sure the buffers are attached prior to rendering, however. 7435 - as per workgroup email list discussions April 20, 2005, added 7436 BindFramebuffer/BindRenderbuffer to the list of 7437 display-listable functions. They were inadvertantly left off 7438 the list. Adding them back to be consistent with resolution 7439 of issue (80). 7440 - added missing language to FramebufferTexture discussion to 7441 correct section where we compared width/height/level values to 7442 MAX_TEXTURE_SIZE instead of MAX_CUBE_MAP_TEXTURE_SIZE for cube 7443 maps attached to framebuffer. 7444 - as per workgroup meeting decision on April 26, 2005, 7445 CheckFramebufferStatusEXT will generate an error if called 7446 within a Begin/End pair, since it is (intentionally) not 7447 listed in the exclusion list for functions that can be called 7448 within Begin/End in section 2.6.3 7449 - as per workgroup meeting decision on April 26, 2005, since 7450 section 2.6.3 states that routines that return a value should 7451 return 0 if the routine generates an error, 7452 CheckFramebufferStatusEXT should return zero and not 7453 FRAMEBUFFER_STATUS_ERROR_EXT. Since we don't need 7454 FRAMEBUFFER_STATUS_ERROR_EXT anymore, we are removing this 7455 enum from the spec. 7456 - added missing error language to spec body and fixed incorrect 7457 language in "Errors" section to clarify that specifying enums 7458 to DrawBuffer(s) and ReadBuffer that are NEVER legal is an 7459 INVALID_ENUM, while specifying values that only illegal 7460 because of the current framebuffer binding are an 7461 INVALID_OPERATION. 7462 - Fix minor typos in DrawBuffer(s) and ReadBuffer definitions. 7463 7464 #111, February 28, 2005: jjuliano, jsandmel 7465 - Add example 7 illustrating "depth-only" framebuffer object. 7466 7467 #110, February 28, 2005: jsandmel, jjuliano, brian paul 7468 - no functional changes 7469 - integrated Brian Paul's fixes for typos and noted 7470 that invalid operation is generated if the <textarget> 7471 and type of texture don't match in FramebufferTexture 7472 - default internalformat for renderbuffer is RGBA not "1" since 7473 "1" is not a legal internalformat for renderbuffers 7474 - note that the unsinged base internal formats of RGB, RGBA, 7475 DEPTH_COMPONENT, and STENCIL_INDEX are legal internal formats 7476 for renderbuffers. They were intended to be legal all along 7477 but the language indicated otherwise. 7478 7479 #109, January 31, 2005: jsandmel, jjuliano 7480 - added language to issue (48) to indidcate that 7481 CheckFramebufferStatus will return an undefined result for a 7482 framebuffer in the intial state since a framebuffer in the 7483 initial state violates multiple completeness rules 7484 7485 #108, January 31, 2005: jjuliano 7486 - fix typos pointed out by various people (thanks) 7487 7488 #107, January 17, 2005: jjuliano, jsandmel 7489 - fix resolution of issue (28) to say "zoffset", not "image" 7490 - more cleanup of issue resolutions 7491 7492 #106, January 17, 2005: jjuliano 7493 - per working group decision, clean up issue resolutions 7494 - minor whitespace and punctuation cleanup 7495 7496 #105, January 17, 2005: jjuliano 7497 - add XXX documenting "undefined-ness" of rendering 7498 vs. texturing 7499 - minor language clarification and typo fix 7500 7501 #104, January 14, 2005: jjuliano, jsandmel 7502 - white space clean up (plus a few capitalizations) 7503 - no functional changes in this revision 7504 7505 #103, January 14, 2005: jjuliano, jsandmel, barthold lichtenbelt, jon leech 7506 - add missing "NONE" case to DrawBuffer language 7507 - permit ReadBuffer(NONE) for application-created framebuffers 7508 - spec body: actually state that DrawPixels, ReadPixels, 7509 CopyPixels, and derivatives of CopyPixels all generate 7510 INVALID_FRAMEBUFFER_OPERATION_EXT if called while framebuffer 7511 is not complete 7512 - clarify error semantics for DrawBuffer(s) when there is no 7513 image attached to the framebuffer attachment point named by 7514 DrawBuffer(s) 7515 - improve error language regarding the <level> parameter of 7516 FramebufferTexture 7517 - State that table 4.nnn is part of the per-framebuffer-object 7518 state vector 7519 - Delete dangling references to table 3.nnn 7520 - In section 4.4.4.2, adjust wording to understand that 7521 DeleteTextures deletes an object, not image 7522 - Convert some left-over window-system-* to 7523 window-system-provided 7524 - Adjust some whitespace and punctuation 7525 - renumbered tables to remove the hole now that the old table of 7526 CheckFramebufferStatus enums has been deleted. 7527 - incorporate remainder of barthold's edits removing more 7528 "framebuffer-attachble" references from the issues list 7529 - moved comment describing the purpose of the 7530 CheckFramebufferStatus enums in the framebuffer completeness 7531 test closer to their initial use in the spec. 7532 - Eliminate two XXX comments that addressed by this revision 7533 7534 #102, January 13, 2005: jjuliano, jsandmel, barthold lichtenbelt, jon leech 7535 - replacement of "renderable image" with "framebuffer-attachable 7536 image" 7537 - removed lots of (now redundant) instances of 7538 "framebuffer-attachable" 7539 - streamlined the grammar in several places to account for 7540 "framebuffer-attachable" change 7541 - incorporated outstanding edits from barthold's review of #73 7542 and #98 7543 - made FramebufferTexture and FramebufferRenderbuffer use "uint" 7544 for texture and renderbuffer names for consistency with 7545 Gen/Is/Bind/Delete. For some reason, in revision #77 we 7546 had incorrectly changed these from uint to ints. 7547 - renamed FRAMEBUFFER_INCOMPLETE_MULTIPLE_ATTACHMENT to 7548 FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT 7549 - fixed DeleteTextures and DeleteRenderbuffers language to 7550 reflect resolution of issue (77), by adding forward reference 7551 to the section that describes attachment (that already had 7552 that right language). 7553 - fixed the different language in FramebufferRenderbuffer and 7554 FramebufferTexture that described the state when binding a 7555 zero object (dropped the reference to object type of NONE 7556 since that *is* the default and it already said the state was 7557 set to default values) 7558 - reworked section 4.4.2 overview to simplify intro to 7559 attaching images to framebuffers 7560 - reworded intro to section 4.4.2.1 Renderbuffer Objects 7561 - fixed several instances of "render buffer" to "renderbuffer" 7562 - replaced language in framebuffer attachment routines that 7563 bounded the upper value of <level> to use the parallel 7564 language from page 185 of the OpenGL 2.0 spec. 7565 - simplified first clause of framebuffer compelteness test to 7566 just require at least one image attached to framebuffer 7567 - reordered CheckFramebufferStatusEXT section and moved 7568 description of FRAMEBUFFER_UNSUPPORTED_EXT to be part of 7569 framebuffer completeness section description 7570 - deleted table 3.nnn which lsted the return values of 7571 CheckFramebufferStatusEXT since this info is already included 7572 in the framebuffer completeness test itself and was really 7573 just a duplicate copy in table form. 7574 - added several errors which were missing from the error summary 7575 at the end of the spec 7576 7577 #101, January 12, 2005: jjuliano, jsandmel 7578 - Clarify language related to BindRenderbuffer(<target>, 0) 7579 - Small grammatical change related to object vs. object's image. 7580 7581 #100, January 11, 2005: jsandmel, jjuliano 7582 - added new enums and clauses to framebuffer completeness test 7583 to catch mutliple and missing attachements 7584 - reshuffled existing enums to account for new enums 7585 - clarified issue (84) it indicate that the intent is to mimic 7586 the pbuffer orientation style 7587 7588 #99, January 11, 2005: jsandmel, jjuliano 7589 - use more expelict language mapping window coordinates to 7590 texture image texels at the end of section 4.4.2.3 7591 - fixed typos 7592 - coalesced interactions with AGL/GLX/WGL with interactions with 7593 WGL/GLX_make_current_read extensions 7594 - addressed and removed some more remaining XXX comments 7595 - added note to issue (58) saying that {Copy}TexSubImage 7596 uses negative offsets to address border texels 7597 - added issue (84) - do we need any language describing 7598 orientation of renderable images? (I.e., are they y-inverted?) 7599 7600 #98, January 7, 2005: jsandmel 7601 - remove more outstanding XXX comments 7602 - updated section 4.4 to better define applicatino-created and 7603 window-system-provided framebuffers in the overview of 7604 framebuffer objects 7605 - further clarifications to issue (49) concerning MRT support 7606 - removed stale XXX comment from issue (75) about stencil mask 7607 language 7608 7609 #97, January 7, 2005: jjuliano 7610 - Resolve some XXX comments, by adding missing spec language and 7611 clarifying existing spec language. 7612 7613 #96, January 6, 2005: jjuliano, ian romanick 7614 - renumbered sections to reflect earlier removal of the section 7615 on renderable image completeness. 7616 - fixed prototype of CheckFramebufferStatusEXT in spec (bool->enum) 7617 7618 #95, January 6, 2005: jsandmel, jjuliano 7619 - added missing change notes from #94 7620 - fixed more typos 7621 - updated issue (48) - it had been resolved already but need 7622 some updated some language from the resolution to reflect our 7623 final decision 7624 - marked issue (55) as resolved (it had been resolved a while 7625 ago but was left as unresolved) 7626 - resolved issue (82) - bind vs. attach. final spec 7627 implications may get updated when we resolved the larger ARB 7628 discussions over multicontext behavior and object sharing 7629 7630 #94, January 4, 2005: jjuliano 7631 - language clarification and word smithing. 7632 - note that rendering to the border of a texture uses 7633 an origin within the border texels 7634 - updated comments in sample code for clarity 7635 - updated issue (16) to clarify how CopyTexImage possibly 7636 affects framebuffer completeness, and simplified remaining 7637 language 7638 - updated issue (77) to better capture the effects of 7639 deleting attached renderable images 7640 - updated issue (79) to better capture the invariance of 7641 renderable image internal format selection 7642 - added additional clarifications to issue (83) to describe how 7643 an explicit enable/disable API would work 7644 7645 7646 #93, December 23, 2004: jsandmel 7647 - improved stencil ref value clamping language yet again to 7648 indicate that queries are clamped 7649 - moved old XXX comment about an explicit enable into a new 7650 resolved issue (83) 7651 - removed a condition of framebuffer attachment completness 7652 concerning the legality of the LEVEL param which I 7653 overzealously added in revision #92 7654 - resolved issue (77) - images are detached from current 7655 framebuffer only, user must do manual detachment for 7656 non current framebuffers 7657 - clarified issue (79) to note that GL need not choose the same 7658 format for both renderbuffers and textures as the text seemed 7659 to imply before. 7660 - clarified issue (16) to note that state changes to non-bound 7661 framebuffers are somewhat similar to state changes made by 7662 another context to shared objects (possibly) bound by this 7663 context. 7664 - clarified resolution of issues (15) and (16) which talk about 7665 how {Copy}TexImage into textures affect the framebuffers to 7666 which textures are attached. 7667 7668 #92, December 23, 2004: jsandmel 7669 - updated "Dependencies" section to add descriptions for 7670 interactions with other extensions 7671 - fixed a stale reference to "accum" in overview 7672 - improved language in overview that seemed to imply that 7673 this extension required a data copy to do render to texture 7674 - removed stale XXX comment about framebuffer sharing since 7675 issue (76) is resolved 7676 - added proposed language for "attach" definition in glossary 7677 - removed stale glossary entry for "renderable image completeness" 7678 now that issue (78) is resolved 7679 - Updated chapter 2 to use proposed language changes describing 7680 interactions with the framebuffer in the context of this 7681 extension. 7682 - clarified that GenerateMipmap only requires cubemap textures 7683 to be cubemap complete 7684 - removed unnecessary reference to proxy texture in GenerateMipmap 7685 - clarified language about stencil ref value clamping 7686 - removed various other stale XXX comments 7687 - added note that RENDERBUFFER_BINDING_EXT can be queried 7688 - included alternate beahviors in language influenced by issue 7689 (77) 7690 - defined the error that occurs on FramebufferTexture when 7691 a level is specified that is too big 7692 - added requirement to framebuffer attachment completeness 7693 that FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_EXT must be 7694 less than q for symmetry with the requirement that the 7695 z-offset is smaller than the depth of the texture 7696 - added section numbers to state tables 7697 - indicated there are no attribute bits for the state tables 7698 - added proposed language for issue (82) 7699 - added proposed language for issue (77) 7700 7701 #91, December 22, 2004: jsandmel 7702 - added updated stencil language to reflect resolution of 7703 issue (75) - stencil ref value and writemask clamping 7704 - added language to section 4.4.2.1 indicating that internal 7705 format selection for renderbuffers follows the same invariance 7706 rules as textures 7707 - updated framebuffer completeness language to reflect resolution 7708 of sissue (78) 7709 - added test to framebuffer attachment completeness indicating 7710 that the z-offset identifying an image within a 3D texture must 7711 be less than the texture's depth 7712 - added routines to list of non-display-list'able routines 7713 as per resolution of issue (80) 7714 - deleted note about OpenGL ES in issue (76) 7715 - cleaned up the proposed language for issue (77) based on 7716 feedback from Jeff Juliano 7717 7718 #90, December 22, 2004: jsandmel 7719 - removed plural from FRAMEBUFFER_INCOMPLETE_ATTACHMENT[S] 7720 - added FRAMEBUFFER_STATUS_ERROR_EXT to enumerants list 7721 - resolved issue (78) - collapsing "renderable image 7722 completeness" test and removed FRAMEBUFFER_INCOMPLETE_IMAGES 7723 enum as per meeting Dec. 21, 2004 7724 - fixed up some typos 7725 - wrote up and resolved issue (76) - framebuffers are shared 7726 like textures as per meeting Dec. 21, 2004 7727 - wrote up issue (77) - detachment on deletion 7728 - wrote up and resolved issue (79) - textures are invariant 7729 with respect to framebuffer state 7730 - wrote up and resolved issue (80) - no routines in this 7731 extension are display-list'able 7732 - wrote up and deferred issue (81) - push/pop attrib 7733 - added issue (82) - bind vs. attach defintions 7734 7735 #89, December 16, 2004: jjuliano, jsandmel, ian romanick 7736 - added glx protocol for this extension 7737 - added issue (75) - stencil ref value and write mask state 7738 - added issue (76) - sharing framebuffer objects 7739 - added issue (77) - deletes affect on detaching images 7740 - added issue (78) - collapsing "completeness" tests 7741 7742 #88, December 06, 2004: jjuliano, jsandmel 7743 - revised examples again for clarity, added example (6) to show 7744 one way to handle CheckFramebufferStatusEXT 7745 7746 #87, December 03, 2004: jjuliano, jsandmel 7747 - incorporated language edit feedback from john rosasco 7748 - changed a few instances of "rendering to texture" to "render 7749 to texture" 7750 - added XXX notes about sections that still need cleanup 7751 - clarified definition of renderbuffer and its image in overview 7752 - clarified comparison of MakeCurrent and BindFramebuffer in 7753 overview 7754 - fixed misc typos 7755 - renamed TEXTURE_ZOFFSET to TEXTURE_3D_ZOFFSET for consistency 7756 with TEXTURE_CUBE_MAP_FACE 7757 - added note to update section 2.1 to talk about configuring 7758 framebuffer (need forward reference to chapeter 4). 7759 - changed several instances "the GL is using ... framebuffer" to 7760 "the GL is bound to ... framebuffer" 7761 - changed several instances of "When [A], if [B], [C]" into "If 7762 [A] and [B], then [C]" 7763 7764 #86, December 02, 2004: jon leech 7765 - assigned "real" enum values 7766 - fixed some minor typos 7767 7768 #85, December 01, 2004: jjuliano, jsandmel 7769 - Improve error checking in examples 7770 - whitespace cleanup 7771 7772 #84, December 01, 2004: jjuliano 7773 - DrawBuffer(s) while bound to user-created framebuffer object 7774 generates an error if the named color attachment does not have 7775 have anything attached to it when DrawBuffer is invoked. 7776 - Likewise for ReadBuffer. 7777 7778 #83, November 30, 2004: jjuliano 7779 - improve wording of issue (28) - zoffset vs image of a 7780 3-dimensional texture 7781 - update examples to use the new attach target enums, and 7782 to check framebuffer status 7783 7784 #82, November 30, 2004: jsandmel 7785 - renumbered tables to start with 1.nnn instead of 2.nnn 7786 - resolved issue (74) - return value of CheckFramebufferStatus() 7787 - re-opened and re-resolved issue (28) - zoffset vs image of a 7788 3d texture 7789 - fixed reference of CopyTexImage to CopyTexSubImage in intro 7790 - added 16 enums for COLOR_ATTACHMENTn_EXT as per meeting 7791 november 29, 2004 7792 - clarified language about number of attachment points in 7793 description of BindFramebufferEXT(). 7794 7795 #81, November 30, 2004: jsandmel 7796 - re-added *-renderable clause to "renderable image completeness" 7797 test. 7798 - clarified language in intro that describes selecting an 7799 image from a texture 7800 - fixed a few more typos 7801 7802 #80, November 30, 2004: jjuliano 7803 - Improve definition of CheckFramebufferStatusEXT. 7804 FRAMEBUFFER_STATUS_ERROR_EXT is returned if <target> is 7805 invalid. Framebuffer zero always produces 7806 FRAMEBUFFER_COMPLETE_EXT. 7807 - Rename 3D_IMAGE to ZOFFSET. More consistent with 7808 CopyTex(Sub)Image. 7809 - In definition of GetFramebufferAttachmentParameterivEXT, 7810 explain that zero is returned when face or zoffset is queried, 7811 but texture is not cube map or 3-dimensional, resp. This 7812 matches the informal description in issue (51). 7813 - Eliminate table 1.nnn, and modify references to instead 7814 reference table 6.nnn. I have not renumbered all the tables 7815 yet, so that the diffs are more obvious. Renumbering can 7816 happen in the next change. 7817 - Eliminate *-renderable clause from Renderable Image 7818 Completeness. This is already covered under Framebuffer 7819 Attachment Completeness. 7820 - For each clause in Framebuffer Completeness, add references to 7821 specific error generated when that clause is violated. 7822 7823 #79, November 23, 2004: jsandmel, jjuliano 7824 - more typos fixed 7825 - added placeholder enumeration of all tables so that every 7826 table was not named XXX.XXX. They are now named M.nnn where M 7827 is incremented sequentially for each table. 7828 - stated that order of return of CheckFramebufferStatus enums is 7829 "implementatino-dependent" instead of "undefined" 7830 - added state table for framebuffer object state (as opposed to 7831 table of framebuffer attachment point state), added 7832 DRAW_BUFFERi and READ_BUFFER state to this table. 7833 7834 #78, November 22, 2004: jsandmel 7835 - re-opened and re-resolved issue (4) - renamed 7836 "renderable-images" to "framebuffer-attachable images" 7837 - resolved issue (70) - defer support of framebuffer binding 7838 push/pop semantics 7839 7840 #77, November 22, 2004: jsandmel, jjuliano 7841 - fixed up typos and address other issues found by Barthold 7842 - changed errors of GetFramebufferAttachmentParameterivEXT 7843 to be INVALID_ENUM instead of INVALID_VALUE where appropriate 7844 - added missing INVALID_ENUM GetRenderbufferParameterivEXT error 7845 case to list of errors 7846 - dropped framebuffer status state from state table (The reason 7847 is: technically this is not state queriable with a standard 7848 Get call and doesn't really need to be stored, an 7849 implementation could calculate this result on the fly in 7850 principle.) 7851 - added issue (74) - what does it mean to call 7852 CheckFramebufferStatusEXT on framebuffer zero (default 7853 framebuffer) and what if CheckFramebufferStatusEXT generates 7854 an error? 7855 - cleaned up a bunch more "window-system-provided" references 7856 - changed a bunch of "bit plane" references --> "bitplane" 7857 - more updates to glossary section (not complete yet) 7858 - Added boolean return values to IsRenderbuffer and 7859 IsFramebuffer prototypes 7860 - Changed object id's in FramebufferTexture* and 7861 FramebufferRenderbuffer from uint to int to be consistent with 7862 texture routines. 7863 - changed typo in Get*Parameter routines: "param" --> "params" 7864 - added missing COLOR_ATTACHMENTn_EXT enums to new tokens list 7865 - clarified difference and similarities between automatic and 7866 manual mipmap generation in section 3.8.8 7867 - added lots of missing EXT's 7868 - clarified use of <textarget> in FramebufferTexture when 7869 <texture> is zero and <renderbuffer> target in 7870 FramebufferRenderbuffer when <renderbuffer> is zero. 7871 (<textarget> and <renderbuffertarget> are ignored in this case> 7872 - added a sentence defining that order of return for enums in 7873 CheckFramebufferStatusEXT is undefined if multiple clauses of 7874 framebuffer completeness test fail 7875 7876 #76, November 19, 2004: jsandmel 7877 - as per group meeting Nov. 19, 2004, rename "render buffer" to 7878 "renderbuffer". This is the only substantive change in this 7879 revision. Unfortunately, this had a lot of white-space 7880 collateral damage. Also, this reopens and closes issue (3). 7881 7882 #75, November 18, 2004: jsandmel 7883 - added missing enums to New Tokens section 7884 - clarified wgl/agl/glx language additions section to note that 7885 the window-system draw/read drawables are ignored when bound 7886 to an application-created framebuffer object 7887 - resolved issue (69) - "application-create" framebuffers 7888 - added more description of issue (70) - push/pop binding bits? 7889 - resolved issue (71) - defining which draw/reading routines can 7890 throw errors 7891 - resolve issue (72) - require at least one color, depth, or 7892 stencil attachment 7893 - resolved issue (73) - allow READ_BUFFER to be none so 7894 user can read from a non-color buffer in a framebuffer 7895 with no color attachments 7896 - added section on ReadBuffer whose absence had unfortunately 7897 gone unnoticed until now. 7898 - added missing "initial state" language for draw buffer to 7899 section 4.2 7900 - cleaned up several references to FRAMEBUFFER_EXT that should 7901 have been either "the target FRAMEBUFFER_EXT" or 7902 "FRAMEBUFFER_BINDING_EXT" 7903 7904 #74, November 18, 2004: jsandmel, jjuliano 7905 - fixed up typos found by Ian Romanick 7906 - changed several instances of "GL-allocated framebuffer" to 7907 "application-created framebuffer" for consistency. 7908 NOTE: However, we might want to pick a new term for these 7909 everywhere. Added issue (69) for this. 7910 - added a MAX_RENDERBUFFER_SIZE_EXT implementation constant 7911 to catch errors to RenderbufferStorageEXT. 7912 - added issue (70), (71), (72), (73) for issues found 7913 by Jeff 7914 7915 #73, November 15, 2004: jsandmel 7916 - split out CheckFramebufferStatus enums as per work group 7917 meeting November 15, 2004 7918 - added note to self to go back and clean up issue (48) 7919 7920 #72, November 15, 2004: jsandmel 7921 - added "valid draw/read buffer" test to framebuffer 7922 completeness test as per resolution of issue (55) as per 7923 meeting on November 11, 2004. 7924 - added new enums to CheckFramebufferStatus for each of the 7925 implementation-independent failure cases as per resolution of 7926 issue (55) as per meeting on November 11, 2004. 7927 (these may be placeholder names for now) 7928 - added additional partial resolutions to issue (55) as 7929 per meeting on November 11, 2004 7930 - added XXX note to update state tables with whatever the 7931 final final resolution of the DRAW_BUFFER location is. 7932 7933 #71, November 9, 2004: jsandmel 7934 - cleaned up contributors list 7935 - resolved issue (61) on minimum requirements as per work group 7936 meeting on November 6, 2004 7937 - added partial resolution and additional description to 7938 issue (55) as per meeting on November 8, 2004 7939 7940 #70, November 2, 2004: jsandmel, jjuliano 7941 - clarified opening language of chapter 4 to name non-visible 7942 buffers 7943 - improved language about when the number of bits in a bitplane 7944 can change 7945 - removed "SUBPIXEL_BITS" from table of state that can change 7946 on framebuffer state change as per working group 7947 meeting November 1, 2004 and marked issue (62) as resolved 7948 - marked issue (56) - draw buffer state location as framebuffer 7949 object state as per working group meeting November 1, 2004 7950 7951 #69, November 1, 2004: jsandmel 7952 - added placeholder "min requirements" text to issue (61) 7953 - marked issue (68) as resolved since it was resolved during 7954 week of Oct 18, 2004. 7955 - incorporated feedback from Brian Paul on various typos, 7956 prototype mismatches, missing "EXT"s, and missing 7957 IsRenderbuffer language (to chapter 6) 7958 - added missing IsFramebufferLanguage to chapter 6 7959 7960 #68, October 29, 2004: jjuliano, jsandmel 7961 - additional clarifications to opening of chapter 4 7962 - various other minor word substitutions 7963 7964 #67, October 28, 2004: jjuliano 7965 - additional clarifications to issue (56) 7966 7967 #66, October 27, 2004: jsandmel 7968 - added most (all?) of the necessary state tables to the end of 7969 the spec (also removed old state table notation) 7970 - made references to the state tables as 6.3XX until we know the 7971 final table numbering 7972 - fleshed out the language of the intro to chapter 4 describing 7973 the color logical buffers and attachable color buffers 7974 - at the beginning of chapter 4, modified core spec language to 7975 note that the bitplane depths are no longer fixed 7976 - moved XXX note about invariance to end of start of chapter 4 7977 - slightly reworded description of FRAMEBUFFER_UNSUPPORTED_EXT 7978 - moved table of "framebuffer dependent state variables" 7979 from spec body into state tables at end of spec 7980 - added most (all?) of the known errors to the "Errors" 7981 section of the spec. 7982 7983 #65, October 25, 2004: jsandmel 7984 - changes to resolve issue (67) - ValidateFramebuffer is now 7985 called CheckFramebufferStatus(). 7986 - updated section 4.2.1 to include DrawBuffers (plural) language 7987 from OpenGL 2.0 spec. Note: we either need to update whole 7988 spec to be based on OpenGL 2.0 spec, or else revise the 7989 DrawBuffer(s) language to refer to the ARB_draw_buffers 7990 extension sepc language. 7991 - added (possibly temp) reference to errors on ReadPixels when 7992 using an incomplete framebuffer 7993 - added note to section 4.4.1 that describes pixel ownership 7994 test success when using application-created framebuffers 7995 - added table of enum values returned from 7996 CheckFramebufferStatus() as per resolution of issue (48) 7997 - resolved issue (65) - name of error on incomplete framebuffer 7998 operations 7999 - clarified that issue (24) is really a duplicate of (64). 8000 - resolved issue (48) 8001 - added note to write up issue (61) language for review 8002 8003 #64, October 19, 2004: jsandmel, jjuliano 8004 - more rewording and clarifications of issue (56) 8005 8006 #63, October 15, 2004: jjuliano 8007 - more rewording and clarifications of issue (55) and (56) 8008 8009 #62, October 14, 2004: jsandmel 8010 - more rewording and clarifications of issue (55) and (56) 8011 8012 #61, October 13, 2004: jjuliano 8013 - Dramatically reword issues (55) and (56). 8014 - Add issue (68) addressing which levels are generated by 8015 GenerateMipmapEXT 8016 8017 #60, October 11, 2004: jsandmel 8018 - revised write up of issue (56) to capture recent work group 8019 discussions about draw buffer state location 8020 - resolved issue (48) as per work group meeting Oct. 11, 2004 8021 8022 #59, October 11, 2004: jjuliano 8023 - added note about possibly wanting to have explicit enable for 8024 framebuffer objects instead of using zero in section 4.2.1 8025 - cleaned up list of differences between framebuffer object and 8026 default framebuffer 8027 - separated out attach/detach cases in list of diffs between 8028 default framebuffer and framebuffer objects 8029 - added reminder note about invariance clause modifications 8030 for section 4.4.5 8031 - added reminder note about modifications for wgl spec 8032 - cleaned up language in issue (26) about reading from 8033 incomplete framebuffer 8034 - clarified resolution of issue (44) - texture from destination 8035 - replaced various instances of framebuffer "invalid" with 8036 framebuffer "incomplete" 8037 - other misc. typos, white space clean up 8038 8039 #58, October 8, 2004: jsandmel, jjuliano 8040 - reopened and resolved issue (26) - incomplete framebuffer 8041 read is an error? 8042 - reopened, updated, and resolved issue (44) - "texture from 8043 destination" is undefined 8044 - marked issue (50) as resolved, since it basically was 8045 - updated and resolved issue (64) - incomplete framebuffer 8046 rendering is an error? 8047 - tentatively resolved issue (65) - name of error when 8048 trying to use an incomplete error 8049 - resolved issue (66) - clarified what state can 8050 cause framebuffer incompleteness 8051 - created issue (67) - name of ValidateFramebuffer 8052 - implemented preliminary draw buffer language in section 4.2.1 8053 - added more language in section 4.4.1 to describe differences 8054 between window-system and application-created framebuffers 8055 - updated "texture-from-destination" language in section 4.4.3 8056 to reflect new resolution of issue (44). 8057 - removed clause describing "texture from destination" 8058 constraints from framebuffer completeness test in section 8059 4.4.4.1 to reflect resolution of issue (44). 8060 - added list of operations which can change framebuffer 8061 completeness to section 4.4.4.2 8062 - Added language to section 4.4.4.3 indicating that rendering to 8063 or reading from an incomplete framebuffer is an error, as per 8064 resolution of issue (64) and (26) 8065 - Added more description of implementation dependent state which 8066 can change in section 4.4.5 and refer to framebuffer 8067 completeness section in 4.4.4.2 to identify when this state 8068 can change 8069 - added MAX_COLOR_ATTACHMENTS to list of state variables that 8070 might change if framebuffer state changes 8071 - added error conditions to queries when framebuffer zero or 8072 renderbuffer zero is bound (since there is no framebuffer 8073 zero or renderbuffer zero). 8074 - added placeholder for Additions to the AGL/GLX/WGL 8075 Specifications 8076 - fixed up misc. typos and whitespace 8077 8078 #57, October 1, 2004: jjuliano 8079 - added additional discussion in issue (66) 8080 - fixed up misc. typos and whitespace 8081 8082 #56, September 29, 2004: jsandmel 8083 - added additional option (d) to issue (66) as per our work 8084 group discussions on Sept 30, 2004. 8085 8086 #55, September 29, 2004: jsandmel 8087 - added meta-issue (66) which deals with framebuffer 8088 completeness dependencies on the context state. 8089 - added section 4.4.5 about state variables which may change if 8090 framebuffer state changes. 8091 - dropped some redundant exposition in issue (55) 8092 - resolved issue (60) and wrote up the description of the issue 8093 - removed ACCUM_FORMAT from list of new enums per resolution of 8094 issue (40) 8095 8096 #54, September 27, 2004: jsandmel 8097 - added issue (64) - error to render with incomplete framebuffer? 8098 - added issue (65) - what should the error be? 8099 - added note to ask if we need to reopen (26) about reading 8100 from invalid framebuffer in light of resolution of (64). 8101 8102 #53, September 17, 2004: jsandmel 8103 - updated "attach" definition in glossary 8104 - fixed up some minor typos, whitespace issues 8105 - in issue (15)/(16) indicate tex state changes can affect 8106 framebuffer completeness, not just cause it to fail (they 8107 might cause it to succeed). 8108 - add clarification about the type of intrinsic buffers that 8109 were removed in issue (36) 8110 - updated language describing use of ACCUM format for textures 8111 in issue (40) 8112 - reworded reference to "billboarding" in issue (42) 8113 - clarified the draw buffer(s) issue (55) to indicate 8114 possible problems even after DrawBuffer(s) is called. 8115 - pacified some of the language surrounding issue (63) and the 8116 rationale for using ValidateFramebuffer or a GetInteger style 8117 query. 8118 8119 #52, September 17, 2004: jjuliano 8120 - edits based on review of a subset of the issues section 8121 - edits to the diffs from version #51 8122 - added note to overview comparing render-to-texture to 8123 CopyTexImage 8124 - added "attach" term to glossary section 8125 - replaced ARB's with EXT's in issue (1) 8126 - distinguished between bind and attach in isuse (5) 8127 - various replacements of "texture" with "texture image" 8128 - various replacements of "framebufer (in)valid" language with 8129 framebuffer (in)completeness language 8130 - added additional rationale to issue (18) about framebuffer 8131 renderable image attachment 8132 - clarified issue (27) that the resolution is no error is 8133 generated 8134 - added note to issue (40) that we might want to use ACCUM 8135 format for textures 8136 - added description of complications with having draw and read 8137 framebuffer targets in issue (42) 8138 - added additional language describing issue (63) concerning the 8139 reasons for using ValidateFramebuffer versus the reasons for 8140 using an explicit query API for framebuffer completeness. 8141 8142 #51, September 16, 2004: jsandmel 8143 - resolved issue (26) - reading from incomplete framebuffer 8144 - clarified issue (55) - draw buffer set to non-existent buffer 8145 - added issue (63) - should we make ValidateFramebuffer a query? 8146 - marked issue (46) as resolved, since there's not much left to 8147 do except resolve the minimum requirements issue (61). 8148 8149 #50, September 16, 2004: jjuliano 8150 - edits based on version #49 diffs, as well as... 8151 - replace uses of "fail ValidateFramebuffer" with references to 8152 "framebuffer completeness" 8153 - reformat whitespace of some very long and very indented issues 8154 - remove "MERGE from some other proposed API" comments 8155 8156 #49, September 16, 2004: jsandmel 8157 - added DeleteTexture and DeleteRenderbuffers spec language to 8158 describe detaching from framebuffers first 8159 - added place holders in various places to correspond 8160 with lots of resolved issues 8161 - added stencil S format table 8162 - renamed section 4.4.3 8163 - clarified framebuffer attachment and renderable image 8164 requirements for completeness 8165 - added requirement to completeness to have all 8166 color attachments with the same format 8167 - added missing write ups for various issues (8), (9), (12) 8168 - in issue (40), clarified that accum language from 1.5 spec 8169 already covers the error behavior we need to defer accum support 8170 - in issue (41), clarified multisample language from 1.5 could 8171 cover the behavior we need to defer multisample support if we 8172 set SAMPLE_BUFFERS to 0 for non-default framebuffers 8173 8174 #48, September 15, 2004: jjuliano 8175 - edits based on review of chapter 4. 8176 8177 #47, September 15, 2004: jjuliano 8178 - edits based on review of all sections except for chapter 4, 8179 Issues. 8180 - clarified, reordered overview 8181 - added missing enums for framebuffer attachment point state 8182 queries to list of new enums 8183 - indicated that GenerateMipmap will only generate 8184 levels base through q instead of base through p 8185 8186 #46, September 15, 2004: jjuliano 8187 - move issues section to end of document. 8188 (issues section accounts for >50% of the document!) 8189 8190 #45, September 13, 2004: jsandmel, jjuliano 8191 - typos and white space updates 8192 - clarified language about the framebuffer object bound to <target> 8193 in section 4.4.4.2 8194 - clarified isssue (62) on which state can change and when 8195 8196 #44, September 13, 2004: jsandmel 8197 - resolved issue (40) accum buffers - deferred per group 8198 decision 8199 - resolved issue (41) multisample buffers - deferred per group 8200 decision 8201 - resolved issue (57) maximum attachable color buffers query per 8202 group decision 8203 - opened issue (62) which queries can change state after 8204 BindFramebuffer 8205 8206 #43, September 13, 2004: jsandmel, jjuliano 8207 - typos, cleanup 8208 - fixed up use of COLOR/AUX/DATAN to use lower n as GL spec. 8209 - clarified definitions of color/depth renderable 8210 - indicate renderable images don't have to be attached to be 8211 "renderable image complete" 8212 - replaced requirement on texture images that they simply need 8213 non-zero dimensions instead of saying they have been "defined" 8214 already 8215 8216 #42, September 13, 2004: jsandmel 8217 - updated Framebuffer validation language 8218 - added "complete" terms to glossary in overview 8219 8220 #41, September 9, 2004: jjuliano 8221 - re-add and rewrite section 4.4.4 on "Framebuffer 8222 Validation" 8223 8224 #40, September 9, 2004: jsandmel 8225 - fixed extra "GL" typos noted by Brian Paul 8226 - resolved issue (54) - color attachment names 8227 - resolved issue (58) - textures with borders 8228 - resolved issue (59) - stencil formats 8229 - added issue (61) - minimum requirements 8230 8231 #39, September 9, 2004: jsandmel, jjuliano 8232 - misc. typos and white space fixed 8233 8234 #38, September 8, 2004: jsandmel, jjuliano 8235 - clarifed section 4.4.3 to indicate that if mipmapping 8236 disabled, the framebuffer texture attachment rules are 8237 slightly different. 8238 - fleshed out multisample buffer support options for 8239 issue (41) after more discussions 8240 8241 #37, September 8, 2004: jsandmel 8242 - renamed attachment enums again to add FRAMEBUFFER_ on the 8243 front to further qualify their namespace. 8244 - updated table of attachment point state to include default 8245 values 8246 - added language to "Texturing From an Attached Renderable 8247 Image" (section 4.4.3) 8248 8249 #36, September 8, 2004: jjuliano 8250 - update chapter 3 language on mipmap generation 8251 - modify example 5 to not use depth buffer when 8252 custom-generating mipmap 8253 - add issue 60 on whether or not disabled depth attachment 8254 factors into framebuffer validity determination 8255 8256 #35, September 7, 2004: jsandmel 8257 - updated chapter 6 language on querying renderbuffer and 8258 framebuffer attachment state. 8259 - made references to "id 0" into "name zero" for easier 8260 searching and consistency with core GL spec 8261 - renamed the enums for framebuffer attachment state to add 8262 "ATTACHMENT" to each to qualify the name space of the enums. 8263 These might not be the final names. 8264 8265 #34, September 7, 2004: jsandmel, jjuliano 8266 - further clarified framebuffer attachment language 8267 - specify that attachment routines set "rest" of 8268 attachment state to default values 8269 8270 #33, September 7, 2004: jsandmel 8271 - added examples to issue (54) about framebuffer attachment names 8272 8273 #32, September 7, 2004: jsandmel 8274 - further clarified framebuffer attachment language 8275 8276 #31, September 3, 2004: jsandmel 8277 - added issue (58) about texture borders 8278 - added issue (59) about stencil internal formats 8279 - updated new tokens section to reflect recent issue resolutions 8280 - added attachment state table to section 4.4.2 8281 - added langauge describing renderbuffer and texture attachment 8282 routines 8283 8284 #30, September 3, 2004: jjuliano 8285 - more typos and white space cleanup 8286 - issue (46): make it clear that validation failure occurs 8287 because of a mismatch in dimensions, rather than size 8288 - clarified language on draw buffer error semantics in issue 8289 (55) 8290 - included more language describing issue (57) about querying 8291 for max number of attachable drawbuffers. 8292 8293 #29, September 2, 2004: jsandmel, jjuliano 8294 - typos fixed and whitespace clean up 8295 - factored issue (39) on ARB_draw_buffers into separate 8296 issues (53), (54), (55), (56), (57) 8297 - fleshed out issue (40) - on ACCUM buffers, tentatively 8298 we will support this if there is time 8299 - made a few ValidationFailures in isseu (46) more 8300 explicit 8301 - added issue (53) - indirection for ARB_draw_buffers? 8302 - added issue (54) - name of color attachment points? 8303 - added issue (55) - error behavior for DRAW_BUFFER 8304 - added issue (56) - is DRAW_BUFFER context state or framebuffer 8305 state? 8306 8307 #28, September 2, 2004: jsandmel 8308 - Improve language describing framebuffer and renderbuffer 8309 objects 8310 8311 #27, August 26, 2004: jsandmel, jjuliano 8312 - re-resolved issue (11) - we use 3 framebuffer attachment 8313 routines for textures, 1 for renderbuffers, also cleaned up 8314 the rationale language for this choice 8315 - resolved issue (30) - renderbuffer state routines take a target 8316 - resolved issue (42) - we use a single framebuffer target enum 8317 - resolved issue (43) - incomplete attached textures will 8318 not cause ValidateFramebuffer failures 8319 - resolved issue (45) - framebuffers with no color buffer attached 8320 will be allowed 8321 - deferred and expanded issue (48) - what info should 8322 ValidateFramebuffer return. 8323 - resolved issue (51) - use individual queries for attachment 8324 state 8325 - resolve issue (52) - auto and manual mipmap generation 8326 can peacefully coexist 8327 - deleted obsolete mipmap generation language from spec text 8328 as this needs to be reworked anyway 8329 8330 #26, August 26, 2004: jsandmel 8331 - corrected some depth_offset --> image terms, since that 8332 is the current resolution of issue (28), unless we reopen it. 8333 - clean up issue (11) language 8334 - moved query of attachments api sub issue from (34) to 8335 its own issue (51) 8336 - removed obsolete note on issue (44) 8337 - fleshed out another alternative attachment query API in issue 8338 (51) 8339 - created issue (52) on when auto/manual mip generation applies 8340 - began more spec language edits to mip generation and framebuffer 8341 object definition (this may be throwaway language depending 8342 on the resolution of some outstanding issues) 8343 8344 #25, August 24, 2004: jjuliano 8345 - Fill in chapter 4. 8346 - Replace some references to "logical buffer" with 8347 "renderbuffer". 8348 - Modification to issue (44). 8349 - Incorporate feedback from Eric Werness: improvements to 8350 examples. 8351 - Incorporate feedback from Jason Allen: issue (42) option D 8352 (GL_FRAMEBUFFER_EXT), and removal of FramebufferBuf. 8353 8354 #24, August 23, 2004: jjuliano 8355 - First stab at text for additions to chapters 2, 3, and 5. 8356 - Fill in examples 1-5. 8357 - Add description of GetFramebufferBufferParametervEXT to 8358 chapter 6. 8359 - Add EXT suffix in some places it was missing. 8360 8361 #23, August 20, 2004: jjuliano 8362 - fix minor typos 8363 - added additional comments regarding reopened issue (11) 8364 - changed some references from z-slice to depth offset 8365 8366 #22, August 19, 2004: jsandmel 8367 - reopened and expanded the options for issue (11) about one vs 8368 many FramebufferTexture attachment routines 8369 - clarified issue (16) does not imply that texture/renderbuffer 8370 state updates are delayed on attached renderable images 8371 - clarified issue (21) to not specifically imply that a call 8372 to BindFramebuffer is required to delete a renderable image 8373 attached to a framebuffer. 8374 - resolved issue (28) "slices" are now referred to as "images" 8375 - resolved issue (29) - GenerateMipmap is included in this 8376 extension 8377 - added and resolved issue (49) - MRT of different formats are 8378 not supported 8379 - added issue (50) - meta issue about whether async generation 8380 of GL errors should be avoided in this api. 8381 8382 #21, August 19, 2004: jsandmel 8383 - incorporated feedback from Barthold (typos fixed) 8384 - incorporated feedback from Barthold (ARB_compromise_buffers->EXT_framebuffer_object) 8385 - incorporated feedback from Barthold (slice->image) 8386 - incorporated feedback from Barthold (other ARB->EXT changes) 8387 8388 #20, August 19, 2004: jjuliano 8389 - fill in issue (13) and (36) - intrinsic buffers 8390 8391 #19, August 18, 2004: jjuliano 8392 - fixed minor typos in issue (15) 8393 - further clarified design rationale in issue (16) 8394 8395 #18, August 18, 2004: jjuliano, jsandmel 8396 - cleaned up language for issues (15) and (16) 8397 8398 #17, August 18, 2004: jsandmel 8399 - cleaned up stale references to ARB_compromise_buffers. 8400 - resolved issues (1) - extension name 8401 - resolved issues (15) - {Copy}TexImage behavior on current framebuffer 8402 - resolved issues (16) - {Copy}TexImage behavior on non-current framebuffer 8403 - (re)resolved issues (21) - Delete object behavior on attached objects 8404 - resolved issues (22) - 1 or 2 detach objects routines 8405 - resolved issues (25) - query on invalid framebuffers 8406 - cleaned up issue (34) language on attachment query API 8407 8408 #16, August 18, 2004: jsandmel 8409 - renamed EXT_framebuffer_object as per group decision 8410 8411 #15, August 8, 2004: jsandmel 8412 - fixed minor typos found by jeff 8413 - expanded discussion on issue (20) to distinguish 8414 width/height/format of texture is mutable unlike texture 8415 target as suggested by jeff 8416 8417 #14, August 5, 2004: jsandmel 8418 - In several issues, make sure ask the same questions about 8419 renderbuffers when we are talking about textures. We want to 8420 resolve these issues symmetrically in almost all cases. 8421 - resolved issue (19) about unused texture/renderbuffer names 8422 - resolved issue (20) about attaching default state objects to 8423 framebuffers 8424 - resolved issue (21) about deleting attached texture/renderbuffer 8425 objects 8426 - fixed typo indicating when issue (33) was resolved 8427 - resolved issue (34) about querying framebuffer objects 8428 for attachments 8429 - resolved issue (44) about using a texture object as a source 8430 texture and destination renderable image 8431 - resolved issue (47) about delineating exactly which state 8432 modifying routines can cause framebuffer revalidation 8433 - added issue (48) about the returned information from 8434 ValidateFramebuffer(). 8435 8436 #13, August 3, 2004: jsandmel 8437 - added related issue in issue (44) - we need to consider 8438 texture objects bound to different targets on the same unit 8439 not just currently bound texture, when calculating 8440 source/destionation circuits. 8441 - in issue (44), option (b), indicate a possibly variant is 8442 to allow but not require ValidateFramebuffer to fail 8443 - cleaned up the "must fail" and "can fail" cases in 8444 issue (46). 8445 - added issue (47) - do we need to list exactly which 8446 state modification routines can cause ValidateFramebuffer 8447 to change its answer? 8448 8449 #12, August 3, 2004: jsandmel 8450 - added issue about when validation failures "can" occur vs. "must" 8451 occur. 8452 8453 #11, August 2, 2004: jsandmel 8454 - removed non-contact emails from contributor list 8455 - "methodology" -> "model" in issue (7) 8456 - resolved issues (31,32,33), there is no renderbuffer name zero, 8457 and binding/attaching to it simply unbinds/detaches the previously 8458 bound/attached object. 8459 - added issue (44) about using the same texture object as both 8460 a source and destination 8461 - added issue (45) about scenarios where having no renderable 8462 image attached to the color buffer attachment point might be 8463 acceptable 8464 8465 #10, July 30, 2004: jjuliano 8466 - flesh out details of issue (29) about GenerateMipmap 8467 - add issue (43) about mipmap cube complete textures and 8468 framebuffer consistency check. 8469 8470 #9, July 30, 2004: jsandmel 8471 - renumbered issues to account for remaval and addition of issues 8472 - dropped issue [used to be (14)] as it was a duplicate of issue 8473 [now (38)] about support for multiple render targets. 8474 - added issue (32) about whether and how to support a 8475 renderbuffer with the name zero (is it an object?) 8476 8477 #8, July 30, 2004: jjuliano 8478 - tightened up language in overview regarding use of renderable 8479 images 8480 - clarified in overview that window and framebuffer can 8481 have different formats 8482 - fixed various typos, grammar, spelling errors 8483 - indicated we should drop issue (14) about MRT, same as issue (37) 8484 - indicate -1 is one option for return value on nonsense queries 8485 of non-validated framebuffer state 8486 8487 #7, July 29, 2004: jsandmel 8488 - add some more terms to the glossary list 8489 - white space and various grammar clean ups (minor) 8490 - note that we need resolution on the switch from 8491 "render target" to "renderable image" 8492 - cleaned up language for issue (31) and (32) 8493 8494 #6, July 29, 2004: jsandmel 8495 - reworked, clarified, streamlined overview section to read better 8496 - cleaned up some white space problems 8497 8498 #5, July 29, 2004: jsandmel 8499 - fixed bad numbering in issues list 8500 8501 #4, July 29, 2004: jsandmel 8502 - cleaned up issues after incorporating feedback 8503 8504 #3, July 28, 2004: jsandmel 8505 - began merging render target and compromise buffers issues lists 8506 - added contributors from EXT_render_target list 8507 - added some extension dependencies 8508 - borrowed overview from EXT_render_target, reworded to 8509 make more appropriate for differences with this spec 8510 - added placeholders for sample code 8511 - resolved a few issues here 8512 - removed intrinsic buffers per group decision july 26,2004 8513 - retained framebuffer objects per group decision july 26,2004 8514 - made FramebufferTexture into 3 functions per group decision july 26, 2004 8515 8516 #2, July 22, 2004: jsandmel 8517 - removed all old EXT-compromise_buffer language, but 8518 some of this will get reformed and added back in 8519 - removed example temporarily, again this will get reformed and 8520 added back in. 8521 - LogicalBuffer renamed to "Renderbuffer" 8522 - began fleshing out issues list 8523 8524 #1, July 22, 2004: jsandmel 8525 - very first revision 8526 - derived from EXT_compromise_buffers but really a mishmash of 8527 all the proposals under discussion 8528