upstream-doc/man2/glAccum.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="glAccum">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glAccum</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glAccum</refname>
  17         <refpurpose>operate on the accumulation buffer</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glAccum</function></funcdef>
  23                 <paramdef>GLenum <parameter>op</parameter></paramdef>
  24                 <paramdef>GLfloat <parameter>value</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <!-- eqn: ignoring delim $$ -->
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>op</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies the accumulation buffer operation.
  36                     Symbolic constants
  37                     <constant>GL_ACCUM</constant>,
  38                     <constant>GL_LOAD</constant>,
  39                     <constant>GL_ADD</constant>,
  40                     <constant>GL_MULT</constant>,
  41                     and
  42                     <constant>GL_RETURN</constant> are accepted.
  43                 </para>
  44             </listitem>
  45         </varlistentry>
  46         <varlistentry>
  47             <term><parameter>value</parameter></term>
  48             <listitem>
  49                 <para>
  50                     Specifies a floating-point value used in the accumulation buffer operation.
  51                     <parameter>op</parameter> determines how <parameter>value</parameter> is used.
  52                 </para>
  53             </listitem>
  54         </varlistentry>
  55         </variablelist>
  56     </refsect1>
  57     <refsect1 id="description"><title>Description</title>
  58         <para>
  59             The accumulation buffer is an extended-range color buffer.
  60             Images are not rendered into it.
  61             Rather,
  62             images rendered into one of the color buffers
  63             are added to the contents of the accumulation buffer after rendering.
  64             Effects such as antialiasing (of points, lines, and polygons),
  65             motion blur,
  66             and depth of field can be created
  67             by accumulating images generated with different transformation matrices.
  68         </para>
  69         <para>
  70             Each pixel in the accumulation buffer consists of
  71             red, green, blue, and alpha values.
  72             The number of bits per component in the accumulation buffer
  73             depends on the implementation. You can examine this number
  74             by calling <citerefentry><refentrytitle>glGetIntegerv</refentrytitle></citerefentry> four times,
  75             with arguments <constant>GL_ACCUM_RED_BITS</constant>,
  76             <constant>GL_ACCUM_GREEN_BITS</constant>,
  77             <constant>GL_ACCUM_BLUE_BITS</constant>,
  78             and <constant>GL_ACCUM_ALPHA_BITS</constant>.
  79             Regardless of the number of bits per component,
  80             the range of values stored by each component is
  81             <inlineequation><mml:math>
  82                 <!-- eqn: [-1,1]:-->
  83                 <mml:mfenced open="[" close="]">
  84                     <mml:mn>-1</mml:mn>
  85                     <mml:mn>1</mml:mn>
  86                 </mml:mfenced>
  87             </mml:math></inlineequation>.
  88             The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.
  89         </para>
  90         <para>
  91             <function>glAccum</function> operates on the accumulation buffer.
  92             The first argument, <parameter>op</parameter>,
  93             is a symbolic constant that selects an accumulation buffer operation.
  94             The second argument, <parameter>value</parameter>,
  95             is a floating-point value to be used in that operation.
  96             Five operations are specified:
  97             <constant>GL_ACCUM</constant>, <constant>GL_LOAD</constant>, <constant>GL_ADD</constant>,
  98             <constant>GL_MULT</constant>, and <constant>GL_RETURN</constant>.
  99         </para>
 100         <para>
 101             All accumulation buffer operations are limited
 102             to the area of the current scissor box and applied identically to
 103             the red, green, blue, and alpha components of each pixel.
 104             If a <function>glAccum</function> operation results in a value outside the range
 105             <inlineequation><mml:math>
 106                 <!-- eqn: [-1,1]:-->
 107                 <mml:mfenced open="[" close="]">
 108                     <mml:mn>-1</mml:mn>
 109                     <mml:mn>1</mml:mn>
 110                 </mml:mfenced>
 111             </mml:math></inlineequation>,
 112             the contents of an accumulation buffer pixel component are undefined.
 113         </para>
 114         <para>
 115             The operations are as follows:
 116         </para>
 117         <variablelist>
 118             <varlistentry>
 119                 <term><constant>GL_ACCUM</constant></term>
 120                 <listitem>
 121                     <para>
 122                         Obtains R, G, B, and A values
 123                         from the buffer currently selected for reading (see <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>).
 124                         Each component value is divided by
 125                         <inlineequation><mml:math>
 126                             <!-- eqn: 2 sup n - 1:-->
 127                             <mml:mrow>
 128                                 <mml:msup><mml:mn>2</mml:mn>
 129                                 <mml:mi mathvariant="italic">n</mml:mi>
 130                                 </mml:msup>
 131                                 <mml:mo>-</mml:mo>
 132                                 <mml:mn>1</mml:mn>
 133                             </mml:mrow>
 134                         </mml:math></inlineequation>,
 135                         where
 136                         <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
 137                         is the number of bits allocated to each color component
 138                         in the currently selected buffer.
 139                         The result is a floating-point value in the range
 140                         <inlineequation><mml:math>
 141                             <!-- eqn: [0,1]:-->
 142                             <mml:mfenced open="[" close="]">
 143                                 <mml:mn>0</mml:mn>
 144                                 <mml:mn>1</mml:mn>
 145                             </mml:mfenced>
 146                         </mml:math></inlineequation>,
 147                         which is multiplied by <parameter>value</parameter> and added to the corresponding pixel component
 148                         in the accumulation buffer,
 149                         thereby updating the accumulation buffer.
 150                     </para>
 151                 </listitem>
 152             </varlistentry>
 153             <varlistentry>
 154                 <term><constant>GL_LOAD</constant></term>
 155                 <listitem>
 156                     <para>
 157                         Similar to <constant>GL_ACCUM</constant>,
 158                         except that the current value in the accumulation buffer is not used
 159                         in the calculation of the new value.
 160                         That is, the R, G, B, and A values from the currently selected buffer
 161                         are divided by
 162                         <inlineequation><mml:math>
 163                             <!-- eqn: 2 sup n - 1:-->
 164                             <mml:mrow>
 165                                 <mml:msup><mml:mn>2</mml:mn>
 166                                 <mml:mi mathvariant="italic">n</mml:mi>
 167                                 </mml:msup>
 168                                 <mml:mo>-</mml:mo>
 169                                 <mml:mn>1</mml:mn>
 170                             </mml:mrow>
 171                         </mml:math></inlineequation>,
 172                         multiplied by <parameter>value</parameter>,
 173                         and then stored in the corresponding accumulation buffer cell,
 174                         overwriting the current value.
 175                     </para>
 176                 </listitem>
 177             </varlistentry>
 178             <varlistentry>
 179                 <term><constant>GL_ADD</constant></term>
 180                 <listitem>
 181                     <para>
 182                         Adds <parameter>value</parameter> to each R, G, B, and A
 183                         in the accumulation buffer.
 184                     </para>
 185                 </listitem>
 186             </varlistentry>
 187             <varlistentry>
 188                 <term><constant>GL_MULT</constant></term>
 189                 <listitem>
 190                     <para>
 191                         Multiplies each R, G, B, and A
 192                         in the accumulation buffer by <parameter>value</parameter> and returns the scaled component
 193                         to its corresponding accumulation buffer location.
 194                     </para>
 195                 </listitem>
 196             </varlistentry>
 197             <varlistentry>
 198                 <term><constant>GL_RETURN</constant></term>
 199                 <listitem>
 200                     <para>
 201                         Transfers accumulation buffer values
 202                         to the color buffer or buffers currently selected for writing.
 203                         Each R, G, B, and A component is multiplied by <parameter>value</parameter>,
 204                         then multiplied by
 205                         <inlineequation><mml:math>
 206                             <!-- eqn: 2 sup n - 1:-->
 207                             <mml:mrow>
 208                                 <mml:msup><mml:mn>2</mml:mn>
 209                                 <mml:mi mathvariant="italic">n</mml:mi>
 210                                 </mml:msup>
 211                                 <mml:mo>-</mml:mo>
 212                                 <mml:mn>1</mml:mn>
 213                             </mml:mrow>
 214                         </mml:math></inlineequation>,
 215                         clamped to the range
 216                         <inlineequation><mml:math>
 217                             <!-- eqn: [0, 2 sup n - 1]:-->
 218                             <mml:mfenced open="[" close="]">
 219                                 <mml:mn>0</mml:mn>
 220                                 <mml:mrow>
 221                                     <mml:msup><mml:mn>2</mml:mn>
 222                                     <mml:mi mathvariant="italic">n</mml:mi>
 223                                     </mml:msup>
 224                                     <mml:mo>-</mml:mo>
 225                                     <mml:mn>1</mml:mn>
 226                                 </mml:mrow>
 227                             </mml:mfenced>
 228                         </mml:math></inlineequation>,
 229                         and stored
 230                         in the corresponding display buffer cell.
 231                         The only fragment operations that are applied to this transfer are
 232                         pixel ownership,
 233                         scissor,
 234                         dithering,
 235                         and color writemasks.
 236                     </para>
 237                 </listitem>
 238             </varlistentry>
 239         </variablelist>
 240         <para>
 241             To clear the accumulation buffer, call <citerefentry><refentrytitle>glClearAccum</refentrytitle></citerefentry> with R, G, B,
 242             and A values to set it to, then call <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> with the
 243             accumulation buffer enabled.
 244         </para>
 245     </refsect1>
 246     <refsect1 id="notes"><title>Notes</title>
 247         <para>
 248             Only pixels within the current scissor box are updated by a
 249             <function>glAccum</function> operation.
 250         </para>
 251     </refsect1>
 252     <refsect1 id="errors"><title>Errors</title>
 253         <para>
 254             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>op</parameter> is not an accepted value.
 255         </para>
 256         <para>
 257             <constant>GL_INVALID_OPERATION</constant> is generated if there is no accumulation buffer.
 258         </para>
 259         <para>
 260             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glAccum</function>
 261             is executed between the execution of
 262             <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 263         </para>
 264     </refsect1>
 265     <refsect1 id="associatedgets"><title>Associated Gets</title>
 266         <para>
 267             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_RED_BITS</constant>
 268         </para>
 269         <para>
 270             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_GREEN_BITS</constant>
 271         </para>
 272         <para>
 273             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_BLUE_BITS</constant>
 274         </para>
 275         <para>
 276             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_ALPHA_BITS</constant>
 277         </para>
 278     </refsect1>
 279     <refsect1 id="seealso"><title>See Also</title>
 280         <para>
 281             <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>,
 282             <citerefentry><refentrytitle>glClearAccum</refentrytitle></citerefentry>,
 283             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 284             <citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
 285             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
 286             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 287             <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
 288             <citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
 289             <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>
 290         </para>
 291     </refsect1>
 292     <refsect1 id="Copyright"><title>Copyright</title>
 293         <para>
 294             Copyright <trademark class="copyright"></trademark> 1991-2006
 295             Silicon Graphics, Inc. This document is licensed under the SGI
 296             Free Software B License. For details, see
 297             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 298         </para>
 299     </refsect1>
 300 </refentry>