1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>
<!-- Converted by db4-upgrade version 1.1 -->
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glDrawBuffers">
<info>
<copyright>
<year>2003-2005</year>
<holder>3Dlabs Inc. Ltd.</holder>
</copyright>
<copyright>
<year>2010-2014</year>
<holder>Khronos Group</holder>
</copyright>
</info>
<refmeta>
<refentrytitle>glDrawBuffers</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glDrawBuffers</refname>
<refname>glNamedFramebufferDrawBuffers</refname>
<refpurpose>Specifies a list of color buffers to be drawn
into</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glDrawBuffers</function></funcdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLenum *<parameter>bufs</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>glNamedFramebufferDrawBuffers</function></funcdef>
<paramdef>GLuint <parameter>framebuffer</parameter></paramdef>
<paramdef>GLsizei <parameter>n</parameter></paramdef>
<paramdef>const GLenum *<parameter>bufs</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="parameters">
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>framebuffer</parameter></term>
<listitem>
<para>Specifies the name of the framebuffer object for
<function>glNamedFramebufferDrawBuffers</function>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>Specifies the number of buffers in
<parameter>bufs</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bufs</parameter></term>
<listitem>
<para>Points to an array of symbolic constants specifying the
buffers into which fragment colors or data values will be
written.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="description">
<title>Description</title>
<para><function>glDrawBuffers</function> and <function>glNamedFramebufferDrawBuffers</function> define an array of buffers into
which outputs from the fragment shader data will be written. If a fragment
shader writes a value to one or more user defined output variables, then
the value of each variable will be written into the buffer specified at a
location within <parameter>bufs</parameter> corresponding to the location
assigned to that user defined output. The draw buffer used for user
defined outputs assigned to locations greater than or equal to
<parameter>n</parameter> is implicitly set to <constant>GL_NONE</constant>
and any data written to such an output is discarded.</para>
<para>For <function>glDrawBuffers</function>, the framebuffer object that
is bound to the <constant>GL_DRAW_FRAMEBUFFER</constant> binding will be
used. For <function>glNamedFramebufferDrawBuffers</function>,
<parameter>framebuffer</parameter> is the name of the framebuffer object.
If <parameter>framebuffer</parameter> is zero, then the default
framebuffer is affected.</para>
<para>The symbolic constants contained in <parameter>bufs</parameter> may
be any of the following:</para>
<variablelist>
<varlistentry>
<term><constant>GL_NONE</constant></term>
<listitem>
<para>The fragment shader output value is not written into any color
buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_LEFT</constant></term>
<listitem>
<para>The fragment shader output value is written into the front
left color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_FRONT_RIGHT</constant></term>
<listitem>
<para>The fragment shader output value is written into the front
right color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK_LEFT</constant></term>
<listitem>
<para>The fragment shader output value is written into the back left
color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_BACK_RIGHT</constant></term>
<listitem>
<para>The fragment shader output value is written into the back
right color buffer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_COLOR_ATTACHMENT</constant><emphasis>n</emphasis></term>
<listitem>
<para>The fragment shader output value is written into the
<emphasis>n</emphasis>th color attachment of the current
framebuffer. <emphasis>n</emphasis> may range from zero to the value
of <constant>GL_MAX_COLOR_ATTACHMENTS</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Except for <constant>GL_NONE</constant>, the preceding symbolic
constants may not appear more than once in <parameter>bufs</parameter>.
The maximum number of draw buffers supported is implementation dependent
and can be queried by calling
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with the argument
<constant>GL_MAX_DRAW_BUFFERS</constant>.</para>
</refsect1>
<refsect1 xml:id="notes">
<title>Notes</title>
<para>The symbolic constants <constant>GL_FRONT</constant>,
<constant>GL_BACK</constant>, <constant>GL_LEFT</constant>,
<constant>GL_RIGHT</constant>, and <constant>GL_FRONT_AND_BACK</constant>
are not allowed in the <parameter>bufs</parameter> array since they may
refer to multiple buffers.</para>
<para>If a fragment shader does not write to a user defined output
variable, the values of the fragment colors following shader execution are
undefined. For each fragment generated in this situation, a different
value may be written into each of the buffers specified by
<parameter>bufs</parameter>.</para>
</refsect1>
<refsect1 xml:id="errors">
<title>Errors</title>
<para><constant>GL_INVALID_OPERATION</constant> error is generated by
<function>glNamedFramebufferDrawBuffers</function> if
<parameter>framebuffer</parameter> is not zero or the name of an existing
framebuffer object.</para>
<para><constant>GL_INVALID_ENUM</constant> is generated if one of the
values in <parameter>bufs</parameter> is not an accepted value.</para>
<para><constant>GL_INVALID_ENUM</constant> is generated if the API call
refers to the default framebuffer and one or more of the values in
<parameter>bufs</parameter> is one of the
<constant>GL_COLOR_ATTACHMENT</constant><emphasis>n</emphasis>
tokens.</para>
<para><constant>GL_INVALID_ENUM</constant> is generated if the API call
refers to a framebuffer object and one or more of the values in
<parameter>bufs</parameter> is anything other than
<constant>GL_NONE</constant> or one of the
<constant>GL_COLOR_ATTACHMENT</constant><emphasis>n</emphasis>
tokens.</para>
<para><constant>GL_INVALID_ENUM</constant> is generated if
<parameter>n</parameter> is less than 0.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if a symbolic
constant other than <constant>GL_NONE</constant> appears more than once in
<parameter>bufs</parameter>.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if any of the
entries in <parameter>bufs</parameter> (other than
<constant>GL_NONE</constant> ) indicates a color buffer that does not
exist in the current GL context.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if any value
in <parameter>bufs</parameter> is <constant>GL_BACK</constant>, and
<parameter>n</parameter> is not one.</para>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>n</parameter> is greater than
<constant>GL_MAX_DRAW_BUFFERS</constant>.</para>
</refsect1>
<refsect1 xml:id="associatedgets">
<title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument <constant>GL_MAX_DRAW_BUFFERS</constant>
</para>
<para>
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
with argument
<constant>GL_DRAW_BUFFER</constant><emphasis>i</emphasis> where
<emphasis><code>i</code></emphasis> indicates the number of the draw
buffer whose value is to be queried.
</para>
</refsect1>
<refsect1 xml:id="versions">
<title>Version Support</title>
<informaltable>
<tgroup cols="13" align="left">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
<tbody>
<row>
<entry><function>glDrawBuffers</function></entry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='20']/*)"/>
</row>
<row>
<entry><function>glNamedFramebufferDrawBuffers</function></entry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='45']/*)"/>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 xml:id="seealso"><title>See Also</title>
<para> <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawBuffers</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 xml:id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"/> 2003-2005 3Dlabs Inc. Ltd.
Copyright <trademark class="copyright"/> 2010-2014 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://opencontent.org/openpub/">http://opencontent.org/openpub/</link>.
</para>
</refsect1>
</refentry>
|
