upstream-man-pages/man4/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>, and
  45                     <constant>GL_FRONT_AND_BACK</constant>
  46                     are accepted.
  47                     The initial value is <constant>GL_FRONT</constant> for single-buffered contexts,
  48                     and <constant>GL_BACK</constant> for double-buffered contexts.
  49                 </para>
  50             </listitem>
  51         </varlistentry>
  52         </variablelist>
  53     </refsect1>
  54     <refsect1 id="description"><title>Description</title>
  55         <para>
  56             When colors are written to the frame buffer,
  57             they are written into the color buffers specified by <function>glDrawBuffer</function>.
  58             The specifications are as follows:
  59         </para>
  60         <variablelist>
  61             <varlistentry>
  62                 <term><constant>GL_NONE</constant></term>
  63                 <listitem>
  64                     <para>
  65                         No color buffers are written.
  66                     </para>
  67                 </listitem>
  68             </varlistentry>
  69             <varlistentry>
  70                 <term><constant>GL_FRONT_LEFT</constant></term>
  71                 <listitem>
  72                     <para>
  73                         Only the front left color buffer is written.
  74                     </para>
  75                 </listitem>
  76             </varlistentry>
  77             <varlistentry>
  78                 <term><constant>GL_FRONT_RIGHT</constant></term>
  79                 <listitem>
  80                     <para>
  81                         Only the front right color buffer is written.
  82                     </para>
  83                 </listitem>
  84             </varlistentry>
  85             <varlistentry>
  86                 <term><constant>GL_BACK_LEFT</constant></term>
  87                 <listitem>
  88                     <para>
  89                         Only the back left color buffer is written.
  90                     </para>
  91                 </listitem>
  92             </varlistentry>
  93             <varlistentry>
  94                 <term><constant>GL_BACK_RIGHT</constant></term>
  95                 <listitem>
  96                     <para>
  97                         Only the back right color buffer is written.
  98                     </para>
  99                 </listitem>
 100             </varlistentry>
 101             <varlistentry>
 102                 <term><constant>GL_FRONT</constant></term>
 103                 <listitem>
 104                     <para>
 105                         Only the front left and front right color buffers are written.
 106                         If there is no front right color buffer,
 107                         only the front left color buffer is written.
 108                     </para>
 109                 </listitem>
 110             </varlistentry>
 111             <varlistentry>
 112                 <term><constant>GL_BACK</constant></term>
 113                 <listitem>
 114                     <para>
 115                         Only the back left and back right color buffers are written.
 116                         If there is no back right color buffer,
 117                         only the back left color buffer is written.
 118                     </para>
 119                 </listitem>
 120             </varlistentry>
 121             <varlistentry>
 122                 <term><constant>GL_LEFT</constant></term>
 123                 <listitem>
 124                     <para>
 125                         Only the front left and back left color buffers are written.
 126                         If there is no back left color buffer,
 127                         only the front left color buffer is written.
 128                     </para>
 129                 </listitem>
 130             </varlistentry>
 131             <varlistentry>
 132                 <term><constant>GL_RIGHT</constant></term>
 133                 <listitem>
 134                     <para>
 135                         Only the front right and back right color buffers are written.
 136                         If there is no back right color buffer,
 137                         only the front right color buffer is written.
 138                     </para>
 139                 </listitem>
 140             </varlistentry>
 141             <varlistentry>
 142                 <term><constant>GL_FRONT_AND_BACK</constant></term>
 143                 <listitem>
 144                     <para>
 145                         All the front and back color buffers
 146                         (front left, front right, back left, back right)
 147                         are written.
 148                         If there are no back color buffers,
 149                         only the front left and front right color buffers are written.
 150                         If there are no right color buffers,
 151                         only the front left and back left color buffers are written.
 152                         If there are no right or back color buffers,
 153                         only the front left color buffer is written.
 154                     </para>
 155                 </listitem>
 156             </varlistentry>
 157         </variablelist>
 158         <para>
 159             If more than one color buffer is selected for drawing,
 160             then blending or logical operations are computed and applied independently
 161             for each color buffer and can produce different results in each buffer.
 162         </para>
 163         <para>
 164             Monoscopic contexts include only
 165             <emphasis>left</emphasis>
 166             buffers, and stereoscopic contexts include both
 167             <emphasis>left</emphasis>
 168             and
 169             <emphasis>right</emphasis>
 170             buffers.
 171             Likewise, single-buffered contexts include only
 172             <emphasis>front</emphasis>
 173             buffers, and double-buffered contexts include both
 174             <emphasis>front</emphasis>
 175             and
 176             <emphasis>back</emphasis>
 177             buffers.
 178             The context is selected at GL initialization.
 179         </para>
 180     </refsect1>
 181     <refsect1 id="errors"><title>Errors</title>
 182         <para>
 183             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
 184         </para>
 185         <para>
 186             <constant>GL_INVALID_OPERATION</constant> is generated if none of the buffers indicated
 187             by <parameter>mode</parameter> exists.
 188         </para>
 189     </refsect1>
 190     <refsect1 id="associatedgets"><title>Associated Gets</title>
 191         <para>
 192             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DRAW_BUFFER</constant>
 193         </para>
 194     </refsect1>
 195     <refsect1 id="seealso"><title>See Also</title>
 196         <para>
 197             <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
 198             <citerefentry><refentrytitle>glColorMask</refentrytitle></citerefentry>,
 199             <citerefentry><refentrytitle>glDrawBuffers</refentrytitle></citerefentry>,
 200             <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
 201             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>
 202         </para>
 203     </refsect1>
 204     <refsect1 id="Copyright"><title>Copyright</title>
 205         <para>
 206             Copyright <trademark class="copyright"></trademark> 1991-2006
 207             Silicon Graphics, Inc. This document is licensed under the SGI
 208             Free Software B License. For details, see
 209             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 210         </para>
 211     </refsect1>
 212 </refentry>