1Name 2 3 ARB_framebuffer_no_attachments 4 5Name Strings 6 7 GL_ARB_framebuffer_no_attachments 8 9Contact 10 11 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 12 13Contributors 14 15 Members of the Khronos OpenGL ARB TSG 16 17Notice 18 19 Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Specification Update Policy 23 24 Khronos-approved extension specifications are updated in response to 25 issues and bugs prioritized by the Khronos OpenGL Working Group. For 26 extensions which have been promoted to a core Specification, fixes will 27 first appear in the latest version of that core Specification, and will 28 eventually be backported to the extension document. This policy is 29 described in more detail at 30 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 31 32Status 33 34 Complete. 35 Approved by the ARB on 2012/06/12. 36 37Version 38 39 Last Modified Date: May 7, 2015 40 Revision: 5 41 42Number 43 44 ARB Extension #130 45 46Dependencies 47 48 OpenGL 3.0 or ARB_framebuffer_object is required. 49 50 This extension is written against the OpenGL 4.2 (Compatibility Profile) 51 Specification (January 19, 2012). 52 53 This extension interacts with OpenGL 3.0 and EXT_texture_array. 54 55 This extension interacts with EXT_direct_state_access. 56 57Overview 58 59 Framebuffer objects as introduced by ARB_framebuffer_object and OpenGL 3.0 60 provide a generalized mechanism for rendering to off-screen surfaces. 61 Each framebuffer object may have depth, stencil and zero or more color 62 attachments that can be written to by the GL. The size of the framebuffer 63 (width, height, layer count, sample count) is derived from the attachments 64 of that framebuffer. In unextended OpenGL 4.2, it is not legal to render 65 into a framebuffer object that has no attachments. Such a framebuffer 66 would be considered incomplete with the 67 FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT status. 68 69 With OpenGL 4.2 and ARB_shader_image_load_store, fragment shaders are 70 capable of doing random access writes to buffer and texture memory via 71 image loads, stores, and atomics. This ability enables algorithms using 72 the conventional rasterizer to generate a collection of fragments, where 73 each fragment shader invocation will write its outputs to buffer or 74 texture memory using image stores or atomics. Such algorithms may have no 75 need to write color or depth values to a conventional framebuffer. 76 However, a framebuffer with no attachments will be considered incomplete 77 and no rasterization or fragment shader exectuion will occur. To avoid 78 such errors, an application may be required to create an otherwise 79 unnecessary "dummy" texture and attach it to the framebuffer (possibly 80 with color writes masked off). If the algorithm requires the rasterizer 81 to operate over a large number of pixels, this dummy texture will 82 needlessly consume a significant amount of memory. 83 84 This extension enables the algorithms described above to work even with a 85 framebuffer with no attachments. Applications can specify default width, 86 height, layer count, and sample count parameters for a framebuffer object. 87 When a framebuffer with no attachments is bound, it will be considered 88 complete as long as the application has specified non-zero default width 89 and height parameters. For the purposes of rasterization, the framebuffer 90 will be considered to have a width, height, layer count, and sample count 91 derived from its default parameters. Framebuffers with one or more 92 attachments are not affected by these default parameters; the size of the 93 framebuffer will still be derived from the sizes of the attachments in 94 that case. 95 96 Additionally, this extension provides queryable implementation-dependent 97 maximums for framebuffer width, height, layer count, and sample count, 98 which may differ from similar limits on textures and renderbuffers. These 99 maximums will be used to error-check the default framebuffer parameters 100 and also permit implementations to expose the ability to rasterize to an 101 attachment-less framebuffer larger than the maximum supported texture 102 size. 103 104IP Status 105 106 No known IP claims. 107 108New Procedures and Functions 109 110 void FramebufferParameteri(enum target, enum pname, int param); 111 void GetFramebufferParameteriv(enum target, enum pname, int *params); 112 113 (the following two commands are supported only if EXT_direct_state_access 114 is supported) 115 116 void NamedFramebufferParameteriEXT(uint framebuffer, enum pname, 117 int param); 118 void GetNamedFramebufferParameterivEXT(uint framebuffer, enum pname, 119 int *params); 120 121New Tokens 122 123 Accepted by the <pname> parameter of FramebufferParameteri, 124 GetFramebufferParameteriv, NamedFramebufferParameteriEXT, and 125 GetNamedFramebufferParameterivEXT: 126 127 FRAMEBUFFER_DEFAULT_WIDTH 0x9310 128 FRAMEBUFFER_DEFAULT_HEIGHT 0x9311 129 FRAMEBUFFER_DEFAULT_LAYERS 0x9312 130 FRAMEBUFFER_DEFAULT_SAMPLES 0x9313 131 FRAMEBUFFER_DEFAULT_FIXED_SAMPLE_LOCATIONS 0x9314 132 133 Accepted by the <pname> parameter of GetIntegerv, GetBooleanv, 134 GetInteger64v, GetFloatv, and GetDoublev: 135 136 MAX_FRAMEBUFFER_WIDTH 0x9315 137 MAX_FRAMEBUFFER_HEIGHT 0x9316 138 MAX_FRAMEBUFFER_LAYERS 0x9317 139 MAX_FRAMEBUFFER_SAMPLES 0x9318 140 141 142Additions to Chapter 2 of the OpenGL 4.2 (Compatibility Profile) Specification 143(OpenGL Operation) 144 145 None. 146 147Additions to Chapter 3 of the OpenGL 4.2 (Compatibility Profile) Specification 148(Rasterization) 149 150 None. 151 152Additions to Chapter 4 of the OpenGL 4.2 (Compatibility Profile) Specification 153(Per-Fragment Operations and the Frame Buffer) 154 155 Modify Section 4.4.1, Binding and Managing Framebuffer Objects, p. 425 156 157 (add to third-to-last bullet, p. 427) 158 159 * If the attachment sizes are not identical, ... for each attachment). 160 if there are no attachments, rendering will be limited to a rectangle 161 having a lower left of (0,0) and an upper right of (width, height), 162 where <width> and <height> are the framebuffer object's default width 163 and height. 164 165 (add to next-to-last bullet, p. 427) 166 167 * If the number of layers of each attachment are not identical, ... of any 168 attachment. If there are no attachments, the number of layers will be 169 taken from the framebuffer object's default layer count. 170 171 (insert before the last paragraph of the section , p. 428) 172 173 Parameters of a framebuffer object are set using the command 174 175 void FramebufferParameteri(enum target, enum pname, int param); 176 177 <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER. 178 FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER. <pname> specifies the 179 parameter of the framebuffer object bound to target to set. An 180 INVALID_OPERATION error is generated if the default (zero) framebuffer 181 object is bound to <target>. 182 183 When a framebuffer has one or more attachments, the width, height, layer 184 count (section 4.4.7), sample count, and sample location pattern of the 185 framebuffer are derived from the properties of the framebuffer 186 attachments. When the framebuffer has no attachments, these properties 187 are taken from framebuffer parameters. When <pname> is 188 FRAMEBUFFER_DEFAULT_WIDTH, FRAMEBUFFER_DEFAULT_HEIGHT, 189 FRAMEBUFFER_DEFAULT_LAYERS, FRAMEBUFFER_DEFAULT_SAMPLES, or 190 FRAMEBUFFER_DEFAULT_FIXED_SAMPLE_LOCATIONS, the value in <param> specifies 191 the width, height, layer count, sample count, or sample location pattern, 192 repsectively, used when the framebuffer has no attachments. The error 193 INVALID_VALUE will be generated if <param> is less than zero or greater 194 the implementation-dependent limits MAX_FRAMEBUFFER_WIDTH, 195 MAX_FRAMEBUFFER_HEIGHT, MAX_FRAMEBUFFER_LAYERS, MAX_FRAMEBUFFER_SAMPLES if 196 <pname> is FRAMEBUFFER_DEFAULT_WIDTH, FRAMEBUFFER_DEFAULT_HEIGHT, 197 FRAMEBUFFER_DEFAULT_LAYERS, or FRAMEBUFFER_DEFAULT_SAMPLES, respectively. 198 199 When a framebuffer has no attachments, it is considered layered (section 200 4.4.7) if and only if the value of FRAMEBUFFER_DEFAULT_LAYERS is non-zero. 201 It is considered to have sample buffers if and only if the value of 202 FRAMEBUFFER_DEFAULT_SAMPLES is non-zero. The number of samples in the 203 framebuffer is derived from the value of FRAMEBUFFER_DEFAULT_SAMPLES in an 204 implementation-dependent manner similar to that described for the command 205 RenderbufferStorageMultisample (section 4.4.2). If the framebuffer has 206 sample buffers, if the value of FRAMEBUFFER_DEFAULT_FIXED_SAMPLE_LOCATIONS 207 is non-zero, it is considered to have a fixed sample location pattern as 208 described for TexImage2DMultisample (section 3.10.6). 209 210 The command 211 212 void NamedFramebufferParameteriEXT(uint framebuffer, enum pname, 213 int param); 214 215 operates exactly like FramebufferParameteri, except that it modifies 216 parameters of the framebuffer object named by <framebuffer> instead of a 217 specified bound framebuffer object. The error INVALID_VALUE is generated 218 if <framebuffer> is not a name returned by GenFramebuffers. If a 219 framebuffer object named <framebuffer> does not yet exist, it will be 220 created. 221 222 223 Modify Section 4.4.4, Framebuffer Completeness, p. 439 224 225 (modify second bullet in the list of required conditions for attachment 226 completeness in "Framebuffer Attachment Completeness", p. 440) 227 228 * The width and height of <image> are greater than zero and are less than 229 or equal to the implementation-dependent limits MAX_FRAMEBUFFER_WIDTH 230 and MAX_FRAMEBUFFER_HEIGHT, respectively. 231 232 (delete the third and fourth bullets in the list, replacing with new 233 bullets at the end of the list) 234 235 (add new bullets to the end of the list, p. 441) 236 237 * If <image> is a three-dimensional, one- or two-dimensional array, or 238 cube map array texture and the attachment is not layered, the selected 239 layer is less than the depth or layer count of the texture. 240 241 * If <image> is a three-dimensional, one- or two-dimensional array, or 242 cube map array texture and the attachment is layered, the depth or 243 layer count of the texture is less than or equal to the 244 implementation-dependent limit MAX_FRAMEBUFFER_LAYERS. 245 246 * If <image> has multiple samples, its sample count is less than or equal 247 to the implementation-dependent limit MAX_FRAMEBUFFER_SAMPLES. 248 249 (modify third bullet of "Whole Framebuffer Completeness", p. 441) 250 251 * There is at least one image attached to the framebuffer, or the 252 framebuffer's FRAMEBUFFER_DEFAULT_WIDTH and FRAMEBUFFER_DEFAULT_HEIGHT 253 parameters are both non-zero. 254 255 { FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT } 256 257 258Additions to Chapter 5 of the OpenGL 4.2 (Compatibility Profile) Specification 259(Special Functions) 260 261 None. 262 263 (NOTE: GetFramebufferParameteriv is not compiled in a display list, but 264 no spec language is required due to the blanket language covering all Get* 265 commands.) 266 267Additions to Chapter 6 of the OpenGL 4.2 (Compatibility Profile) Specification 268(State and State Requests) 269 270 Modify Section 6.1.19, Framebuffer Object Queries, p. 501 271 272 (add to end of the section, p. 504) 273 274 The command 275 276 void GetFramebufferParameteriv(enum target, enum pname, int *params) 277 278 returns the values of the framebuffer parameter <pname> of the framebuffer 279 object bound to <target>. 280 281 <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER. 282 FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER. <pname> specifies the 283 parameter of the framebuffer object bound to target to return. An 284 INVALID_OPERATION error is generated if the default (zero) framebuffer 285 object is bound to <target>. 286 287 The command 288 289 void GetNamedFramebufferParameterivEXT(uint framebuffer, enum pname, 290 int *params); 291 292 operates exactly like GetFramebufferParameteriv, except that it queries 293 parameters of the framebuffer object named by <framebuffer> instead of a 294 specified bound framebuffer object. The error INVALID_VALUE is generated 295 if <framebuffer> is not a name returned by GenFramebuffers. If a 296 framebuffer object named <framebuffer> does not yet exist, it will be 297 created. 298 299 300Additions to Appendix A of the OpenGL 4.2 (Compatibility Profile) Specification 301(Invariance) 302 303 None. 304 305Additions to Appendix D of the OpenGL 4.2 (Compatibility Profile) Specification 306(Shared Objects and Multiple Contexts) 307 308 None. 309 310Additions to the AGL/EGL/GLX/WGL Specifications 311 312 None 313 314GLX Protocol 315 316 TBD 317 318Dependencies on OpenGL 3.0 and EXT_texture_array 319 320 If OpenGL 3.0 and EXT_texture_array are not supported, references to the 321 framebuffer parameter FRAMEBUFFER_DEFAULT_LAYERS should be removed. 322 323Dependencies on EXT_direct_state_access 324 325 If EXT_direct_state_access is not supported, the commands 326 NamedFramebufferParameteriEXT and GetNamedFramebufferParameterivEXT are 327 not supported. 328 329Errors 330 331 The error INVALID_ENUM is generated by FramebufferParameteri and 332 GetFramebufferParameteriv if <target> is not DRAW_FRAMEBUFFER, 333 READ_FRAMEBUFFER, or FRAMEBUFFER. 334 335 The error INVALID_OPERATION is generated by FramebufferParameteri and 336 GetFramebufferParameteriv if the default (zero) framebuffer is bound to 337 target. 338 339 The error INVALID_VALUE is generated by FramebufferParameteri and 340 NamedFramebufferParameteriEXT if <param> is less than zero or greater the 341 implementation-dependent limits MAX_FRAMEBUFFER_WIDTH, 342 MAX_FRAMEBUFFER_HEIGHT, MAX_FRAMEBUFFER_LAYERS, MAX_FRAMEBUFFER_SAMPLES if 343 <pname> is FRAMEBUFFER_DEFAULT_WIDTH, FRAMEBUFFER_DEFAULT_HEIGHT, 344 FRAMEBUFFER_DEFAULT_LAYERS, or FRAMEBUFFER_DEFAULT_SAMPLES, respectively. 345 346 The error INVALID_VALUE is generated by NamedFramebufferParameteriEXT and 347 GetNamedFramebufferParameterivEXT if <framebuffer> is not a name returned 348 by GenFramebuffers. 349 350New State 351 352 Add to Table 6.33, Framebuffer (state per framebuffer object), p. 537 353 354 Initial 355 Get Value Type Get Command Value Description Sec. Attrib. 356 ---------------------------- ---- --------------- ------- ------------------------ ----- --------- 357 FRAMEBUFFER_DEFAULT_WIDTH Z+ GetFramebuffer- 0 default width of frame- 4.4.1 - 358 Parameteriv buffer w/o attachments 359 FRAMEBUFFER_DEFAULT_HEIGHT Z+ GetFramebuffer- 0 default height of frame- 4.4.1 - 360 Parameteriv buffer w/o attachments 361 FRAMEBUFFER_DEFAULT_LAYERS Z+ GetFramebuffer- 0 default layer count of 4.4.1 - 362 Parameteriv framebuffer w/o 363 attachments 364 FRAMEBUFFER_DEFAULT_SAMPLES Z+ GetFramebuffer- 0 default sample count of 4.4.1 - 365 Parameteriv framebuffer w/o 366 attachments 367 FRAMEBUFFER_DEFAULT_FIXED_ B GetFramebuffer- FALSE default sample location 4.4.1 - 368 SAMPLE_LOCATIONS Parameteriv pattern of framebuffer 369 w/o attachments 370 371 372New Implementation Dependent State 373 374 Get Value Type Get Command Minimum Value Description Sec. 375 ----------------------- ---- ----------- ------------- ------------------------- ----- 376 MAX_FRAMEBUFFER_WIDTH Z+ GetIntegerv 16384 (*) maximum width for 4.4.1 377 framebuffer object 378 MAX_FRAMEBUFFER_HEIGHT Z+ GetIntegerv 16384 (*) maximum height for 4.4.1 379 framebuffer object 380 MAX_FRAMEBUFFER_LAYERS Z+ GetIntegerv 2048 (*) maximum layer count for 4.4.1 381 layered framebuffer object 382 MAX_FRAMEBUFFER_SAMPLES Z+ GetIntegerv 4 (*) maximum sample count for 4.4.1 383 framebuffer object 384 385 (*) Note: These minimum values are the ones applicable to this extension 386 on top of OpenGL 4.2 and higher. The minimum values may be lower on 387 implementations supporting only older versions of OpenGL. For 388 implementations supporting this extension on older versions, the minimums 389 can be determined from the table below. 390 391 the minimum for is the minimum defined for 392 ----------------------- -------------------------- 393 MAX_FRAMEBUFFER_WIDTH MAX_TEXTURE_SIZE 394 MAX_FRAMEBUFFER_HEIGHT MAX_TEXTURE_SIZE 395 MAX_FRAMEBUFFER_LAYERS MAX_ARRAY_TEXTURE_LAYERS 396 MAX_FRAMEBUFFER_SAMPLES MAX_SAMPLES 397 398Issues 399 400 (1) Should we specify the default framebuffer parameters in one command or 401 via separate FramebufferParameter* commands? 402 403 RESOLVED: Separate parameters provide for a more future-proof API, in 404 case we need new defaults in the future. 405 406 (2) Should the default framebuffer parameters affect only framebuffers 407 with no attachments? 408 409 RESOLVED: As specified, they affect only framebuffers with no 410 attachments. 411 412 Alternately, one could have treated these default parameters as 413 specifying an extra unusable attachment whose values would be used in 414 various intersection/consistency tests. In that approach, if a 415 framebuffer had a single attachment and default parameters were also 416 specified: 417 418 * the renderable area would be the intersection of the rectangle/layer 419 count derived from the attachment and the rectangle/layer count from 420 the framebuffer defaults; 421 422 * the sample count and fixed sample location state would have to match 423 between the attachment and framebuffer default. 424 425 This specification is not using such an "intersection" approach, which 426 doesn't seem to introduce significant value. 427 428 (3) Should we check the default framebuffer parameters against 429 implementation-dependent limits when they are specified, when testing 430 for completeness, or both? 431 432 RESOLVED: We will expose implementation-dependent limits on the maximum 433 framebuffer width, height, layer count, and sample count, and check the 434 values passed the FramebufferParameteri against them. 435 436 As specified, implementations are required to support all legal 437 combinations of default framebuffer width, height, sample count, and 438 layer count as long as they are under their respective implementation 439 limits. This requirement could be a problem if a hypothetical 440 implementation could support larger values for one default parameter as 441 long as others stayed small. For example, if an implementation could 442 support a 64Kx64K single-sample framebuffer, but could only support a 443 16Kx16K framebuffer with 8 samples, this extension would only permit 444 them to expose a maximum width/height of 16K. The most obvious way to 445 support this would be to add a feature allowing larger default sizes, 446 but treating a framebuffer with an unsupported combination (e.g., 447 64Kx64K at 8xAA) as incomplete. Such a capability will not be 448 incorporated into this extension, however. 449 450 (4) How do the new implementation-dependent limits for maximum framebuffer 451 width, height, layer count, and sample count affect framebuffers with 452 attachments? 453 454 RESOLVED: If implementation limits permit the creation of attachable 455 surfaces larger than the maximum framebuffer size, such images will be 456 considered not to be framebuffer attachment complete. We don't expect 457 this to be a common case, as the minimum maximums for framebuffer sizes 458 equals the minimum maximums for texture sizes. 459 460 (5) The ClampColor setting FIXED_ONLY depends on the framebuffer. How is 461 this value intepreted in a framebuffer with no attachments? 462 463 RESOLVED: Given current spec language, clamping should be enabled in 464 this case, as there are no enabled color buffers with non-fixed-point 465 components: 466 467 If clamp is FIXED_ONLY, fragment color clamping is enabled if 468 all enabled color buffers have fixed-point components. 469 470 This isn't really a new issue in this extension; it could also arise 471 when using a complete framebuffer with no color attachments. 472 473 Note that this issue has no effect on the core profile of OpenGL. 474 CLAMP_VERTEX_COLOR and CLAMP_FRAGMENT_COLOR are compatibility-only. 475 CLAMP_READ_COLOR has no effect as ReadPixels will always generate an 476 error due to the lack of framebuffer attachments. 477 478 (6) What should be returned on the compatibility profile queries of 479 RED_BITS, GREEN_BITS, BLUE_BITS, and ALPHA_BITS on a framebuffer with 480 no attachments? 481 482 RESOLVED: Zero should be returned, which is also the case for 483 DEPTH_BITS and STENCIL_BITS. As in issue (5), this isn't a new issue in 484 this spec. 485 486Revision History 487 488 Revision 5, May 7, 2015 (Jon Leech) 489 - Restore missing cube map arrays to new framebuffer attachment 490 completeness conditions (Bug 11201). 491 492 Revision 4, September 12, 2012 (Jon Leech) 493 - Clarify legal <target> values (Bug 9344). 494 495 Revision 3, June 4, 2012 (pbrown) 496 - Mark issues (4) through (6) as resolved. 497 498 Revision 2, June 1, 2012 (pbrown) 499 - Add new implementation-dependent limits on framebuffer width, height, 500 layer count, and sample count. 501 - Assign enumerant values for all the new tokens. 502 - Specify that the default framebuffer parameters are error-checked 503 against the new implementation limits. 504 - Add new checks treating framebuffer attachments as incomplete in the 505 unlikely event that they exceed the new implementation limits. 506 - Mark issues (1) through (3) as resolved. 507 - Add new issues (4) through (6). 508 - Add overview text. 509 510 Revision 1, May 14, 2012 (pbrown) 511 - Initial revision, for discussion purposes. 512