upstream-man-pages/man2/glDrawBuffer.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="glDrawBuffer">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glDrawBuffer</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glDrawBuffer</refname>
  17         <refpurpose>specify which color buffers are to be drawn into</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glDrawBuffer</function></funcdef>
  23                 <paramdef>GLenum <parameter>mode</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <!-- eqn: ignoring delim $$ -->
  28     <refsect1 id="parameters"><title>Parameters</title>
  29         <variablelist>
  30         <varlistentry>
  31             <term><parameter>mode</parameter></term>
  32             <listitem>
  33                 <para>
  34                     Specifies up to four color buffers to be drawn into.
  35                     Symbolic constants
  36                     <constant>GL_NONE</constant>,
  37                     <constant>GL_FRONT_LEFT</constant>,
  38                     <constant>GL_FRONT_RIGHT</constant>,
  39                     <constant>GL_BACK_LEFT</constant>,
  40                     <constant>GL_BACK_RIGHT</constant>,
  41                     <constant>GL_FRONT</constant>,
  42                     <constant>GL_BACK</constant>,
  43                     <constant>GL_LEFT</constant>,
  44                     <constant>GL_RIGHT</constant>,
  45                     <constant>GL_FRONT_AND_BACK</constant>, and
  46                     <constant>GL_AUX</constant><emphasis>i</emphasis>,
  47                     where <emphasis>i</emphasis> is between 0 and the value of <constant>GL_AUX_BUFFERS</constant> minus 1,
  48                     are accepted.  (<constant>GL_AUX_BUFFERS</constant> is not the upper limit; use <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
  49                     to query the number of available aux buffers.)
  50                     The initial value is <constant>GL_FRONT</constant> for single-buffered contexts,
  51                     and <constant>GL_BACK</constant> for double-buffered contexts.
  52                 </para>
  53             </listitem>
  54         </varlistentry>
  55         </variablelist>
  56     </refsect1>
  57     <refsect1 id="description"><title>Description</title>
  58         <para>
  59             When colors are written to the frame buffer,
  60             they are written into the color buffers specified by <function>glDrawBuffer</function>.
  61             The specifications are as follows:
  62         </para>
  63         <variablelist>
  64             <varlistentry>
  65                 <term><constant>GL_NONE</constant></term>
  66                 <listitem>
  67                     <para>
  68                         No color buffers are written.
  69                     </para>
  70                 </listitem>
  71             </varlistentry>
  72             <varlistentry>
  73                 <term><constant>GL_FRONT_LEFT</constant></term>
  74                 <listitem>
  75                     <para>
  76                         Only the front left color buffer is written.
  77                     </para>
  78                 </listitem>
  79             </varlistentry>
  80             <varlistentry>
  81                 <term><constant>GL_FRONT_RIGHT</constant></term>
  82                 <listitem>
  83                     <para>
  84                         Only the front right color buffer is written.
  85                     </para>
  86                 </listitem>
  87             </varlistentry>
  88             <varlistentry>
  89                 <term><constant>GL_BACK_LEFT</constant></term>
  90                 <listitem>
  91                     <para>
  92                         Only the back left color buffer is written.
  93                     </para>
  94                 </listitem>
  95             </varlistentry>
  96             <varlistentry>
  97                 <term><constant>GL_BACK_RIGHT</constant></term>
  98                 <listitem>
  99                     <para>
 100                         Only the back right color buffer is written.
 101                     </para>
 102                 </listitem>
 103             </varlistentry>
 104             <varlistentry>
 105                 <term><constant>GL_FRONT</constant></term>
 106                 <listitem>
 107                     <para>
 108                         Only the front left and front right color buffers are written.
 109                         If there is no front right color buffer,
 110                         only the front left color buffer is written.
 111                     </para>
 112                 </listitem>
 113             </varlistentry>
 114             <varlistentry>
 115                 <term><constant>GL_BACK</constant></term>
 116                 <listitem>
 117                     <para>
 118                         Only the back left and back right color buffers are written.
 119                         If there is no back right color buffer,
 120                         only the back left color buffer is written.
 121                     </para>
 122                 </listitem>
 123             </varlistentry>
 124             <varlistentry>
 125                 <term><constant>GL_LEFT</constant></term>
 126                 <listitem>
 127                     <para>
 128                         Only the front left and back left color buffers are written.
 129                         If there is no back left color buffer,
 130                         only the front left color buffer is written.
 131                     </para>
 132                 </listitem>
 133             </varlistentry>
 134             <varlistentry>
 135                 <term><constant>GL_RIGHT</constant></term>
 136                 <listitem>
 137                     <para>
 138                         Only the front right and back right color buffers are written.
 139                         If there is no back right color buffer,
 140                         only the front right color buffer is written.
 141                     </para>
 142                 </listitem>
 143             </varlistentry>
 144             <varlistentry>
 145                 <term><constant>GL_FRONT_AND_BACK</constant></term>
 146                 <listitem>
 147                     <para>
 148                         All the front and back color buffers
 149                         (front left, front right, back left, back right)
 150                         are written.
 151                         If there are no back color buffers,
 152                         only the front left and front right color buffers are written.
 153                         If there are no right color buffers,
 154                         only the front left and back left color buffers are written.
 155                         If there are no right or back color buffers,
 156                         only the front left color buffer is written.
 157                     </para>
 158                 </listitem>
 159             </varlistentry>
 160             <varlistentry>
 161                 <term><constant>GL_AUX</constant><emphasis>i</emphasis></term>
 162                 <listitem>
 163                     <para>
 164                         Only auxiliary color buffer <emphasis>i</emphasis> is written.
 165                     </para>
 166                 </listitem>
 167             </varlistentry>
 168         </variablelist>
 169         <para>
 170             If more than one color buffer is selected for drawing,
 171             then blending or logical operations are computed and applied independently
 172             for each color buffer and can produce different results in each buffer.
 173         </para>
 174         <para>
 175             Monoscopic contexts include only
 176             <emphasis>left</emphasis>
 177             buffers, and stereoscopic contexts include both
 178             <emphasis>left</emphasis>
 179             and
 180             <emphasis>right</emphasis>
 181             buffers.
 182             Likewise, single-buffered contexts include only
 183             <emphasis>front</emphasis>
 184             buffers, and double-buffered contexts include both
 185             <emphasis>front</emphasis>
 186             and
 187             <emphasis>back</emphasis>
 188             buffers.
 189             The context is selected at GL initialization.
 190         </para>
 191     </refsect1>
 192     <refsect1 id="notes"><title>Notes</title>
 193         <para>
 194             It is always the case that <constant>GL_AUX</constant>
 195             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 196             = <constant>GL_AUX0</constant> +
 197             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
 198         </para>
 199     </refsect1>
 200     <refsect1 id="errors"><title>Errors</title>
 201         <para>
 202             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
 203         </para>
 204         <para>
 205             <constant>GL_INVALID_OPERATION</constant> is generated if none of the buffers indicated
 206             by <parameter>mode</parameter> exists.
 207         </para>
 208         <para>
 209             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glDrawBuffer</function>
 210             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 211             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 212         </para>
 213     </refsect1>
 214     <refsect1 id="associatedgets"><title>Associated Gets</title>
 215         <para>
 216             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DRAW_BUFFER</constant>
 217         </para>
 218         <para>
 219             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_AUX_BUFFERS</constant>
 220         </para>
 221     </refsect1>
 222     <refsect1 id="seealso"><title>See Also</title>
 223         <para>
 224             <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
 225             <citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
 226             <citerefentry><refentrytitle>glIndexMask</refentrytitle></citerefentry>,
 227             <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
 228             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>
 229         </para>
 230     </refsect1>
 231     <refsect1 id="Copyright"><title>Copyright</title>
 232         <para>
 233             Copyright <trademark class="copyright"></trademark> 1991-2006
 234             Silicon Graphics, Inc. This document is licensed under the SGI
 235             Free Software B License. For details, see
 236             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 237         </para>
 238     </refsect1>
 239 </refentry>