upstream-man-pages/man2/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 fragment color values or fragment data will
  44         be written. If no fragment shader is active, rendering
  45         operations will generate only one fragment color per fragment
  46         and it will be written into each of the buffers specified by
  47         <parameter>bufs</parameter>. If a fragment shader is active and
  48         it writes a value to the output variable
  49         <code>gl_FragColor</code>, then that value will be
  50         written into each of the buffers specified by
  51         <parameter>bufs</parameter>. If a fragment shader is active and
  52         it writes a value to one or more elements of the output array
  53         variable <code>gl_FragData[]</code>, then the value of
  54         <code>gl_FragData[0] </code> will be written into the
  55         first buffer specified by <parameter>bufs</parameter>, the value
  56         of <code>gl_FragData[1] </code> will be written into the
  57         second buffer specified by <parameter>bufs</parameter>, and so
  58         on up to <code>gl_FragData[n-1]</code>. The draw buffer
  59         used for <code>gl_FragData[n]</code> and beyond is
  60         implicitly set to be <constant>GL_NONE</constant>.</para>
  61
  62         <para>The symbolic constants contained in
  63         <parameter>bufs</parameter> may be any of the following:</para>
  64
  65         <variablelist>
  66             <varlistentry>
  67                 <term><constant>GL_NONE</constant></term>
  68                 <listitem>
  69                     <para>The fragment color/data value is not written into
  70                     any color buffer.</para>
  71                 </listitem>
  72             </varlistentry>
  73             <varlistentry>
  74                 <term><constant>GL_FRONT_LEFT</constant></term>
  75                 <listitem>
  76                     <para>The fragment color/data value is written into the
  77                     front left color buffer.</para>
  78                 </listitem>
  79             </varlistentry>
  80             <varlistentry>
  81                 <term><constant>GL_FRONT_RIGHT</constant></term>
  82                 <listitem>
  83                     <para>The fragment color/data value is written into the
  84                     front right color buffer.</para>
  85                 </listitem>
  86             </varlistentry>
  87             <varlistentry>
  88                 <term><constant>GL_BACK_LEFT</constant></term>
  89                 <listitem>
  90                     <para>The fragment color/data value is written into the
  91                     back left color buffer.</para>
  92                 </listitem>
  93             </varlistentry>
  94             <varlistentry>
  95                 <term><constant>GL_BACK_RIGHT</constant></term>
  96                 <listitem>
  97                     <para>The fragment color/data value is written into the
  98                     back right color buffer.</para>
  99                 </listitem>
 100             </varlistentry>
 101             <varlistentry>
 102                 <term><constant>GL_AUXi</constant></term>
 103                 <listitem>
 104                     <para>The fragment color/data value is written into
 105                     auxiliary buffer <code>i</code>.</para>
 106                 </listitem>
 107             </varlistentry>
 108         </variablelist>
 109
 110         <para>Except for <constant>GL_NONE</constant>, the preceding
 111         symbolic constants may not appear more than once in
 112         <parameter>bufs</parameter>. The maximum number of draw buffers
 113         supported is implementation dependent and can be queried by
 114         calling
 115         <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 116         with the argument <constant>GL_MAX_DRAW_BUFFERS</constant>. The
 117         number of auxiliary buffers can be queried by calling
 118         <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 119         with the argument <constant>GL_AUX_BUFFERS</constant>.</para>
 120     </refsect1>
 121     <refsect1 id="notes"><title>Notes</title>
 122         <para><function>glDrawBuffers</function> is available only if
 123         the GL version is 2.0 or greater.</para>
 124
 125         <para>It is always the case that <constant>GL_AUXi</constant> =
 126         <constant>GL_AUX0</constant> + <code>i</code>.</para>
 127
 128         <para>The symbolic constants <constant>GL_FRONT</constant>,
 129         <constant>GL_BACK</constant>, <constant>GL_LEFT</constant>,
 130         <constant>GL_RIGHT</constant>, and
 131         <constant>GL_FRONT_AND_BACK</constant> are not allowed in the
 132         <parameter>bufs</parameter> array since they may refer to
 133         multiple buffers.</para>
 134
 135         <para>If a fragment shader writes to neither
 136         <code>gl_FragColor</code> nor
 137         <code>gl_FragData</code>, the values of the fragment
 138         colors following shader execution are undefined. For each
 139         fragment generated in this situation, a different value may be
 140         written into each of the buffers specified by
 141         <parameter>bufs</parameter>.</para>
 142     </refsect1>
 143     <refsect1 id="errors"><title>Errors</title>
 144         <para><constant>GL_INVALID_ENUM</constant> is generated if one of the
 145         values in <parameter>bufs</parameter> is not an accepted
 146         value.</para>
 147
 148         <para><constant>GL_INVALID_ENUM</constant> is generated if
 149         <parameter>n</parameter> is less than 0.</para>
 150
 151         <para><constant>GL_INVALID_OPERATION</constant> is generated if a
 152         symbolic constant other than <constant>GL_NONE</constant>
 153         appears more than once in <parameter>bufs</parameter>.</para>
 154
 155         <para><constant>GL_INVALID_OPERATION</constant> is generated if any of
 156         the entries in <parameter>bufs</parameter> (other than
 157         <constant>GL_NONE</constant> ) indicates a color buffer that
 158         does not exist in the current GL context.</para>
 159
 160         <para><constant>GL_INVALID_VALUE</constant> is generated if
 161         <parameter>n</parameter> is greater than
 162         <constant>GL_MAX_DRAW_BUFFERS</constant>.</para>
 163
 164         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 165         <function>glDrawBuffers</function> is executed between the
 166         execution of
 167         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 168         and the corresponding execution of
 169         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 170     </refsect1>
 171     <refsect1 id="associatedgets"><title>Associated Gets</title>
 172         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 173         with argument <constant>GL_MAX_DRAW_BUFFERS</constant></para>
 174
 175         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 176         with argument <constant>GL_DRAW_BUFFERSi</constant> where
 177         <code>i</code> indicates the number of the draw buffer
 178         whose value is to be queried</para>
 179     </refsect1>
 180     <refsect1 id="seealso"><title>See Also</title>
 181         <para> <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
 182         <citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
 183         <citerefentry><refentrytitle>glDrawBuffers</refentrytitle></citerefentry>,
 184         <citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
 185         <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
 186         <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry></para>
 187     </refsect1>
 188     <refsect1 id="Copyright"><title>Copyright</title>
 189         <para>
 190             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 191             This material may be distributed subject to the terms and conditions set forth in
 192             the Open Publication License, v 1.0, 8 June 1999.
 193             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 194         </para>
 195     </refsect1>
 196 </refentry>