<!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>
