Back to the OpenGL extension cross reference
GL_ARB_draw_buffers
ARB_draw_buffers
Name Strings
GL_ARB_draw_buffers
Contributors
Benj Lipchak, ATI
Bill Licea-Kane, ATI
Contact
Rob Mace, ATI Research (mace 'at' ati.com)
IP Status
No known IP issues.
Status
Complete. Approved by the ARB on July 23, 2004.
Version
Last Modified Date: December 13, 2004
Revision: 15
Number
ARB Extension #37
Dependencies
The extension is written against the OpenGL 1.5 Specification.
OpenGL 1.3 is required.
ARB_fragment_program affects the definition of this extension.
ARB_fragment_shader affects the definition of this extension.
Overview
This extension extends ARB_fragment_program and ARB_fragment_shader
to allow multiple output colors, and provides a mechanism for
directing those outputs to multiple color buffers.
Issues
(1) How many GL_DRAW_BUFFER#_ARB enums should be reserved?
RESOLVED: We only need 4 currently, but for future expandability
it would be nice to keep the enums in sequence. We'll specify
16 for now, which will be more than enough for a long time.
(2) How should multisample work when there are multiple output
colors being rendered to multiple draw buffers?
Basic options are:
(a) Color 0 is written to the multisample buffer and then the
multisample buffer is resolved to all the color buffers.
This option would be consistent with GL's idea of a single
multisample buffer, but would be really useless and defeat
the purpose of multiple output colors.
(b) Have a separate multisample color buffer for each output
color/draw buffer. This would be useful but would all
implementations be able to handle it?
(c) Don't allow multiple output colors and multisampling to
be combined by restricting MAX_DRAW_BUFFERS_ARB to 1
for contexts with multisample buffers. This is simple
and would allow a future extension to allow (b).
RESOLUTION: (b) and (c). Samples will contain separate color
values for each output color. Implementations that can not
support this can restrict MAX_DRAW_BUFFERS_ARB to 1 for contexts
with multisample buffers.
(3) Should gl_FragColor be aliased to gl_FragData[0]?
RESOLUTION: No. A shader should write either gl_FragColor, or
gl_FragData[n], but not both.
Writing to gl_FragColor will write to all draw buffers specified
with DrawBuffersARB.
(4) Should gl_FragData[n] be clamped?
RESOLUTION: They will be clamped if fragment color clamping is
enabled.
void DrawBuffersARB(sizei n, const enum *bufs);
Accepted by the <pname> parameters of GetIntegerv, GetFloatv,
and GetDoublev:
MAX_DRAW_BUFFERS_ARB 0x8824
DRAW_BUFFER0_ARB 0x8825
DRAW_BUFFER1_ARB 0x8826
DRAW_BUFFER2_ARB 0x8827
DRAW_BUFFER3_ARB 0x8828
DRAW_BUFFER4_ARB 0x8829
DRAW_BUFFER5_ARB 0x882A
DRAW_BUFFER6_ARB 0x882B
DRAW_BUFFER7_ARB 0x882C
DRAW_BUFFER8_ARB 0x882D
DRAW_BUFFER9_ARB 0x882E
DRAW_BUFFER10_ARB 0x882F
DRAW_BUFFER11_ARB 0x8830
DRAW_BUFFER12_ARB 0x8831
DRAW_BUFFER13_ARB 0x8832
DRAW_BUFFER14_ARB 0x8833
DRAW_BUFFER15_ARB 0x8834
Additions to Chapter 2 of the OpenGL 1.5 Specification (OpenGL
Operation)
None
Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
Modify Section 3.2.1, Multisampling (p. 71)
(replace the second paragraph with)
An additional buffer, called the multisample buffer, is added to the
framebuffer. Pixel sample values, including color, depth, and
stencil values, are stored in this buffer. Samples contain separate
color values for each output color. When the framebuffer includes a
multisample buffer, it does not include depth or stencil buffers,
even if the multisample buffer does not store depth or stencil
values. Color buffers (left, right, front, back, and aux) do coexist
with the multisample buffer, however.
Modify Section 3.11.2, Fragment Program Grammar and Semantic
Restrictions (ARB_fragment_program)
(replace <resultBinding> grammar rule with these rules)
<resultBinding> ::= "result" "." "color" <optOutputColorNum>
| "result" "." "depth"
<optOutputColorNum> ::= ""
| "[" <outputColorNum> "]"
<outputColorNum> ::= <integer> from 0 to MAX_DRAW_BUFFERS_ARB-1
Modify Section 3.11.3.4, Fragment Program Results
(modify Table X.3)
Binding Components Description
----------------------------- ---------- ----------------------------
result.color[n] (r,g,b,a) color n
result.depth (*,*,*,d) depth coordinate
Table X.3: Fragment Result Variable Bindings. Components labeled
"*" are unused. "[n]" is optional -- color <n> is used if
specified; color 0 is used otherwise.
(modify third paragraph) If a result variable binding matches
"result.color[n]", updates to the "x", "y", "z", and "w" components
of the result variable modify the "r", "g", "b", and "a" components,
respectively, of the fragment's corresponding output color. If
"result.color[n]" is not both bound by the fragment program and
written by some instruction of the program, the output color <n> of
the fragment program is undefined.
Add a new Section 3.11.4.5.3 (ARB_fragment_program)
3.11.4.5.3 Draw Buffers Program Option
If a fragment program specifies the "ARB_draw_buffers" option,
it will generate multiple output colors, and the result binding
"result.color[n]" is allowed, as described in section 3.11.3.4,
and with modified grammar rules as set forth in section 3.11.2.
If this option is not specified, a fragment program that attempts
to bind "result.color[n]" will fail to load, and only "result.color"
will be allowed.
Add a new section 3.11.6 (ARB_fragment_shader)
Section 3.11.6 Fragment Shader Output
The OpenGL Shading Language specification describes the values that
may be output by a fragment shader. These are gl_FragColor,
gl_FragData[n], and gl_FragDepth. If fragment color clamping is
enabled, the final fragment color values or the final fragment data
values written by a fragment shader are clamped to the range [0,1]
and then converted to fixed-point as described in section 2.13.9,
Final Color Processing.
The final fragment depth written by a fragment shader is first
clamped to [0,1] then converted to fixed-point as if it were a
window z value. See Section 2.10.1, Controlling the Viewport. Note
that the depth range computation is NOT applied here, only the
conversion to fixed-point.
The OpenGL Shading Language specification defines what happens when
color and/or depth are not written. Those rules are repeated here.
Writing to gl_FragColor specifies the fragment color that will be
used by the subsequent fixed functionality pipeline. If subsequent
fixed functionality consumes fragment color and an execution of a
fragment shader does not write a value to gl_FragColor then the
fragment color consumed is undefined.
Writing to gl_FragData[n] specifies the fragment data that will be
used by the subsequent fixed functionality pipeline. If subsequent
fixed functionality consumes fragment data and an execution of a
fragment shader does not write a value to gl_FragData[n] then the
fragment data consumed is undefined.
If a shader statically assigns a value to gl_FragColor, it may not
assign a value to gl_FragData[n]. If a shader statically writes a
value to gl_FragData[n], it may not assign a value to gl_FragColor.
That is, a shader may assign values to either gl_FragColor or
gl_FragData[n], but not both.
Writing to gl_FragDepth will establish the depth value for the
fragment being processed. If depth buffering is enabled, and a
shader does not write gl_FragDepth, then the fixed function value
for depth will be used as the fragment's depth value. If a shader
statically assigns a value to gl_FragDepth, and there is an
execution path through the shader that does not set gl_FragDepth,
then the value of the fragment's depth may be undefined for some
executions of the shader. That is, if a shader statically writes
gl_FragDepth, then it is responsible for always writing it.
Note, statically assigning a value to gl_FragColor, gl_FragData[n]
or gl_FragDepth means that there is a line of code in the fragment
shader source that writes a value to gl_FragColor, gl_FragData[n]
or gl_FragDepth, respectively, even if that line of code is never
executed.
Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
Operations and the Frame Buffer)
Replace Section 4.2.1, Selecting a Buffer for Writing (p. 183)
4.2.1 Selecting Color Buffers for Writing
The first such operation is controlling the color buffers into
which each of the output colors are written. This is accomplished
with either DrawBuffer or DrawBuffersARB.
The command
void DrawBuffer(enum buf);
defines the set of color buffers to which output color 0 is written.
<buf> is a symbolic constant specifying zero, one, two, or four
buffers for writing. The constants are NONE, FRONT_LEFT,
FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, FRONT, BACK, LEFT, RIGHT,
FRONT_AND_BACK, and AUX0 through AUXn, where n + 1 is the number
of available auxiliary buffers.
The constants refer to the four potentially visible buffers front
left, front right, back left, and back right, and to the auxiliary
buffers. Arguments other than AUXi that omit reference to LEFT or
RIGHT refer to both left and right buffers. Arguments other than
AUXi that omit reference to FRONT or BACK refer to both front and
back buffers. AUXi enables drawing only to auxiliary buffer i.
Each AUXi adheres to AUXi = AUX0 + i. The constants and the buffers
they indicate are summarized in Table 4.3. If DrawBuffer is
supplied with a constant (other than NONE) that does not indicate
any of the color buffers allocated to the GL context, the error
INVALID_OPERATION results.
symbolic front front back back aux
constant left right left right i
-------- ----- ----- ---- ----- ---
NONE
FRONT_LEFT *
FRONT_RIGHT *
BACK_LEFT *
BACK_RIGHT *
FRONT * *
BACK * *
LEFT * *
RIGHT * *
FRONT_AND_BACK * * * *
AUXi *
Table 4.3: Arguments to DrawBuffer and the buffers that they
indicate.
DrawBuffer will set the draw buffer for output colors other than 0
to NONE.
The command
void DrawBuffersARB(sizei n, const enum *bufs);
defines the draw buffers to which all output colors are written.
<n> specifies the number of buffers in <bufs>. <bufs> is a pointer
to an array of symbolic constants specifying the buffer to which
each output color is written. The constants may be NONE,
FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, and AUX0 through
AUXn, where n + 1 is the number of available auxiliary buffers. The
draw buffers being defined correspond in order to the respective
output colors. The draw buffer for output colors beyond <n> is set
to NONE.
Except for NONE, a buffer should not appear more then once in the
array pointed to by <bufs>. Specifying a buffer more then once
will result in the error INVALID_OPERATION.
If a fragment program is not using the "ARB_draw_buffers" option,
DrawBuffersARB specifies a set of draw buffers into which output
color 0 is written.
If a fragment shader writes to "gl_FragColor", DrawBuffersARB
specifies a set of draw buffers into which the color written to
"gl_FragColor" is written.
The maximum number of draw buffers is implementation dependent and
must be at least 1. The number of draw buffers supported can
be queried with the state MAX_DRAW_BUFFERS_ARB.
The constants FRONT, BACK, LEFT, RIGHT, and FRONT_AND_BACK that
refer to multiple buffers are not valid for use in DrawBuffersARB
and will result in the error INVALID_OPERATION.
If DrawBuffersARB is supplied with a constant (other than NONE)
that does not indicate any of the color buffers allocated to
the GL context, the error INVALID_OPERATION will be generated. If
<n> is greater than MAX_DRAW_BUFFERS_ARB, the error
INVALID_OPERATION will be generated.
Indicating a buffer or buffers using DrawBuffer or DrawBuffersARB
causes subsequent pixel color value writes to affect the indicated
buffers. If more than one color buffer is selected for drawing,
blending and logical operations are computed and applied
independently for each buffer. If there are multiple output colors
being written to multiple buffers, the alpha used in alpha to
coverage and alpha test is the alpha of output color 0.
Specifying NONE as the draw buffer for an output color will inhibit
that output color from being written to any buffer.
Monoscopic contexts include only left buffers, while stereoscopic
contexts include both left and right buffers. Likewise, single
buffered contexts include only front buffers, while double buffered
contexts include both front and back buffers. The type of context
is selected at GL initialization.
The state required to handle color buffer selection is an integer
for each supported output color. In the initial state, draw buffer
for output color 0 is FRONT if there are no back buffers; otherwise
it is BACK. The initial state of draw buffers for output colors
other then 0 is NONE.
Additions to Chapter 5 of the OpenGL 1.5 Specification (Special
Functions)
None
Additions to Chapter 6 of the OpenGL 1.5 Specification (State and
State Requests)
None
Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification
(Basics)
Add a new Section 3.3.1, GL_ARB_draw_buffers Extension (p. 13)
3.3.1 GL_ARB_draw_buffers Extension
To use the GL_ARB_draw_buffers extension in a shader it must be
enabled using the #extension directive.
The shading language preprocessor #define GL_ARB_draw_buffers will
be defined to 1, if the GL_ARB_draw_buffers extension is supported.
Dependencies on ARB_fragment_program
If ARB_fragment_program is not supported then all changes to
section 3.11 of ARB_fragment_program and the fragment program
specific part of section 4.2.1 are removed.
Dependencies on ARB_fragment_shader
If ARB_fragment_shader is not supported then all changes to
section 3.11 of ARB_fragment_shader, section 3.3.1 of the Shading
Language Specification, and the fragment shader specific part of
section 4.2.1 are removed.
Interactions with possible future extensions
If there is some other future extension that defines multiple
color outputs then this extension and glDrawBuffersARB could be
used to define the destinations for those outputs. This extension
need not be used only with ARB_fragment_program.
GLX Protocol
The following rendering command is potentially large, and hence can
be sent in a glxRender or glxRenderLarge request.
DrawBuffersARB
2 8+(4*n) rendering command length
2 233 rendering command opcode
4 CARD32 n
n*4 LISTofCARD32 list of draw buffers
If the command is encoded in a glxRenderLarge request, the command
opcode and command length fields above are expanded to 4 bytes each:
4 12+(4*n) rendering command length
4 233 rendering command opcode
Errors
The error INVALID_OPERATION is generated by DrawBuffersARB if a
color buffer not currently allocated to the GL context is specified.
The error INVALID_OPERATION is generated by DrawBuffersARB if <n>
is greater than the state MAX_DRAW_BUFFERS_ARB.
The error INVALID_OPERATION is generated by DrawBuffersARB if value
in <bufs> does not correspond to one of the allowed buffers.
The error INVALID_OPERATION is generated by DrawBuffersARB if a draw
buffer other then NONE is specified more then once in <bufs>.
New State
(table 6.19, p227) add the following entry:
Get Value Type Get Command Initial Value Description Section Attribute
------------------------------- ------ ------------- ------------- -------------------- ------------ ------------
DRAW_BUFFERi_ARB Z10* GetIntegerv see 4.2.1 Draw buffer selected 4.2.1 color-buffer
for output color i
New Implementation Dependent State
Get Value Type Get Command Minimum Value Description Sec. Attribute
--------- ---- ----------- ------------- ------------------- ----- ---------
MAX_DRAW_BUFFERS_ARB Z+ GetIntegerv 1 Maximum number of 4.2.1 -
active draw buffers
Revision History
Date: 12/13/2004
Revision: 15 (Ian Romanick, IBM)
- Added GLX protocol.
Date: 7/26/2004
Revision: 14
- Clarified interaction of gl_FragColor and multiple draw buffers.
- Updated dependencies section.
- Added real ARB extension #.
Date: 7/22/2004
Revision: 13
- Converted from ATI_draw_buffers to ARB_draw_buffers.
Date: 7/21/2004
Revision: 12
- Updated intro to mention ARB_fragment_shader.
- Marked which sections modify ARB_fragment_program and
ARB_fragment_shader.
- Added "Dependencies on ARB_fragment_shader".
- Added extension section 3.3.1 to Shading Language spec.
- Resolved interaction with multisample (issue 2).
- Fixed typos.
Date: 6/9/2004
Revision: 11
- Added GLSL integration.
Date: 4/27/2004
Revision: 10
- Replaced modification to section 4.2.1 with a complete
replacement for the section, the individual modifications were
getting too cumbersome.
- Added issue (2) on multisampling.
Date: 4/15/2004
Revision: 9
- Specified that it is the alpha of color 0 that is used for alpha
test.
Date: 12/30/2002
Revision: 8
- Clarified that DrawBuffersATI will set the set of draw buffers
to write color output 0 to when the "ATI_draw_buffer" fragments
program option is not in use.
Date: 9/27/2002
Revision: 7
- Fixed confusion between meaning of color buffer and draw buffer
in last revision.
- Fixed mistake in when an error is generated based on the <n>
argument of DrawBuffersATI.
Date: 9/26/2002
Revision: 6
- Cleaned up and put in sync with latest ARB_fragment_program
revision (#22). Some meaningless changes made just in the name
of consistency.
Date: 9/11/2002
Revision: 5
- Added section 3.11.4.5.3.
- Added enum numbers to New Tokens.
Date: 9/9/2002
Revision: 4
- Changed error from MAX_OUTPUT_COLORS to MAX_DRAW_BUFFERS_ATI.
- Changed 3.10 section numbers to 3.11 to match change to
ARB_fragment_program spec.
- Changed ARB_fragment_program from required to affects, and
added section on interactions with it and future extensions
that define multiple color outputs.
Date: 9/6/2002
Revision: 3
- Changed error to INVALID OPERATION.
- Cleaned up typos.
Date: 8/19/2002
Revision: 2
- Added a paragraph that specifically points out that the
constants that refer to multiple buffers are not allowed with
DrawBuffersATI.
- Changed bufs to <bufs> in a couple of places.
Date: 8/16/2002
Revision: 1
- First draft for circulation.
Implementation Support
List of OpenGL implementations supporting the GL_ARB_draw_buffers extension
Original File
Original text file for the GL_ARB_draw_buffers extension
Page generated on Sun Nov 20 18:37:05 2005