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