1Name 2 3 ARB_draw_buffers 4 5Name Strings 6 7 GL_ARB_draw_buffers 8 9Contributors 10 11 Benj Lipchak, AMD 12 Bill Licea-Kane, AMD 13 14Contact 15 16 Rob Mace, NVIDIA (rmace 'at' nvidia.com) 17 18Notice 19 20 Copyright (c) 2004-2013 The Khronos Group Inc. Copyright terms at 21 http://www.khronos.org/registry/speccopyright.html 22 23Specification Update Policy 24 25 Khronos-approved extension specifications are updated in response to 26 issues and bugs prioritized by the Khronos OpenGL Working Group. For 27 extensions which have been promoted to a core Specification, fixes will 28 first appear in the latest version of that core Specification, and will 29 eventually be backported to the extension document. This policy is 30 described in more detail at 31 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 32 33IP Status 34 35 No known IP issues. 36 37Status 38 39 Complete. Approved by the ARB on July 23, 2004. 40 41Version 42 43 Last Modified Date: February 19, 2008 44 Revision: 17 45 46Number 47 48 ARB Extension #37 49 50Dependencies 51 52 The extension is written against the OpenGL 1.5 Specification. 53 54 OpenGL 1.3 is required. 55 56 ARB_fragment_program affects the definition of this extension. 57 58 ARB_fragment_shader affects the definition of this extension. 59 60 61Overview 62 63 This extension extends ARB_fragment_program and ARB_fragment_shader 64 to allow multiple output colors, and provides a mechanism for 65 directing those outputs to multiple color buffers. 66 67 68Issues 69 70 (1) How many GL_DRAW_BUFFER#_ARB enums should be reserved? 71 72 RESOLVED: We only need 4 currently, but for future expandability 73 it would be nice to keep the enums in sequence. We'll specify 74 16 for now, which will be more than enough for a long time. 75 76 (2) How should multisample work when there are multiple output 77 colors being rendered to multiple draw buffers? 78 79 Basic options are: 80 (a) Color 0 is written to the multisample buffer and then the 81 multisample buffer is resolved to all the color buffers. 82 This option would be consistent with GL's idea of a single 83 multisample buffer, but would be really useless and defeat 84 the purpose of multiple output colors. 85 (b) Have a separate multisample color buffer for each output 86 color/draw buffer. This would be useful but would all 87 implementations be able to handle it? 88 (c) Don't allow multiple output colors and multisampling to 89 be combined by restricting MAX_DRAW_BUFFERS_ARB to 1 90 for contexts with multisample buffers. This is simple 91 and would allow a future extension to allow (b). 92 93 RESOLUTION: (b) and (c). Samples will contain separate color 94 values for each output color. Implementations that can not 95 support this can restrict MAX_DRAW_BUFFERS_ARB to 1 for contexts 96 with multisample buffers. 97 98 (3) Should gl_FragColor be aliased to gl_FragData[0]? 99 100 RESOLUTION: No. A shader should write either gl_FragColor, or 101 gl_FragData[n], but not both. 102 103 Writing to gl_FragColor will write to all draw buffers specified 104 with DrawBuffersARB. 105 106 (4) Should gl_FragData[n] be clamped? 107 108 RESOLUTION: They will be clamped if fragment color clamping is 109 enabled. 110 111 112New Procedures and Functions 113 114 void DrawBuffersARB(sizei n, const enum *bufs); 115 116 117New Tokens 118 119 Accepted by the <pname> parameters of GetIntegerv, GetFloatv, 120 and GetDoublev: 121 122 MAX_DRAW_BUFFERS_ARB 0x8824 123 DRAW_BUFFER0_ARB 0x8825 124 DRAW_BUFFER1_ARB 0x8826 125 DRAW_BUFFER2_ARB 0x8827 126 DRAW_BUFFER3_ARB 0x8828 127 DRAW_BUFFER4_ARB 0x8829 128 DRAW_BUFFER5_ARB 0x882A 129 DRAW_BUFFER6_ARB 0x882B 130 DRAW_BUFFER7_ARB 0x882C 131 DRAW_BUFFER8_ARB 0x882D 132 DRAW_BUFFER9_ARB 0x882E 133 DRAW_BUFFER10_ARB 0x882F 134 DRAW_BUFFER11_ARB 0x8830 135 DRAW_BUFFER12_ARB 0x8831 136 DRAW_BUFFER13_ARB 0x8832 137 DRAW_BUFFER14_ARB 0x8833 138 DRAW_BUFFER15_ARB 0x8834 139 140 141Additions to Chapter 2 of the OpenGL 1.5 Specification (OpenGL 142Operation) 143 144 None 145 146 147Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization) 148 149 Modify Section 3.2.1, Multisampling (p. 71) 150 151 (replace the second paragraph with) 152 153 An additional buffer, called the multisample buffer, is added to the 154 framebuffer. Pixel sample values, including color, depth, and 155 stencil values, are stored in this buffer. Samples contain separate 156 color values for each output color. When the framebuffer includes a 157 multisample buffer, it does not include depth or stencil buffers, 158 even if the multisample buffer does not store depth or stencil 159 values. Color buffers (left, right, front, back, and aux) do coexist 160 with the multisample buffer, however. 161 162 163 Modify Section 3.11.2, Fragment Program Grammar and Semantic 164 Restrictions (ARB_fragment_program) 165 166 (replace <resultBinding> grammar rule with these rules) 167 168 <resultBinding> ::= "result" "." "color" <optOutputColorNum> 169 | "result" "." "depth" 170 171 <optOutputColorNum> ::= "" 172 | "[" <outputColorNum> "]" 173 174 <outputColorNum> ::= <integer> from 0 to MAX_DRAW_BUFFERS_ARB-1 175 176 177 Modify Section 3.11.3.4, Fragment Program Results 178 179 (modify Table X.3) 180 181 Binding Components Description 182 ----------------------------- ---------- ---------------------------- 183 result.color[n] (r,g,b,a) color n 184 result.depth (*,*,*,d) depth coordinate 185 186 Table X.3: Fragment Result Variable Bindings. Components labeled 187 "*" are unused. "[n]" is optional -- color <n> is used if 188 specified; color 0 is used otherwise. 189 190 (modify third paragraph) If a result variable binding matches 191 "result.color[n]", updates to the "x", "y", "z", and "w" components 192 of the result variable modify the "r", "g", "b", and "a" components, 193 respectively, of the fragment's corresponding output color. If 194 "result.color[n]" is not both bound by the fragment program and 195 written by some instruction of the program, the output color <n> of 196 the fragment program is undefined. 197 198 199 Add a new Section 3.11.4.5.3 (ARB_fragment_program) 200 201 3.11.4.5.3 Draw Buffers Program Option 202 203 If a fragment program specifies the "ARB_draw_buffers" option, 204 it will generate multiple output colors, and the result binding 205 "result.color[n]" is allowed, as described in section 3.11.3.4, 206 and with modified grammar rules as set forth in section 3.11.2. 207 If this option is not specified, a fragment program that attempts 208 to bind "result.color[n]" will fail to load, and only "result.color" 209 will be allowed. 210 211 212 Add a new section 3.11.6 (ARB_fragment_shader) 213 214 Section 3.11.6 Fragment Shader Output 215 216 The OpenGL Shading Language specification describes the values that 217 may be output by a fragment shader. These are gl_FragColor, 218 gl_FragData[n], and gl_FragDepth. If fragment color clamping is 219 enabled, the final fragment color values or the final fragment data 220 values written by a fragment shader are clamped to the range [0,1] 221 and then converted to fixed-point as described in section 2.13.9, 222 Final Color Processing. 223 224 The final fragment depth written by a fragment shader is first 225 clamped to [0,1] then converted to fixed-point as if it were a 226 window z value. See Section 2.10.1, Controlling the Viewport. Note 227 that the depth range computation is NOT applied here, only the 228 conversion to fixed-point. 229 230 The OpenGL Shading Language specification defines what happens when 231 color and/or depth are not written. Those rules are repeated here. 232 233 Writing to gl_FragColor specifies the fragment color that will be 234 used by the subsequent fixed functionality pipeline. If subsequent 235 fixed functionality consumes fragment color and an execution of a 236 fragment shader does not write a value to gl_FragColor then the 237 fragment color consumed is undefined. 238 239 Writing to gl_FragData[n] specifies the fragment data that will be 240 used by the subsequent fixed functionality pipeline. If subsequent 241 fixed functionality consumes fragment data and an execution of a 242 fragment shader does not write a value to gl_FragData[n] then the 243 fragment data consumed is undefined. 244 245 If a shader statically assigns a value to gl_FragColor, it may not 246 assign a value to gl_FragData[n]. If a shader statically writes a 247 value to gl_FragData[n], it may not assign a value to gl_FragColor. 248 That is, a shader may assign values to either gl_FragColor or 249 gl_FragData[n], but not both. 250 251 Writing to gl_FragDepth will establish the depth value for the 252 fragment being processed. If depth buffering is enabled, and a 253 shader does not write gl_FragDepth, then the fixed function value 254 for depth will be used as the fragment's depth value. If a shader 255 statically assigns a value to gl_FragDepth, and there is an 256 execution path through the shader that does not set gl_FragDepth, 257 then the value of the fragment's depth may be undefined for some 258 executions of the shader. That is, if a shader statically writes 259 gl_FragDepth, then it is responsible for always writing it. 260 261 Note, statically assigning a value to gl_FragColor, gl_FragData[n] 262 or gl_FragDepth means that there is a line of code in the fragment 263 shader source that writes a value to gl_FragColor, gl_FragData[n] 264 or gl_FragDepth, respectively, even if that line of code is never 265 executed. 266 267 268Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment 269Operations and the Frame Buffer) 270 271 272 Replace Section 4.2.1, Selecting a Buffer for Writing (p. 183) 273 274 4.2.1 Selecting Color Buffers for Writing 275 276 The first such operation is controlling the color buffers into 277 which each of the output colors are written. This is accomplished 278 with either DrawBuffer or DrawBuffersARB. 279 280 The command 281 282 void DrawBuffer(enum buf); 283 284 defines the set of color buffers to which output color 0 is written. 285 <buf> is a symbolic constant specifying zero, one, two, or four 286 buffers for writing. The constants are NONE, FRONT_LEFT, 287 FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, FRONT, BACK, LEFT, RIGHT, 288 FRONT_AND_BACK, and AUX0 through AUXn, where n + 1 is the number 289 of available auxiliary buffers. 290 291 The constants refer to the four potentially visible buffers front 292 left, front right, back left, and back right, and to the auxiliary 293 buffers. Arguments other than AUXi that omit reference to LEFT or 294 RIGHT refer to both left and right buffers. Arguments other than 295 AUXi that omit reference to FRONT or BACK refer to both front and 296 back buffers. AUXi enables drawing only to auxiliary buffer i. 297 Each AUXi adheres to AUXi = AUX0 + i. The constants and the buffers 298 they indicate are summarized in Table 4.3. If DrawBuffer is 299 supplied with a constant (other than NONE) that does not indicate 300 any of the color buffers allocated to the GL context, the error 301 INVALID_OPERATION results. 302 303 symbolic front front back back aux 304 constant left right left right i 305 -------- ----- ----- ---- ----- --- 306 NONE 307 FRONT_LEFT * 308 FRONT_RIGHT * 309 BACK_LEFT * 310 BACK_RIGHT * 311 FRONT * * 312 BACK * * 313 LEFT * * 314 RIGHT * * 315 FRONT_AND_BACK * * * * 316 AUXi * 317 318 Table 4.3: Arguments to DrawBuffer and the buffers that they 319 indicate. 320 321 322 DrawBuffer will set the draw buffer for output colors other than 0 323 to NONE. 324 325 The command 326 327 void DrawBuffersARB(sizei n, const enum *bufs); 328 329 defines the draw buffers to which all output colors are written. 330 <n> specifies the number of buffers in <bufs>. <bufs> is a pointer 331 to an array of symbolic constants specifying the buffer to which 332 each output color is written. The constants may be NONE, 333 FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, and AUX0 through 334 AUXn, where n + 1 is the number of available auxiliary buffers. The 335 draw buffers being defined correspond in order to the respective 336 output colors. The draw buffer for output colors beyond <n> is set 337 to NONE. 338 339 Except for NONE, a buffer should not appear more then once in the 340 array pointed to by <bufs>. Specifying a buffer more then once 341 will result in the error INVALID_OPERATION. 342 343 If a fragment program is not using the "ARB_draw_buffers" option, 344 DrawBuffersARB specifies a set of draw buffers into which output 345 color 0 is written. 346 347 If a fragment shader writes to "gl_FragColor", DrawBuffersARB 348 specifies a set of draw buffers into which the color written to 349 "gl_FragColor" is written. 350 351 The maximum number of draw buffers is implementation dependent and 352 must be at least 1. The number of draw buffers supported can 353 be queried with the state MAX_DRAW_BUFFERS_ARB. 354 355 The constants FRONT, BACK, LEFT, RIGHT, and FRONT_AND_BACK that 356 refer to multiple buffers are not valid for use in DrawBuffersARB 357 and will result in the error INVALID_OPERATION. 358 359 If DrawBuffersARB is supplied with a constant (other than NONE) 360 that does not indicate any of the color buffers allocated to 361 the GL context, the error INVALID_OPERATION will be generated. If 362 <n> is greater than MAX_DRAW_BUFFERS_ARB, the error 363 INVALID_OPERATION will be generated. 364 365 Indicating a buffer or buffers using DrawBuffer or DrawBuffersARB 366 causes subsequent pixel color value writes to affect the indicated 367 buffers. If more than one color buffer is selected for drawing, 368 blending and logical operations are computed and applied 369 independently for each buffer. If there are multiple output colors 370 being written to multiple buffers, the alpha used in alpha to 371 coverage and alpha test is the alpha of output color 0. 372 373 Specifying NONE as the draw buffer for an output color will inhibit 374 that output color from being written to any buffer. 375 376 Monoscopic contexts include only left buffers, while stereoscopic 377 contexts include both left and right buffers. Likewise, single 378 buffered contexts include only front buffers, while double buffered 379 contexts include both front and back buffers. The type of context 380 is selected at GL initialization. 381 382 The state required to handle color buffer selection is an integer 383 for each supported output color. In the initial state, draw buffer 384 for output color 0 is FRONT if there are no back buffers; otherwise 385 it is BACK. The initial state of draw buffers for output colors 386 other then 0 is NONE. 387 388 389Additions to Chapter 5 of the OpenGL 1.5 Specification (Special 390Functions) 391 392 None 393 394 395Additions to Chapter 6 of the OpenGL 1.5 Specification (State and 396State Requests) 397 398 None 399 400 401Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification 402(Basics) 403 404 Add a new Section 3.3.1, GL_ARB_draw_buffers Extension (p. 13) 405 406 3.3.1 GL_ARB_draw_buffers Extension 407 408 To use the GL_ARB_draw_buffers extension in a shader it must be 409 enabled using the #extension directive. 410 411 The shading language preprocessor #define GL_ARB_draw_buffers will 412 be defined to 1, if the GL_ARB_draw_buffers extension is supported. 413 414 415Dependencies on ARB_fragment_program 416 417 If ARB_fragment_program is not supported then all changes to 418 section 3.11 of ARB_fragment_program and the fragment program 419 specific part of section 4.2.1 are removed. 420 421 422Dependencies on ARB_fragment_shader 423 424 If ARB_fragment_shader is not supported then all changes to 425 section 3.11 of ARB_fragment_shader, section 3.3.1 of the Shading 426 Language Specification, and the fragment shader specific part of 427 section 4.2.1 are removed. 428 429 430Interactions with possible future extensions 431 432 If there is some other future extension that defines multiple 433 color outputs then this extension and glDrawBuffersARB could be 434 used to define the destinations for those outputs. This extension 435 need not be used only with ARB_fragment_program. 436 437GLX Protocol 438 439 The following rendering command is potentially large, and hence can 440 be sent in a glxRender or glxRenderLarge request. 441 442 DrawBuffersARB 443 2 8+(4*n) rendering command length 444 2 233 rendering command opcode 445 4 CARD32 n 446 n*4 LISTofCARD32 list of draw buffers 447 448 If the command is encoded in a glxRenderLarge request, the command 449 opcode and command length fields above are expanded to 4 bytes each: 450 451 4 12+(4*n) rendering command length 452 4 233 rendering command opcode 453 454Errors 455 456 The error INVALID_OPERATION is generated by DrawBuffersARB if a 457 color buffer not currently allocated to the GL context is specified. 458 459 The error INVALID_OPERATION is generated by DrawBuffersARB if <n> 460 is greater than the state MAX_DRAW_BUFFERS_ARB. 461 462 The error INVALID_OPERATION is generated by DrawBuffersARB if value 463 in <bufs> does not correspond to one of the allowed buffers. 464 465 The error INVALID_OPERATION is generated by DrawBuffersARB if a draw 466 buffer other then NONE is specified more then once in <bufs>. 467 468 469New State 470 471 (table 6.19, p227) add the following entry: 472 473 Get Value Type Get Command Initial Value Description Section Attribute 474 ------------------------------- ------ ------------- ------------- -------------------- ------------ ------------ 475 DRAW_BUFFERi_ARB Z10* GetIntegerv see 4.2.1 Draw buffer selected 4.2.1 color-buffer 476 for output color i 477 478 479New Implementation Dependent State 480 481 Get Value Type Get Command Minimum Value Description Sec. Attribute 482 --------- ---- ----------- ------------- ------------------- ----- --------- 483 MAX_DRAW_BUFFERS_ARB Z+ GetIntegerv 1 Maximum number of 4.2.1 - 484 active draw buffers 485 486 487Revision History 488 489 Date: 2/19/2008 490 Revision: 17 (Mark Kilgard, NVIDIA) 491 - Updated contact 492 493 Date: 11/4/2006 494 Revision: 16 (Benj Lipchak, AMD) 495 - Updated contact info after ATI/AMD merger. 496 497 Date: 12/13/2004 498 Revision: 15 (Ian Romanick, IBM) 499 - Added GLX protocol. 500 501 Date: 7/26/2004 502 Revision: 14 503 - Clarified interaction of gl_FragColor and multiple draw buffers. 504 - Updated dependencies section. 505 - Added real ARB extension #. 506 507 Date: 7/22/2004 508 Revision: 13 509 - Converted from ATI_draw_buffers to ARB_draw_buffers. 510 511 Date: 7/21/2004 512 Revision: 12 513 - Updated intro to mention ARB_fragment_shader. 514 - Marked which sections modify ARB_fragment_program and 515 ARB_fragment_shader. 516 - Added "Dependencies on ARB_fragment_shader". 517 - Added extension section 3.3.1 to Shading Language spec. 518 - Resolved interaction with multisample (issue 2). 519 - Fixed typos. 520 521 Date: 6/9/2004 522 Revision: 11 523 - Added GLSL integration. 524 525 Date: 4/27/2004 526 Revision: 10 527 - Replaced modification to section 4.2.1 with a complete 528 replacement for the section, the individual modifications were 529 getting too cumbersome. 530 - Added issue (2) on multisampling. 531 532 Date: 4/15/2004 533 Revision: 9 534 - Specified that it is the alpha of color 0 that is used for alpha 535 test. 536 537 Date: 12/30/2002 538 Revision: 8 539 - Clarified that DrawBuffersATI will set the set of draw buffers 540 to write color output 0 to when the "ATI_draw_buffer" fragments 541 program option is not in use. 542 543 Date: 9/27/2002 544 Revision: 7 545 - Fixed confusion between meaning of color buffer and draw buffer 546 in last revision. 547 - Fixed mistake in when an error is generated based on the <n> 548 argument of DrawBuffersATI. 549 550 Date: 9/26/2002 551 Revision: 6 552 - Cleaned up and put in sync with latest ARB_fragment_program 553 revision (#22). Some meaningless changes made just in the name 554 of consistency. 555 556 Date: 9/11/2002 557 Revision: 5 558 - Added section 3.11.4.5.3. 559 - Added enum numbers to New Tokens. 560 561 Date: 9/9/2002 562 Revision: 4 563 - Changed error from MAX_OUTPUT_COLORS to MAX_DRAW_BUFFERS_ATI. 564 - Changed 3.10 section numbers to 3.11 to match change to 565 ARB_fragment_program spec. 566 - Changed ARB_fragment_program from required to affects, and 567 added section on interactions with it and future extensions 568 that define multiple color outputs. 569 570 Date: 9/6/2002 571 Revision: 3 572 - Changed error to INVALID OPERATION. 573 - Cleaned up typos. 574 575 Date: 8/19/2002 576 Revision: 2 577 - Added a paragraph that specifically points out that the 578 constants that refer to multiple buffers are not allowed with 579 DrawBuffersATI. 580 - Changed bufs to <bufs> in a couple of places. 581 582 Date: 8/16/2002 583 Revision: 1 584 - First draft for circulation. 585