upstream-man-pages/man2/xhtml/glAccum.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glAccum</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glAccum"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glAccum — operate on the accumulation buffer</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glAccum</b>(</code></td><td>GLenum  </td><td><var class="pdparam">op</var>, </td></tr><tr><td> </td><td>GLfloat  </td><td><var class="pdparam">value</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>op</code></em></span></dt><dd><p>
   4                     Specifies the accumulation buffer operation.
   5                     Symbolic constants
   6                     <code class="constant">GL_ACCUM</code>,
   7                     <code class="constant">GL_LOAD</code>,
   8                     <code class="constant">GL_ADD</code>,
   9                     <code class="constant">GL_MULT</code>,
  10                     and
  11                     <code class="constant">GL_RETURN</code> are accepted.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>value</code></em></span></dt><dd><p>
  13                     Specifies a floating-point value used in the accumulation buffer operation.
  14                     <em class="parameter"><code>op</code></em> determines how <em class="parameter"><code>value</code></em> is used.
  15                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  16             The accumulation buffer is an extended-range color buffer.
  17             Images are not rendered into it.
  18             Rather,
  19             images rendered into one of the color buffers
  20             are added to the contents of the accumulation buffer after rendering.
  21             Effects such as antialiasing (of points, lines, and polygons),
  22             motion blur,
  23             and depth of field can be created
  24             by accumulating images generated with different transformation matrices.
  25         </p><p>
  26             Each pixel in the accumulation buffer consists of
  27             red, green, blue, and alpha values.
  28             The number of bits per component in the accumulation buffer
  29             depends on the implementation. You can examine this number
  30             by calling <a class="citerefentry" href="glGetIntegerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetIntegerv</span></span></a> four times,
  31             with arguments <code class="constant">GL_ACCUM_RED_BITS</code>,
  32             <code class="constant">GL_ACCUM_GREEN_BITS</code>,
  33             <code class="constant">GL_ACCUM_BLUE_BITS</code>,
  34             and <code class="constant">GL_ACCUM_ALPHA_BITS</code>.
  35             Regardless of the number of bits per component,
  36             the range of values stored by each component is
  37             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  38
  39                 <mml:mfenced open="[" close="]">
  40                     <mml:mn>-1</mml:mn>
  41                     <mml:mn>1</mml:mn>
  42                 </mml:mfenced>
  43             </mml:math>.
  44             The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.
  45         </p><p>
  46             <code class="function">glAccum</code> operates on the accumulation buffer.
  47             The first argument, <em class="parameter"><code>op</code></em>,
  48             is a symbolic constant that selects an accumulation buffer operation.
  49             The second argument, <em class="parameter"><code>value</code></em>,
  50             is a floating-point value to be used in that operation.
  51             Five operations are specified:
  52             <code class="constant">GL_ACCUM</code>, <code class="constant">GL_LOAD</code>, <code class="constant">GL_ADD</code>,
  53             <code class="constant">GL_MULT</code>, and <code class="constant">GL_RETURN</code>.
  54         </p><p>
  55             All accumulation buffer operations are limited
  56             to the area of the current scissor box and applied identically to
  57             the red, green, blue, and alpha components of each pixel.
  58             If a <code class="function">glAccum</code> operation results in a value outside the range
  59             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  60
  61                 <mml:mfenced open="[" close="]">
  62                     <mml:mn>-1</mml:mn>
  63                     <mml:mn>1</mml:mn>
  64                 </mml:mfenced>
  65             </mml:math>,
  66             the contents of an accumulation buffer pixel component are undefined.
  67         </p><p>
  68             The operations are as follows:
  69         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_ACCUM</code></span></dt><dd><p>
  70                         Obtains R, G, B, and A values
  71                         from the buffer currently selected for reading (see <a class="citerefentry" href="glReadBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glReadBuffer</span></span></a>).
  72                         Each component value is divided by
  73                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  74
  75                             <mml:mrow>
  76                                 <mml:msup><mml:mn>2</mml:mn>
  77                                 <mml:mi mathvariant="italic">n</mml:mi>
  78                                 </mml:msup>
  79                                 <mml:mo>-</mml:mo>
  80                                 <mml:mn>1</mml:mn>
  81                             </mml:mrow>
  82                         </mml:math>,
  83                         where
  84                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
  85                         is the number of bits allocated to each color component
  86                         in the currently selected buffer.
  87                         The result is a floating-point value in the range
  88                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  89
  90                             <mml:mfenced open="[" close="]">
  91                                 <mml:mn>0</mml:mn>
  92                                 <mml:mn>1</mml:mn>
  93                             </mml:mfenced>
  94                         </mml:math>,
  95                         which is multiplied by <em class="parameter"><code>value</code></em> and added to the corresponding pixel component
  96                         in the accumulation buffer,
  97                         thereby updating the accumulation buffer.
  98                     </p></dd><dt><span class="term"><code class="constant">GL_LOAD</code></span></dt><dd><p>
  99                         Similar to <code class="constant">GL_ACCUM</code>,
 100                         except that the current value in the accumulation buffer is not used
 101                         in the calculation of the new value.
 102                         That is, the R, G, B, and A values from the currently selected buffer
 103                         are divided by
 104                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 105
 106                             <mml:mrow>
 107                                 <mml:msup><mml:mn>2</mml:mn>
 108                                 <mml:mi mathvariant="italic">n</mml:mi>
 109                                 </mml:msup>
 110                                 <mml:mo>-</mml:mo>
 111                                 <mml:mn>1</mml:mn>
 112                             </mml:mrow>
 113                         </mml:math>,
 114                         multiplied by <em class="parameter"><code>value</code></em>,
 115                         and then stored in the corresponding accumulation buffer cell,
 116                         overwriting the current value.
 117                     </p></dd><dt><span class="term"><code class="constant">GL_ADD</code></span></dt><dd><p>
 118                         Adds <em class="parameter"><code>value</code></em> to each R, G, B, and A
 119                         in the accumulation buffer.
 120                     </p></dd><dt><span class="term"><code class="constant">GL_MULT</code></span></dt><dd><p>
 121                         Multiplies each R, G, B, and A
 122                         in the accumulation buffer by <em class="parameter"><code>value</code></em> and returns the scaled component
 123                         to its corresponding accumulation buffer location.
 124                     </p></dd><dt><span class="term"><code class="constant">GL_RETURN</code></span></dt><dd><p>
 125                         Transfers accumulation buffer values
 126                         to the color buffer or buffers currently selected for writing.
 127                         Each R, G, B, and A component is multiplied by <em class="parameter"><code>value</code></em>,
 128                         then multiplied by
 129                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 130
 131                             <mml:mrow>
 132                                 <mml:msup><mml:mn>2</mml:mn>
 133                                 <mml:mi mathvariant="italic">n</mml:mi>
 134                                 </mml:msup>
 135                                 <mml:mo>-</mml:mo>
 136                                 <mml:mn>1</mml:mn>
 137                             </mml:mrow>
 138                         </mml:math>,
 139                         clamped to the range
 140                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 141
 142                             <mml:mfenced open="[" close="]">
 143                                 <mml:mn>0</mml:mn>
 144                                 <mml:mrow>
 145                                     <mml:msup><mml:mn>2</mml:mn>
 146                                     <mml:mi mathvariant="italic">n</mml:mi>
 147                                     </mml:msup>
 148                                     <mml:mo>-</mml:mo>
 149                                     <mml:mn>1</mml:mn>
 150                                 </mml:mrow>
 151                             </mml:mfenced>
 152                         </mml:math>,
 153                         and stored
 154                         in the corresponding display buffer cell.
 155                         The only fragment operations that are applied to this transfer are
 156                         pixel ownership,
 157                         scissor,
 158                         dithering,
 159                         and color writemasks.
 160                     </p></dd></dl></div><p>
 161             To clear the accumulation buffer, call <a class="citerefentry" href="glClearAccum.xml"><span class="citerefentry"><span class="refentrytitle">glClearAccum</span></span></a> with R, G, B,
 162             and A values to set it to, then call <a class="citerefentry" href="glClear.xml"><span class="citerefentry"><span class="refentrytitle">glClear</span></span></a> with the
 163             accumulation buffer enabled.
 164         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 165             Only pixels within the current scissor box are updated by a
 166             <code class="function">glAccum</code> operation.
 167         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 168             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>op</code></em> is not an accepted value.
 169         </p><p>
 170             <code class="constant">GL_INVALID_OPERATION</code> is generated if there is no accumulation buffer.
 171         </p><p>
 172             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glAccum</code>
 173             is executed between the execution of
 174             <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 175         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 176             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_ACCUM_RED_BITS</code>
 177         </p><p>
 178             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_ACCUM_GREEN_BITS</code>
 179         </p><p>
 180             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_ACCUM_BLUE_BITS</code>
 181         </p><p>
 182             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_ACCUM_ALPHA_BITS</code>
 183         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 184             <a class="citerefentry" href="glClear.xml"><span class="citerefentry"><span class="refentrytitle">glClear</span></span></a>,
 185             <a class="citerefentry" href="glClearAccum.xml"><span class="citerefentry"><span class="refentrytitle">glClearAccum</span></span></a>,
 186             <a class="citerefentry" href="glCopyPixels.xml"><span class="citerefentry"><span class="refentrytitle">glCopyPixels</span></span></a>,
 187             <a class="citerefentry" href="glDrawBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glDrawBuffer</span></span></a>,
 188             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a>,
 189             <a class="citerefentry" href="glReadBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glReadBuffer</span></span></a>,
 190             <a class="citerefentry" href="glReadPixels.xml"><span class="citerefentry"><span class="refentrytitle">glReadPixels</span></span></a>,
 191             <a class="citerefentry" href="glScissor.xml"><span class="citerefentry"><span class="refentrytitle">glScissor</span></span></a>,
 192             <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>
 193         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 194             Copyright <span class="trademark"></span>© 1991-2006
 195             Silicon Graphics, Inc. This document is licensed under the SGI
 196             Free Software B License. For details, see
 197             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 198         </p></div></div></body></html>