• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    NV_draw_buffers
4
5Name Strings
6
7    GL_NV_draw_buffers
8
9Contact
10
11    Greg Roth, NVIDIA Corporation (groth 'at' nvidia.com)
12
13Contributors
14
15     Benj Lipchak, AMD
16     Bill Licea-Kane, AMD
17     Rob Mace, NVIDIA Corporation
18     James Helferty, NVIDIA Corporation
19
20Status
21
22    Complete.
23
24Version
25
26    Last Modified Date: July 11, 2013
27    NVIDIA Revision: 4.0
28
29Number
30
31    OpenGL ES Extension #91
32
33Dependencies
34
35    Written against the OpenGL ES 2.0 Specification and the OpenGL ES
36    Shader Language 1.0.14 Specification.
37
38    This extension interacts with the OpenGL ES 3.0 Specification
39
40Overview
41
42    This extension extends OpenGL ES 2.0 to allow multiple output
43    colors, and provides a mechanism for directing those outputs to
44    multiple color buffers.
45
46    This extension serves a similar purpose to ARB_draw_buffers except
47    that this is for OpenGL ES 2.0.
48
49    When OpenGL ES 3.0 is present, this extension relaxes the order
50    restriction on color attachments to draw framebuffer objects.
51
52IP Status
53
54    NVIDIA Proprietary
55
56New Procedures and Functions
57
58    void DrawBuffersNV(sizei n, const enum *bufs);
59
60New Tokens
61
62    Accepted by the <pname> parameters of GetIntegerv, GetFloatv,
63    and GetDoublev:
64
65        MAX_DRAW_BUFFERS_NV                     0x8824
66        DRAW_BUFFER0_NV                         0x8825
67        DRAW_BUFFER1_NV                         0x8826
68        DRAW_BUFFER2_NV                         0x8827
69        DRAW_BUFFER3_NV                         0x8828
70        DRAW_BUFFER4_NV                         0x8829
71        DRAW_BUFFER5_NV                         0x882A
72        DRAW_BUFFER6_NV                         0x882B
73        DRAW_BUFFER7_NV                         0x882C
74        DRAW_BUFFER8_NV                         0x882D
75        DRAW_BUFFER9_NV                         0x882E
76        DRAW_BUFFER10_NV                        0x882F
77        DRAW_BUFFER11_NV                        0x8830
78        DRAW_BUFFER12_NV                        0x8831
79        DRAW_BUFFER13_NV                        0x8832
80        DRAW_BUFFER14_NV                        0x8833
81        DRAW_BUFFER15_NV                        0x8834
82
83
84    Accepted by the <bufs> parameter of DrawBuffersNV:
85
86        COLOR_ATTACHMENT0_NV                    0x8CE0
87        COLOR_ATTACHMENT1_NV                    0x8CE1
88        COLOR_ATTACHMENT2_NV                    0x8CE2
89        COLOR_ATTACHMENT3_NV                    0x8CE3
90        COLOR_ATTACHMENT4_NV                    0x8CE4
91        COLOR_ATTACHMENT5_NV                    0x8CE5
92        COLOR_ATTACHMENT6_NV                    0x8CE6
93        COLOR_ATTACHMENT7_NV                    0x8CE7
94        COLOR_ATTACHMENT8_NV                    0x8CE8
95        COLOR_ATTACHMENT9_NV                    0x8CE9
96        COLOR_ATTACHMENT10_NV                   0x8CEA
97        COLOR_ATTACHMENT11_NV                   0x8CEB
98        COLOR_ATTACHMENT12_NV                   0x8CEC
99        COLOR_ATTACHMENT13_NV                   0x8CED
100        COLOR_ATTACHMENT14_NV                   0x8CEE
101        COLOR_ATTACHMENT15_NV                   0x8CEF
102
103
104Changes to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
105
106    Section 3.2, (Multisampling). Replace the second paragraph:
107
108    An additional buffer, called the multisample buffer, is added to the
109    framebuffer. Pixel sample values, including color, depth, and
110    stencil values, are stored in this buffer. Samples contain separate
111    color values for each fragment color. When the framebuffer includes
112    a multisample buffer, it does not include depth or stencil buffers,
113    even if the multisample buffer does not store depth or stencil
114    values. The color buffer does coexist with the multisample buffer,
115    however.
116
117    Section 3.8.2, (Shader Execution) Replace subsection "Shader
118    Outputs":
119
120    The OpenGL ES Shading Language specification describes the values
121    that may be output by a fragment shader. These are gl_FragColor and
122    gl_FragData[n].  The final fragment color values or the final
123    fragment data values written by a fragment shader are clamped to the
124    range [0, 1] and then converted to fixed-point as described in
125    section 2.1.2 for framebuffer color components.
126
127    Writing to gl_FragColor specifies the fragment color (color number
128    zero) that will be used by subsequent stages of the pipeline.
129    Writing to gl_FragData[n] specifies the value of fragment color
130    number n. Any colors, or color components, associated with a
131    fragment that are not written by the fragment shader are undefined.
132    A fragment shader may not statically assign values to both
133    gl_FragColor and gl_FragData. In this case, a compile or link error
134    will result. A shader statically assigns a value to a variable if,
135    after preprocessing, it contains a statement that would write to the
136    variable, whether or not run-time flow of control will cause that
137    statement to be executed.
138
139Changes to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
140Operations and the Frame Buffer)
141
142    Replace Section 4.2.1, "Selecting a Buffer for Writing"
143
144    By default, color values are written into the front buffer for
145    single buffered surfaces or into the back buffer for back buffered
146    surfaces as determined when making the context current. To control
147    the color buffer into which each of the fragment color values is
148    written, DrawBuffersNV is used.
149
150    The command
151
152      void DrawBuffersNV(sizei n, const enum *bufs);
153
154    defines the draw buffers to which all fragment colors are written.
155    <n> specifies the number of buffers in <bufs>. <bufs> is a pointer
156    to an array of symbolic constants specifying the buffer to which
157    each fragment color is written.
158
159    Each buffer listed in <bufs> must be NONE, COLOR_ATTACHMENT0, or
160    COLOR_ATTACHMENTi_NV, where <i> is the index of the color attachment
161    point. Otherwise, an INVALID_ENUM error is generated. DrawBuffersNV
162    may only be called when the GL is bound to a framebuffer object. If
163    called when the GL is bound to the default framebuffer, an INVALID_-
164    OPERATION error is generated.
165
166    The draw buffers being defined correspond in order to the respective
167    fragment colors. The draw buffer for fragment colors beyond <n> is
168    set to NONE.
169
170    The maximum number of draw buffers is implementation dependent and
171    must be at least 1. The number of draw buffers supported can be
172    queried by calling GetIntegerv with the symbolic constant
173    MAX_DRAW_BUFFERS_NV. An INVALID_VALUE error is generated if <n> is
174    less than one or greater than MAX_DRAW_BUFFERS_NV.
175
176    Except for NONE, a buffer may not appear more then once in the array
177    pointed to by <bufs>. Specifying a buffer more then once will result
178    in the error INVALID_OPERATION.
179
180    If a fragment shader writes to "gl_FragColor", DrawBuffersNV
181    specifies a set of draw buffers into which the color written to
182    "gl_FragColor" is written. If a fragment shader writes to
183    gl_FragData, DrawBuffers specifies a set of draw buffers into which
184    each of the multiple output colors defined by these variables are
185    separately written. If a fragment shader writes to neither
186    gl_FragColor nor gl_FragData the values of the fragment colors
187    following shader execution are undefined, and may differ for each
188    fragment color.
189
190    If DrawBuffersNV is supplied with a constant COLOR_ATTACHMENT<m>
191    where <m> is greater than or equal to the value of
192    MAX_COLOR_ATTACHMENTS_NV, then the error INVALID_OPERATION results.
193
194    Indicating a buffer or buffers using DrawBuffersNV causes subsequent
195    pixel color value writes to affect the indicated buffers. If the GL is
196    bound to a draw framebuffer object and a draw buffer selects an attachment
197    that has no image attached, then that fragment color is not written.
198
199    Specifying NONE as the draw buffer for a fragment color will inhibit
200    that fragment color from being written to any buffer.
201
202    The state required to handle color buffer selection is an integer
203    for each supported fragment color.  For each framebuffer object, the
204    initial state of the draw buffer for fragment color zero is COLOR_-
205    ATTACHMENT0 and the initial state of draw buffers for fragment
206    colors other than zero is NONE.
207
208    The value of the draw buffer selected for fragment color <i> can be
209    queried by calling GetIntegerv with the symbolic constant
210    DRAW_BUFFER<i>_NV.
211
212Changes to Chapter 3 of the OpenGL Shading Language 1.0 Specification (Basics)
213
214    Add a new section:
215
216    3.3.1 GL_NV_draw_buffers Extension
217
218    To use the GL_NV_draw_buffers extension in a shader it must be
219    enabled using the #extension directive.
220
221    The shading language preprocessor #define GL_NV_draw_buffers will be
222    defined to 1, if the GL_NV_draw_buffers extension is supported.
223
224Interactions with OpenGL ES 3.0
225
226    Section 4.2.1 of OpenGL ES 3.0, (Selecting a Buffer for Writing). Replace
227    the eighth and ninth paragraph:
228
229    If the GL is bound to a draw framebuffer object, the ith buffer listed in
230    bufs must be COLOR_ATTACHMENTm or NONE, where m is less than the value of
231    MAX_COLOR_ATTACHMENTS. Specifying BACK or COLOR_ATTACHMENTm where m is
232    greater than or equal to MAX_COLOR_ATTACHMENTS will generate the error
233    INVALID_OPERATION.
234
235    If an OpenGL ES Shading Language 1.00 or 3.00 fragment shader writes a
236    user-defined varying out variable, DrawBuffers specifies a set of draw
237    buffers into which each of the multiple output colors defined by these
238    variables are separately written. If a fragment shader writes to none of
239    gl_FragColor, gl_FragData, nor any user-defined output variables, the
240    values of the fragment colors following shader execution are undefined, and
241    may differ for each fragment color. If some, but not all user-defined
242    output variables are written, the values of fragment colors corresponding
243    to unwritten variables are similarly undefined.
244
245New State
246
247    Add Table 6.X Framebuffer (State per framebuffer object):
248
249        State           Type  Get Command Initial Value Description
250        --------------- ---- ------------ ------------- -----------
251        DRAW_BUFFERi_NV Z10* GetIntegerv  see 4.2.1     Draw buffer selected
252                                                        for fragment color i
253
254    Add the new Table 6.X "Framebuffer Dependent Values" :
255
256        State               Type Get Command Min Value Description
257        ------------------- ---- ----------- --------- -----------
258        MAX_DRAW_BUFFERS_NV  Z+  GetIntegerv 1         Maximum number of
259                                                       active draw buffers
260
261Issues
262
263    1. What behavior should be expected if a draw buffer selects an attachment
264       for a draw framebuffer that has no image attached?
265
266      Early drivers considered this an INVALID_OPERATION and the DrawBuffersNV
267      operation did not succeed. (Following precedent set in Issue 55 of
268      EXT_framebuffer_object)
269
270      OpenGL ES 3.0 and Desktop GL 4.3 consider this legal, and the DrawBuffers
271      call succeeds. Missing attachments are simply not written to.
272
273      RESOLVED: Behavior should match OpenGL ES 3.0. Application developers are
274      cautioned that early Tegra drivers may exhibit the previous behavior.
275
276    See ARB_draw_buffers for additional relevant issues.
277
278Revision History
279
280    Rev.    Date      Author       Changes
281    ----   --------   ---------    ------------------------------------
282     4     07/11/13   jhelferty    Updated error behavior for missing
283                                   attachments to match ES 3.0.
284                                   Clarified ES 3.0 interactions.
285     3     06/07/11   groth        Clarified default behavior, state tables.
286     2     04/26/11   groth        Filled in many missing elements.
287     1     03/03/08   kashida      First revision based on
288                                   ARB_draw_buffers.
289