upstream-doc/man3/glDrawBuffers.xml

   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">
   5     <refmeta>
   6     <refentrytitle>glDrawBuffers</refentrytitle>
   7     <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10     <refname>glDrawBuffers</refname>
  11     <refpurpose>Specifies a list of color buffers to be drawn into</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14     <funcsynopsis>
  15         <funcprototype>
  16         <funcdef>void <function>glDrawBuffers</function></funcdef>
  17         <paramdef>GLsizei <parameter>n</parameter></paramdef>
  18         <paramdef>const GLenum *<parameter>bufs</parameter></paramdef>
  19         </funcprototype>
  20     </funcsynopsis>
  21     </refsynopsisdiv>
  22     <refsect1 id="parameters"><title>Parameters</title>
  23     <variablelist>
  24         <varlistentry>
  25         <term><parameter>n</parameter></term>
  26         <listitem>
  27             <para>Specifies the number of buffers in
  28             <parameter>bufs</parameter>.</para>
  29         </listitem>
  30         </varlistentry>
  31         <varlistentry>
  32         <term><parameter>bufs</parameter></term>
  33         <listitem>
  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>
  37         </listitem>
  38         </varlistentry>
  39     </variablelist>
  40     </refsect1>
  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
  52     is discarded.</para>
  53
  54     <para>The symbolic constants contained in
  55     <parameter>bufs</parameter> may be any of the following:</para>
  56
  57     <variablelist>
  58         <varlistentry>
  59         <term><constant>GL_NONE</constant></term>
  60         <listitem>
  61             <para>The fragment shader output value is not written into
  62             any color buffer.</para>
  63         </listitem>
  64         </varlistentry>
  65         <varlistentry>
  66         <term><constant>GL_FRONT_LEFT</constant></term>
  67         <listitem>
  68             <para>The fragment shader output value is written into the
  69             front left color buffer.</para>
  70         </listitem>
  71         </varlistentry>
  72         <varlistentry>
  73         <term><constant>GL_FRONT_RIGHT</constant></term>
  74         <listitem>
  75             <para>The fragment shader output value is written into the
  76             front right color buffer.</para>
  77         </listitem>
  78         </varlistentry>
  79         <varlistentry>
  80         <term><constant>GL_BACK_LEFT</constant></term>
  81         <listitem>
  82             <para>The fragment shader output value is written into the
  83             back left color buffer.</para>
  84         </listitem>
  85         </varlistentry>
  86         <varlistentry>
  87         <term><constant>GL_BACK_RIGHT</constant></term>
  88         <listitem>
  89             <para>The fragment shader output value is written into the
  90             back right color buffer.</para>
  91         </listitem>
  92         </varlistentry>
  93         <varlistentry>
  94         <term><constant>GL_COLOR_ATTACHMENT<emphasis>n</emphasis></constant></term>
  95         <listitem>
  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>
 100         </listitem>
 101         </varlistentry>
 102     </variablelist>
 103
 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
 108     calling
 109     <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 110     with the argument <constant>GL_MAX_DRAW_BUFFERS</constant>.</para>
 111     </refsect1>
 112     <refsect1 id="notes"><title>Notes</title>
 113
 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>
 120
 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>
 127     </refsect1>
 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
 131     value.</para>
 132
 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>
 136     tokens.</para>
 137
 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>
 142
 143     <para><constant>GL_INVALID_ENUM</constant> is generated if
 144     <parameter>n</parameter> is less than 0.</para>
 145
 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>
 149
 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>
 154
 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>
 158
 159     </refsect1>
 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>
 163
 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>
 168     </refsect1>
 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>
 175     </refsect1>
 176     <refsect1 id="Copyright"><title>Copyright</title>
 177         <para>
 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>.
 182         </para>
 183     </refsect1>
 184 </refentry>