1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
4 <refentry id=
"glDrawBuffers">
6 <refentrytitle>glDrawBuffers
</refentrytitle>
7 <manvolnum>3G
</manvolnum>
10 <refname>glDrawBuffers
</refname>
11 <refpurpose>Specifies a list of color buffers to be drawn into
</refpurpose>
13 <refsynopsisdiv><title>C Specification
</title>
16 <funcdef>void
<function>glDrawBuffers
</function></funcdef>
17 <paramdef>GLsizei
<parameter>n
</parameter></paramdef>
18 <paramdef>const GLenum *
<parameter>bufs
</parameter></paramdef>
22 <refsect1 id=
"parameters"><title>Parameters
</title>
25 <term><parameter>n
</parameter></term>
27 <para>Specifies the number of buffers in
28 <parameter>bufs
</parameter>.
</para>
32 <term><parameter>bufs
</parameter></term>
34 <para>Points to an array of symbolic constants
35 specifying the buffers into which fragment colors or
36 data values will be written.
</para>
41 <refsect1 id=
"description"><title>Description
</title>
42 <para><function>glDrawBuffers
</function> defines an array of
43 buffers into which outputs from the fragment shader data will
44 be written. If a fragment shader writes a value
45 to one or more user defined output
46 variables, then the value of each variable will be written into the
47 buffer specified at a location within
<parameter>bufs
</parameter>
48 corresponding to the location assigned to that user defined output.
49 The draw buffer used for user defined outputs assigned to locations
50 greater than or equal to
<parameter>n
</parameter> is implicitly set
51 to
<constant>GL_NONE
</constant> and any data written to such an output
54 <para>The symbolic constants contained in
55 <parameter>bufs
</parameter> may be any of the following:
</para>
59 <term><constant>GL_NONE
</constant></term>
61 <para>The fragment shader output value is not written into
62 any color buffer.
</para>
66 <term><constant>GL_FRONT_LEFT
</constant></term>
68 <para>The fragment shader output value is written into the
69 front left color buffer.
</para>
73 <term><constant>GL_FRONT_RIGHT
</constant></term>
75 <para>The fragment shader output value is written into the
76 front right color buffer.
</para>
80 <term><constant>GL_BACK_LEFT
</constant></term>
82 <para>The fragment shader output value is written into the
83 back left color buffer.
</para>
87 <term><constant>GL_BACK_RIGHT
</constant></term>
89 <para>The fragment shader output value is written into the
90 back right color buffer.
</para>
94 <term><constant>GL_COLOR_ATTACHMENT
<emphasis>n
</emphasis></constant></term>
96 <para>The fragment shader output value is written into the
97 <emphasis>n
</emphasis>th color attachment of the current framebuffer.
98 <emphasis>n
</emphasis> may range from
0 to the value of
99 <constant>GL_MAX_COLOR_ATTACHMENTS
</constant>.
</para>
104 <para>Except for
<constant>GL_NONE
</constant>, the preceding
105 symbolic constants may not appear more than once in
106 <parameter>bufs
</parameter>. The maximum number of draw buffers
107 supported is implementation dependent and can be queried by
109 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry>
110 with the argument
<constant>GL_MAX_DRAW_BUFFERS
</constant>.
</para>
112 <refsect1 id=
"notes"><title>Notes
</title>
114 <para>The symbolic constants
<constant>GL_FRONT
</constant>,
115 <constant>GL_BACK
</constant>,
<constant>GL_LEFT
</constant>,
116 <constant>GL_RIGHT
</constant>, and
117 <constant>GL_FRONT_AND_BACK
</constant> are not allowed in the
118 <parameter>bufs
</parameter> array since they may refer to
119 multiple buffers.
</para>
121 <para>If a fragment shader does not write to a user defined output variable,
122 the values of the fragment
123 colors following shader execution are undefined. For each
124 fragment generated in this situation, a different value may be
125 written into each of the buffers specified by
126 <parameter>bufs
</parameter>.
</para>
128 <refsect1 id=
"errors"><title>Errors
</title>
129 <para><constant>GL_INVALID_ENUM
</constant> is generated if one of the
130 values in
<parameter>bufs
</parameter> is not an accepted
133 <para><constant>GL_INVALID_ENUM
</constant> is generated if the GL is bound
134 to the default framebuffer and one or more of the values in
135 <parameter>bufs
</parameter> is one of the
<constant>GL_COLOR_ATTACHMENT
<emphasis>n
</emphasis></constant>
138 <para><constant>GL_INVALID_ENUM
</constant> is generated if the GL is bound
139 to a framebuffer object and one or more of the values in
<parameter>bufs
</parameter>
140 is anything other than
<constant>GL_NONE
</constant> or one of the
141 <constant>GL_COLOR_ATTACHMENTS
<emphasis>n
</emphasis></constant> tokens.
</para>
143 <para><constant>GL_INVALID_ENUM
</constant> is generated if
144 <parameter>n
</parameter> is less than
0.
</para>
146 <para><constant>GL_INVALID_OPERATION
</constant> is generated if a
147 symbolic constant other than
<constant>GL_NONE
</constant>
148 appears more than once in
<parameter>bufs
</parameter>.
</para>
150 <para><constant>GL_INVALID_OPERATION
</constant> is generated if any of
151 the entries in
<parameter>bufs
</parameter> (other than
152 <constant>GL_NONE
</constant> ) indicates a color buffer that
153 does not exist in the current GL context.
</para>
155 <para><constant>GL_INVALID_VALUE
</constant> is generated if
156 <parameter>n
</parameter> is greater than
157 <constant>GL_MAX_DRAW_BUFFERS
</constant>.
</para>
160 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
161 <para><citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry>
162 with argument
<constant>GL_MAX_DRAW_BUFFERS
</constant></para>
164 <para><citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry>
165 with argument
<constant>GL_DRAW_BUFFER
<emphasis>i
</emphasis></constant> where
166 <code><emphasis>i
</emphasis></code> indicates the number of the draw buffer
167 whose value is to be queried
</para>
169 <refsect1 id=
"seealso"><title>See Also
</title>
170 <para> <citerefentry><refentrytitle>glBlendFunc
</refentrytitle></citerefentry>,
171 <citerefentry><refentrytitle>glColorMask
</refentrytitle></citerefentry>,
172 <citerefentry><refentrytitle>glDrawBuffers
</refentrytitle></citerefentry>,
173 <citerefentry><refentrytitle>glLogicOp
</refentrytitle></citerefentry>,
174 <citerefentry><refentrytitle>glReadBuffer
</refentrytitle></citerefentry></para>
176 <refsect1 id=
"Copyright"><title>Copyright
</title>
178 Copyright
<trademark class=
"copyright"></trademark> 2003-
2005 3Dlabs Inc. Ltd.
179 This material may be distributed subject to the terms and conditions set forth in
180 the Open Publication License, v
1.0,
8 June
1999.
181 <ulink url=
"http://opencontent.org/openpub/">http://opencontent.org/openpub/
</ulink>.