| 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> |