1 Name 2 3 EXT_draw_buffers 4 5 Name Strings 6 7 GL_EXT_draw_buffers 8 9 Contributors 10 11 Contributors to GL_NV_draw_buffers 12 Contributors to GL_NV_fbo_color_attachments 13 Contributors to the OpenGL ES 2.0 specification 14 Contributors to the OpenGLSL ES 1.0.17 specification 15 Contributors to the OpenGL ES 3.0 specification 16 Nicolas Capens, TransGaming Inc. 17 Daniel Koch, TransGaming Inc. 18 Alastair Patrick, Google Inc. 19 Kenneth Russell, Google Inc. 20 Greg Roth, NVIDIA Corporation 21 Ben Bowman, Imagination Technologies 22 Members of the WebGL and OpenGL ES working groups 23 24 Contact 25 26 Daniel Koch (daniel 'at' transgaming.com) 27 28 Status 29 30 Draft Complete 31 32 Version 33 34 Last Modified Date: January 30, 2013 35 Revision: #7 36 37 Number 38 39 TBD 40 41 Dependencies 42 43 OpenGL ES 2.0 is required. 44 45 The extension is written against the OpenGL ES 2.0 specification. 46 47 ANGLE_framebuffer_blit affects the definition of this extension. 48 APPLE_framebuffer_multisample affects the definitin of this extension. 49 50 Overview 51 52 This extension increases the number of available framebuffer object 53 color attachment points, extends OpenGL ES 2.0 to allow multiple output 54 colors, and provides a mechanism for directing those outputs to 55 multiple color buffers. 56 57 This extension is similar to the combination of the GL_NV_draw_buffers 58 and GL_NV_fbo_color_attachments extensions, but imposes certain 59 restrictions informed by the OpenGL ES 3.0 API. 60 61 New Procedures and Functions 62 63 void DrawBuffersEXT(sizei n, const enum *bufs); 64 65 New Tokens 66 67 Accepted by the <pname> parameter of GetIntegerv: 68 69 MAX_COLOR_ATTACHMENTS_EXT 0x8CDF 70 71 Accepted by the <pname> parameters of GetIntegerv and GetFloatv: 72 73 MAX_DRAW_BUFFERS_EXT 0x8824 74 DRAW_BUFFER0_EXT 0x8825 75 DRAW_BUFFER1_EXT 0x8826 76 DRAW_BUFFER2_EXT 0x8827 77 DRAW_BUFFER3_EXT 0x8828 78 DRAW_BUFFER4_EXT 0x8829 79 DRAW_BUFFER5_EXT 0x882A 80 DRAW_BUFFER6_EXT 0x882B 81 DRAW_BUFFER7_EXT 0x882C 82 DRAW_BUFFER8_EXT 0x882D 83 DRAW_BUFFER9_EXT 0x882E 84 DRAW_BUFFER10_EXT 0x882F 85 DRAW_BUFFER11_EXT 0x8830 86 DRAW_BUFFER12_EXT 0x8831 87 DRAW_BUFFER13_EXT 0x8832 88 DRAW_BUFFER14_EXT 0x8833 89 DRAW_BUFFER15_EXT 0x8834 90 91 Accepted by the <attachment> parameter of FramebufferRenderbuffer, 92 FramebufferTexture2D and GetFramebufferAttachmentParameteriv, and by 93 the <bufs> parameter of DrawBuffersEXT: 94 95 COLOR_ATTACHMENT0_EXT 0x8CE0 96 COLOR_ATTACHMENT1_EXT 0x8CE1 97 COLOR_ATTACHMENT2_EXT 0x8CE2 98 COLOR_ATTACHMENT3_EXT 0x8CE3 99 COLOR_ATTACHMENT4_EXT 0x8CE4 100 COLOR_ATTACHMENT5_EXT 0x8CE5 101 COLOR_ATTACHMENT6_EXT 0x8CE6 102 COLOR_ATTACHMENT7_EXT 0x8CE7 103 COLOR_ATTACHMENT8_EXT 0x8CE8 104 COLOR_ATTACHMENT9_EXT 0x8CE9 105 COLOR_ATTACHMENT10_EXT 0x8CEA 106 COLOR_ATTACHMENT11_EXT 0x8CEB 107 COLOR_ATTACHMENT12_EXT 0x8CEC 108 COLOR_ATTACHMENT13_EXT 0x8CED 109 COLOR_ATTACHMENT14_EXT 0x8CEE 110 COLOR_ATTACHMENT15_EXT 0x8CEF 111 112 The COLOR_ATTACHMENT0_EXT constant is equal to the 113 COLOR_ATTACHMENT0 constant. 114 115 Each COLOR_ATTACHMENT<i>_EXT adheres to COLOR_ATTACHMENT<i>_EXT 116 = COLOR_ATTACHMENT0_EXT + <i>. 117 118 Changes to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 119 120 Section 3.2, (Multisampling). Replace the second paragraph: 121 122 An additional buffer, called the multisample buffer, is added to the 123 window system-provided framebuffer. Pixel sample values, including 124 color, depth, and stencil values, are stored in this buffer. Samples 125 contain separate color values for each fragment color. When the 126 window system-provided framebuffer includes a multisample buffer, it 127 does not include depth or stencil buffers, even if the multisample 128 buffer does not store depth or stencil values. Color buffers do 129 coexist with the multisample buffer, however. 130 131 Section 3.8.2, (Shader Execution) Replace subsection "Shader 132 Outputs": 133 134 The OpenGL ES Shading Language specification describes the values 135 that may be output by a fragment shader. These are gl_FragColor and 136 gl_FragData[n]. The final fragment color values or the final 137 fragment data values written by a fragment shader are clamped to the 138 range [0, 1] and then converted to fixed-point as described in 139 section 2.1.2 for framebuffer color components. 140 141 Writing to gl_FragColor specifies the fragment color (color number 142 zero) that will be used by subsequent stages of the pipeline. 143 Writing to gl_FragData[n] specifies the value of fragment color 144 number n. Any colors, or color components, associated with a 145 fragment that are not written by the fragment shader are undefined. 146 A fragment shader may not statically assign values to both 147 gl_FragColor and gl_FragData. In this case, a compile or link error 148 will result. A shader statically assigns a value to a variable if, 149 after preprocessing, it contains a statement that would write to the 150 variable, whether or not run-time flow of control will cause that 151 statement to be executed. 152 153 Changes to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 154 Operations and the Frame Buffer) 155 156 Modify the overview of Chapter 4 and replace the sentences 157 of the fifth paragraph which read: 158 159 "The name of the color buffer of an application-created framebuffer 160 object is COLOR_ATTACHMENT0. The names of the depth and stencil buffers 161 are DEPTH_ATTACHMENT and STENCIL_ATTACHMENT." 162 163 With the following: 164 165 "A framebuffer object has an array of color buffer attachment points, 166 numbered zero through <n>, a depth buffer attachment point, and a 167 stencil buffer attachment point." 168 169 Insert Table 4.3 to Section 4.2.1 (and renumber subsequent tables): 170 171 Symbolic Constant Meaning 172 ----------------- --------------------- 173 NONE No buffer 174 175 COLOR_ATTACHMENT<i>_EXT (see caption) Output fragment color to image 176 attached at color attachment 177 point i 178 179 Table 4.3: Arguments to DrawBuffersEXT when the context is bound to a 180 framebuffer object, and the buffers they indicate. <i> in 181 COLOR_ATTACHMENT<i>_EXT may range from zero to the value of 182 MAX_COLOR_ATTACHMENTS_EXT minus one. 183 184 Replace Section 4.2.1, "Selecting a Buffer for Writing" with the following: 185 186 "By default, color values are written into the front buffer for 187 single buffered surfaces or into the back buffer for back buffered 188 surfaces as determined when making the context current. To control 189 the color buffer into which each of the fragment color values is 190 written, DrawBuffersEXT is used. 191 192 The command 193 194 void DrawBuffersEXT(sizei n, const enum *bufs); 195 196 defines the draw buffers to which all fragment colors are written. 197 <n> specifies the number of buffers in <bufs>. <bufs> is a pointer 198 to an array of symbolic constants specifying the buffer to which 199 each fragment color is written. 200 201 Each buffer listed in <bufs> must be BACK, NONE, or one of the 202 values from table 4.3. Further, acceptable values for the constants 203 in <bufs> depend on whether the GL is using the default framebuffer 204 (i.e., DRAW_FRAMEBUFFER_BINDING is zero), or a framebuffer object 205 (i.e., DRAW_FRAMEBUFFER_BINDING is non-zero). For more information 206 about framebuffer objects, see section 4.4. 207 208 If the GL is bound to the default framebuffer, then <n> must be 1 209 and the constant must be BACK or NONE. When draw buffer zero is 210 BACK, color values are written into the sole buffer for single- 211 buffered contexts, or into the back buffer for double-buffered 212 contexts. If DrawBuffersEXT is supplied with a constant other than 213 BACK and NONE, the error INVALID_OPERATION is generated. 214 215 If the GL is bound to a draw framebuffer object, then each of the 216 constants must be one of the values listed in table 4.3. 217 218 In both cases, the draw buffers being defined correspond in order to 219 the respective fragment colors. The draw buffer for fragment 220 colors beyond <n> is set to NONE. 221 222 The maximum number of draw buffers is implementation-dependent. The 223 number of draw buffers supported can be queried by calling 224 GetIntegerv with the symbolic constant MAX_DRAW_BUFFERS_EXT. An 225 INVALID_VALUE error is generated if <n> is greater than 226 MAX_DRAW_BUFFERS_EXT. 227 228 If the GL is bound to a draw framebuffer object, the <i>th buffer listed 229 in <bufs> must be COLOR_ATTACHMENT<i>_EXT or NONE. Specifying a 230 buffer out of order, BACK, or COLOR_ATTACHMENT<m>_EXT where <m> is 231 greater than or equal to the value of MAX_COLOR_ATTACHMENTS_EXT, 232 will generate the error INVALID_OPERATION. 233 234 If a fragment shader writes to "gl_FragColor", DrawBuffersEXT 235 specifies the set of draw buffers into which the color 236 written to "gl_FragColor" is written. If a fragment shader writes to 237 "gl_FragData", DrawBuffersEXT specifies a set of draw buffers 238 into which each of the multiple output colors defined by these 239 variables are separately written. If a fragment shader writes to 240 neither "gl_FragColor" nor "gl_FragData" the values of the 241 fragment colors following shader execution are undefined, and may 242 differ for each fragment color. 243 244 Indicating a buffer or buffers using DrawBuffersEXT causes 245 subsequent pixel color value writes to affect the indicated 246 buffers. If the GL is bound to a draw framebuffer object and a draw 247 buffer selects an attachment that has no image attached, then that 248 fragment color is not written. 249 250 Specifying NONE as the draw buffer for a fragment color will inhibit 251 that fragment color from being written. 252 253 The state required to handle color buffer selection for each 254 framebuffer is an integer for each supported fragment color. For the 255 default framebuffer, in the initial state the draw buffer for 256 fragment color zero is BACK if there is a default framebuffer 257 associated with the context, otherwise NONE. For framebuffer 258 objects, in the initial state the draw buffer for fragment color 259 zero is COLOR_ATTACHMENT0_EXT. 260 261 For both the default framebuffer and framebuffer objects, the 262 initial state of draw buffers for fragment colors other than zero is 263 NONE. 264 265 The value of the draw buffer selected for fragment color <i> can be 266 queried by calling GetIntegerv with the symbolic constant 267 DRAW_BUFFER<i>_EXT." 268 269 Modify Section 4.2.3 (Clearing the Buffers) and replace the first 270 two paragraphs with the following: 271 272 "The GL provides a means for setting portions of every pixel in a 273 particular buffer to the same value. The argument to 274 275 void Clear(bitfield buf); 276 277 is the bitwise OR of a number of values indicating which buffers are 278 to be cleared. The values are COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT, and 279 STENCIL_BUFFER_BIT, indicating the buffers currently enabled for color 280 writing, the depth buffer, and the stencil buffer (see below), 281 respectively. The value to which each buffer is cleared depends on 282 the setting of the clear value for that buffer. If the mask is not a 283 bitwise OR of the specified values, then the error INVALID_VALUE is 284 generated. 285 286 void ClearColor(clampf r, clampf, g, clampf b, clampf a); 287 288 sets the clear value for fixed-point color buffers. Each of the 289 specified components is clamped to [0, 1] and converted to fixed-point 290 as described in section 2.1.2 for framebuffer color components." 291 292 Replace the second paragraph of Section 4.4.1 (Binding and Managing 293 Framebuffer Objects) with the following: 294 295 "The namespace for framebuffer objects is the unsigned integers, with 296 zero reserved by OpenGL ES to refer to the default framebuffer. A 297 framebuffer object is created by binding an unused name to the 298 target FRAMEBUFFER, DRAW_FRAMEBUFFER, or READ_FRAMEBUFFER. The binding 299 is effected by calling 300 301 void BindFramebuffer(enum target, uint framebuffer); 302 303 with <target> set the desired framebuffer target and <framebuffer> set 304 to the unused name. The resulting framebuffer object is a new state 305 vector. There is a number of color attachment points, plus one each 306 for the depth and stencil attachment points. The number of color attachment 307 points is equal to the value of MAX_COLOR_ATTACHMENTS_EXT." 308 309 Replace the third item in the bulleted list in Section 4.4.1 (Binding 310 and Managing Framebuffer Objects) with the following: 311 312 " * The only color buffer bitplanes are the ones defined by the 313 framebuffer attachments points named COLOR_ATTACHMENT0_EXT through 314 COLOR_ATTACHMENT<n>_EXT." 315 316 Modify Section 4.4.3 (Renderbuffer Objects) in the 317 "Attaching Renderbuffer Images to a Framebuffer" subsection as follows: 318 319 Insert the following table: 320 321 Name of attachment 322 --------------------------------------- 323 COLOR_ATTACHMENT<i>_EXT (see caption) 324 DEPTH_ATTACHMENT 325 STENCIL_ATTACHMENT 326 327 Table 4.x: Framebuffer attachment points. <i> in COLOR_ATTACHMENT<i>_EXT 328 may range from zero to the value of MAX_COLOR_ATTACHMENTS_EXT minus 1. 329 330 Modify the third sentence of the paragraph following the definition of 331 FramebufferRenderbuffer to be as follows: 332 333 "<attachment> should be set to one of the attachment points of the 334 framebuffer listed in Table 4.x." 335 336 Modify Section 4.4.3 (Renderbuffer Objects) in the "Attaching Texture 337 Images to a Framebuffer" subsection as follows: 338 339 Modify the last sentence of the paragraph following the definition of 340 FramebufferTexture2D to be as follows: 341 342 "<attachment> must be one of the attachment points of the framebuffer 343 listed in Table 4.x." 344 345 Modify Section 4.4.5 (Framebuffer Completeness) and replace the 3rd 346 item in the bulleted list in the "Framebuffer Attachment Completeness" 347 subsection with the following: 348 349 " * If <attachment> is COLOR_ATTACHMENT<i>_EXT, then <image> must 350 have a color-renderable internal format." 351 352 Changes to Chapter 6 of the OpenGL ES 2.0 Specification (State and 353 State Requests) 354 355 In section 6.1.3 (Enumerated Queries) modify the third sentence in 356 the definition of GetFramebufferAttachmentParameteriv to be as follows: 357 358 "<attachment> must be one of the attachment points of the framebuffer 359 listed in Table 4.x." 360 361 Changes to Chapter 3 of the OpenGL ES Shading Language 1.0.17 Specification (Basics) 362 363 Add a new section: 364 365 3.4.1 GL_EXT_draw_buffers Extension 366 367 To use the GL_EXT_draw_buffers extension in a shader it 368 must be enabled using the #extension directive. 369 370 The shading language preprocessor #define 371 GL_EXT_draw_buffers will be defined to 1, if the 372 GL_EXT_draw_buffers extension is supported. 373 374 Dependencies on ANGLE_framebuffer_blit and APPLE_framebuffer_multisample: 375 376 If neither ANGLE_framebuffer_blit nor APPLE_framebuffer_multisample are 377 supported, then all references to "draw framebuffers" should be replaced 378 with references to "framebuffers". References to DRAW_FRAMEBUFFER_BINDING 379 should be replaced with references to FRAMEBUFFER_BINDING. References to 380 DRAW_FRAMEBUFFER and READ_FRAMEBUFFER should be removed. 381 382 If ANGLE_framebuffer_blit is supported, DRAW_FRAMEBUFFER_BINDING, DRAW_FRAMEBUFFER 383 and READ_FRAMEBUFFER all refer to corresponding _ANGLE suffixed names 384 (they have the same token values). 385 386 If APPLE_framebuffer_multisample is supported, DRAW_FRAMEBUFFER_BINDING, 387 DRAW_FRAMEBUFFER and READ_FRAMEBUFFER all refer to the corresponding _APPLE 388 suffixed names (they have the same token values). 389 390 Errors 391 392 The INVALID_OPERATION error is generated if DrawBuffersEXT is called 393 when the default framebuffer is bound and any of the following conditions 394 hold: 395 - <n> is greater than 1 and less than MAX_DRAW_BUFFERS_EXT, 396 - <bufs> contains a value other than BACK or NONE. 397 398 The INVALID_OPERATION error is generated if DrawBuffersEXT is called 399 when bound to a draw framebuffer object and any of the following 400 conditions hold: 401 - the <i>th value in <bufs> is not COLOR_ATTACHMENT<i>_EXT or NONE. 402 403 The INVALID_VALUE error is generated if DrawBuffersEXT is called 404 with a value of <n> which is greater than MAX_DRAW_BUFFERS_EXT. 405 406 The INVALID_ENUM error is generated by FramebufferRenderbuffer if 407 the <attachment> parameter is not one of the values listed in Table 4.x. 408 409 The INVALID_ENUM error is generated by FramebufferTexture2D if 410 the <attachment> parameter is not one of the values listed in Table 4.x. 411 412 The INVALID_ENUM error is generated by GetFramebufferAttachmentParameteriv 413 if the <attachment> parameter is not one of the values listed in Table 4.x. 414 415 New State 416 417 Add Table 6.X Framebuffer (State per framebuffer object): 418 419 State Type Get Command Initial Value Description 420 ------------------ ---- ------------ ------------- ----------- 421 DRAW_BUFFER<i>_EXT Z10* GetIntegerv see 4.2.1 Draw buffer selected 422 for fragment color i 423 424 Add to Table 6.18 (Implementation Dependent Values) 425 426 Get value Type Get Cmnd Minimum Value Description Sec. 427 -------------------- ---- ----------- ------------- ----------- ----- 428 MAX_DRAW_BUFFERS_EXT Z+ GetIntegerv 1 Maximum number of 4.2.1 429 active draw buffers 430 MAX_COLOR_ATTACHMENTS_EXT Z+ GetIntegerv 1 Number of framebuffer 4.4.1 431 color attachment points 432 Issues 433 434 See ARB_draw_buffers for relevant issues. 435 436 1) What are the differences between this extension and NV_draw_buffers 437 + NV_fbo_color_attachments? 438 439 RESOLVED. This extension: 440 - adds interactions with blit_framebuffer and the separate 441 draw/read binding points 442 - The draw buffer and color attachment limits are global instead 443 of per-fbo (see Issue 2) 444 - can be used to with default framebuffer to set NONE/BACK (see Issue 4) 445 - retains the ordering restrictions on color attachments that are 446 imposed by ES 3.0. 447 448 2) Should the MAX_DRAW_BUFFERS_EXT and MAX_COLOR_ATTACHMENTS_EXT limits 449 be per-framebuffer values or implementation dependent constants? 450 451 DISCUSSION: In ARB_draw_buffers this was per-context (see Issue 2). 452 EXT_framebuffer_object (and subsequently ARB_framebuffer_object, and GL 3.0 453 through GL 4.2) made these queries framebuffer-dependent. 454 However in GL 4.3 and GLES 3.0, these limits were changed from 455 framebuffer-dependent state to implementation-dependent state after 456 much discussion (Bug 7990). 457 458 NV_draw_buffers has MAX_DRAW_BUFFERS listed as per-framebuffer state, 459 but NV_fbo_color_attachments has MAX_COLOR_ATTACHMENTS as an 460 implementation-dependent constant. 461 462 This is relevant because some implementations are not able to support 463 multisampling in conjuction with multiple color attachments. If the 464 query is per-framebuffer, they can report a maximum of one attachment 465 when there are multisampled attachments, but a higher limit when only 466 single-sampled attachments are present. 467 468 RESOLVED. Make this global context state as this is most consistent 469 with GLES 3.0 and updated GL drivers. In an implementation cannot 470 support multisampling in conjunction with multiple color attachments, 471 perhaps such an implementation could report FBO incomplete in this 472 situation, but this is less than desirable. 473 474 3) Should we support broadcast from gl_FragColor to all gl_FragData[x] 475 or should it be synonymous with gl_FragData[0]? 476 477 DISCUSSION: With NV_draw_buffers, writing to gl_FragColor writes to all 478 the enabled draw buffers (ie broadcast). In OpenGL ES 3.0 when using 479 ESSL 1.0, gl_FragColor is equivalent to writing a single output to 480 gl_FragData[0] and multiple outputs are not possible. When using ESSL 3.0, 481 only user-defined out variables may be used. 482 483 If broadcast is supported, some implementations may have to replace 484 writes to gl_FragColor with replicated writes to all possible gl_FragData 485 locations when this extension is enabled. 486 487 RESOLVED: Writes to gl_FragColor are broadcast to all enabled color 488 buffers. ES 3.0 using ESSL 1.0 doesn't support broadcast because 489 ESSL 1.0 was not extended to have multiple color outputs (but that is 490 what this extension adds). ESSL 3.0 doesn't support the broadcast because 491 it doesn't have the gl_FragColor variable at all, and only has user- 492 defined out variables. This extension extends ESSL 1.0 to have multiple 493 color outputs. Broadcasting from gl_FragColor to all enabled color 494 buffers is the most consistent with existing draw buffer extensions to 495 date (both NV_draw_buffers and desktop GL). 496 497 4) Should we allow DrawBuffersEXT to be called when the default FBO is 498 bound? 499 500 DISCUSSION: NV_draw_buffers specifies that DrawBuffersNV errors with 501 INVALID_OPERATION when the default FBO is bound. OpenGL ES 3.0 allows 502 DrawBuffers to toggle between BACK and NONE on the default FBO. 503 504 An implementation that does not natively support disabling the drawbuffer 505 on the default FBO could emulate this by disabling color writes. 506 507 RESOLVED: Allow DrawBuffersEXT to be called for the default FBO. This 508 is more forward looking and is compatible with ES 3.0. 509 510 5) What are the requirements on the color attachment sizes and formats? 511 512 RESOLVED: ES 2.0 requires that all color buffers attached to application- 513 created framebuffer objects must have the same number of bitplanes 514 (Chapter 4 overview p91). ES 2.0 also requires that all attached images 515 have the same width and height (Section 4.4.5 Framebuffer Completeness). 516 This extension does not lift those requirements, and failing to meet 517 them will result in an incomplete FBO. 518 519 6) Does this have any interactions with glClear? 520 521 RESOLVED: Yes. When multiple color buffers are enabled for writing, 522 glClear clears all of the color buffers. Added language clarifying 523 that glClear and glClearColor may affect multiple color buffers. 524 525 Revision History 526 527 01/30/2013 dgkoch add issue 6 and clear interactions 528 renamed to EXT_draw_buffers based on feedback 529 changed resolution of issue 3. 530 01/23/2013 dgkoch add resolutions to issues 2-4. 531 add issue 5. 532 Add Table 4.x and update various explicit 533 references to COLOR_ATTACHMENT0. 534 Add errors. 535 11/13/2012 dgkoch add revision history 536 add text from updated ES 3.0 spec 537 add issues for discussion 538 10/16/2012 kbr update name string 539 10/16/2012 kbr remove restrition requiring draw buffer 0 to be non-NULL 540 10/12/2012 kbr remove references to GetDoublev and ReadBuffer 541 10/11/2012 kbr initial draft extension 542 543
