Opentk/Source/Bind/Specifications/Docs/glDrawBuffers.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
	      "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glDrawBuffers">
    <refmeta>
	<refentrytitle>glDrawBuffers</refentrytitle>
	<manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
	<refname>glDrawBuffers</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>
	</funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
	<variablelist>
	    <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 id="description"><title>Description</title>
	<para><function>glDrawBuffers</function> defines an array of
	buffers into which fragment color values or fragment data will
	be written. If no fragment shader is active, rendering
	operations will generate only one fragment color per fragment
	and it will be written into each of the buffers specified by
	<parameter>bufs</parameter>. If a fragment shader is active and
	it writes a value to the output variable
	<code>gl_FragColor</code>, then that value will be
	written into each of the buffers specified by
	<parameter>bufs</parameter>. If a fragment shader is active and
	it writes a value to one or more elements of the output array
	variable <code>gl_FragData[]</code>, then the value of
	<code>gl_FragData[0] </code> will be written into the
	first buffer specified by <parameter>bufs</parameter>, the value
	of <code>gl_FragData[1] </code> will be written into the
	second buffer specified by <parameter>bufs</parameter>, and so
	on up to <code>gl_FragData[n-1]</code>. The draw buffer
	used for <code>gl_FragData[n]</code> and beyond is
	implicitly set to be <constant>GL_NONE</constant>.</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 color/data value is not written into
		    any color buffer.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><constant>GL_FRONT_LEFT</constant></term>
		<listitem>
		    <para>The fragment color/data value is written into the
		    front left color buffer.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><constant>GL_FRONT_RIGHT</constant></term>
		<listitem>
		    <para>The fragment color/data value is written into the
		    front right color buffer.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><constant>GL_BACK_LEFT</constant></term>
		<listitem>
		    <para>The fragment color/data value is written into the
		    back left color buffer.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><constant>GL_BACK_RIGHT</constant></term>
		<listitem>
		    <para>The fragment color/data value is written into the
		    back right color buffer.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><constant>GL_AUXi</constant></term>
		<listitem>
		    <para>The fragment color/data value is written into
		    auxiliary buffer <code>i</code>.</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>. The
	number of auxiliary buffers can be queried by calling
	<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
	with the argument <constant>GL_AUX_BUFFERS</constant>.</para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
	<para><function>glDrawBuffers</function> is available only if
	the GL version is 2.0 or greater.</para>

	<para>It is always the case that <constant>GL_AUXi</constant> =
	<constant>GL_AUX0</constant> + <code>i</code>.</para>

	<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 writes to neither
	<code>gl_FragColor</code> nor
	<code>gl_FragData</code>, 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 id="errors"><title>Errors</title>
	<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
	<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_VALUE</constant> is generated if
	<parameter>n</parameter> is greater than
	<constant>GL_MAX_DRAW_BUFFERS</constant>.</para>

	<para><constant>GL_INVALID_OPERATION</constant> is generated if
	<function>glDrawBuffers</function> is executed between the
	execution of
	<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
	and the corresponding execution of
	<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
    </refsect1>
    <refsect1 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_BUFFERSi</constant> where
	<code>i</code> indicates the number of the draw buffer
	whose value is to be queried</para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
	<para> <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glDrawBuffers</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry></para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd. 
            This material may be distributed subject to the terms and conditions set forth in 
            the Open Publication License, v 1.0, 8 June 1999.
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
        </para>
    </refsect1>
</refentry>