300 lines
14 KiB
XML
300 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
|
|
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
|
|
<refentry id="glAccum">
|
|
<refmeta>
|
|
<refmetainfo>
|
|
<copyright>
|
|
<year>1991-2006</year>
|
|
<holder>Silicon Graphics, Inc.</holder>
|
|
</copyright>
|
|
</refmetainfo>
|
|
<refentrytitle>glAccum</refentrytitle>
|
|
<manvolnum>3G</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>glAccum</refname>
|
|
<refpurpose>operate on the accumulation buffer</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glAccum</function></funcdef>
|
|
<paramdef>GLenum <parameter>op</parameter></paramdef>
|
|
<paramdef>GLfloat <parameter>value</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<!-- eqn: ignoring delim $$ -->
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>op</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the accumulation buffer operation.
|
|
Symbolic constants
|
|
<constant>GL_ACCUM</constant>,
|
|
<constant>GL_LOAD</constant>,
|
|
<constant>GL_ADD</constant>,
|
|
<constant>GL_MULT</constant>,
|
|
and
|
|
<constant>GL_RETURN</constant> are accepted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>value</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a floating-point value used in the accumulation buffer operation.
|
|
<parameter>op</parameter> determines how <parameter>value</parameter> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1 id="description"><title>Description</title>
|
|
<para>
|
|
The accumulation buffer is an extended-range color buffer.
|
|
Images are not rendered into it.
|
|
Rather,
|
|
images rendered into one of the color buffers
|
|
are added to the contents of the accumulation buffer after rendering.
|
|
Effects such as antialiasing (of points, lines, and polygons),
|
|
motion blur,
|
|
and depth of field can be created
|
|
by accumulating images generated with different transformation matrices.
|
|
</para>
|
|
<para>
|
|
Each pixel in the accumulation buffer consists of
|
|
red, green, blue, and alpha values.
|
|
The number of bits per component in the accumulation buffer
|
|
depends on the implementation. You can examine this number
|
|
by calling <citerefentry><refentrytitle>glGetIntegerv</refentrytitle></citerefentry> four times,
|
|
with arguments <constant>GL_ACCUM_RED_BITS</constant>,
|
|
<constant>GL_ACCUM_GREEN_BITS</constant>,
|
|
<constant>GL_ACCUM_BLUE_BITS</constant>,
|
|
and <constant>GL_ACCUM_ALPHA_BITS</constant>.
|
|
Regardless of the number of bits per component,
|
|
the range of values stored by each component is
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: [-1,1]:-->
|
|
<mml:mfenced open="[" close="]">
|
|
<mml:mn>-1</mml:mn>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mfenced>
|
|
</mml:math></inlineequation>.
|
|
The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.
|
|
</para>
|
|
<para>
|
|
<function>glAccum</function> operates on the accumulation buffer.
|
|
The first argument, <parameter>op</parameter>,
|
|
is a symbolic constant that selects an accumulation buffer operation.
|
|
The second argument, <parameter>value</parameter>,
|
|
is a floating-point value to be used in that operation.
|
|
Five operations are specified:
|
|
<constant>GL_ACCUM</constant>, <constant>GL_LOAD</constant>, <constant>GL_ADD</constant>,
|
|
<constant>GL_MULT</constant>, and <constant>GL_RETURN</constant>.
|
|
</para>
|
|
<para>
|
|
All accumulation buffer operations are limited
|
|
to the area of the current scissor box and applied identically to
|
|
the red, green, blue, and alpha components of each pixel.
|
|
If a <function>glAccum</function> operation results in a value outside the range
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: [-1,1]:-->
|
|
<mml:mfenced open="[" close="]">
|
|
<mml:mn>-1</mml:mn>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mfenced>
|
|
</mml:math></inlineequation>,
|
|
the contents of an accumulation buffer pixel component are undefined.
|
|
</para>
|
|
<para>
|
|
The operations are as follows:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>GL_ACCUM</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Obtains R, G, B, and A values
|
|
from the buffer currently selected for reading (see <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>).
|
|
Each component value is divided by
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: 2 sup n - 1:-->
|
|
<mml:mrow>
|
|
<mml:msup><mml:mn>2</mml:mn>
|
|
<mml:mi mathvariant="italic">n</mml:mi>
|
|
</mml:msup>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mrow>
|
|
</mml:math></inlineequation>,
|
|
where
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
|
|
is the number of bits allocated to each color component
|
|
in the currently selected buffer.
|
|
The result is a floating-point value in the range
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: [0,1]:-->
|
|
<mml:mfenced open="[" close="]">
|
|
<mml:mn>0</mml:mn>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mfenced>
|
|
</mml:math></inlineequation>,
|
|
which is multiplied by <parameter>value</parameter> and added to the corresponding pixel component
|
|
in the accumulation buffer,
|
|
thereby updating the accumulation buffer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_LOAD</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Similar to <constant>GL_ACCUM</constant>,
|
|
except that the current value in the accumulation buffer is not used
|
|
in the calculation of the new value.
|
|
That is, the R, G, B, and A values from the currently selected buffer
|
|
are divided by
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: 2 sup n - 1:-->
|
|
<mml:mrow>
|
|
<mml:msup><mml:mn>2</mml:mn>
|
|
<mml:mi mathvariant="italic">n</mml:mi>
|
|
</mml:msup>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mrow>
|
|
</mml:math></inlineequation>,
|
|
multiplied by <parameter>value</parameter>,
|
|
and then stored in the corresponding accumulation buffer cell,
|
|
overwriting the current value.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_ADD</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Adds <parameter>value</parameter> to each R, G, B, and A
|
|
in the accumulation buffer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_MULT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Multiplies each R, G, B, and A
|
|
in the accumulation buffer by <parameter>value</parameter> and returns the scaled component
|
|
to its corresponding accumulation buffer location.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_RETURN</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Transfers accumulation buffer values
|
|
to the color buffer or buffers currently selected for writing.
|
|
Each R, G, B, and A component is multiplied by <parameter>value</parameter>,
|
|
then multiplied by
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: 2 sup n - 1:-->
|
|
<mml:mrow>
|
|
<mml:msup><mml:mn>2</mml:mn>
|
|
<mml:mi mathvariant="italic">n</mml:mi>
|
|
</mml:msup>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mrow>
|
|
</mml:math></inlineequation>,
|
|
clamped to the range
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: [0, 2 sup n - 1]:-->
|
|
<mml:mfenced open="[" close="]">
|
|
<mml:mn>0</mml:mn>
|
|
<mml:mrow>
|
|
<mml:msup><mml:mn>2</mml:mn>
|
|
<mml:mi mathvariant="italic">n</mml:mi>
|
|
</mml:msup>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mn>1</mml:mn>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
</mml:math></inlineequation>,
|
|
and stored
|
|
in the corresponding display buffer cell.
|
|
The only fragment operations that are applied to this transfer are
|
|
pixel ownership,
|
|
scissor,
|
|
dithering,
|
|
and color writemasks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
To clear the accumulation buffer, call <citerefentry><refentrytitle>glClearAccum</refentrytitle></citerefentry> with R, G, B,
|
|
and A values to set it to, then call <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> with the
|
|
accumulation buffer enabled.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="notes"><title>Notes</title>
|
|
<para>
|
|
Only pixels within the current scissor box are updated by a
|
|
<function>glAccum</function> operation.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="errors"><title>Errors</title>
|
|
<para>
|
|
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>op</parameter> is not an accepted value.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_OPERATION</constant> is generated if there is no accumulation buffer.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glAccum</function>
|
|
is executed between the execution of
|
|
<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="associatedgets"><title>Associated Gets</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_RED_BITS</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_GREEN_BITS</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_BLUE_BITS</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_ACCUM_ALPHA_BITS</constant>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="seealso"><title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glClearAccum</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
|
<para>
|
|
Copyright <trademark class="copyright"></trademark> 1991-2006
|
|
Silicon Graphics, Inc. This document is licensed under the SGI
|
|
Free Software B License. For details, see
|
|
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|