492 lines
23 KiB
XML
492 lines
23 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="glFog">
|
|
<refmeta>
|
|
<refmetainfo>
|
|
<copyright>
|
|
<year>1991-2006</year>
|
|
<holder>Silicon Graphics, Inc.</holder>
|
|
</copyright>
|
|
</refmetainfo>
|
|
<refentrytitle>glFog</refentrytitle>
|
|
<manvolnum>3G</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>glFog</refname>
|
|
<refpurpose>specify fog parameters</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glFogf</function></funcdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>GLfloat <parameter>param</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glFogi</function></funcdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>GLint <parameter>param</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<!-- eqn: ignoring delim $$ -->
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>pname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a single-valued fog parameter.
|
|
<constant>GL_FOG_MODE</constant>,
|
|
<constant>GL_FOG_DENSITY</constant>,
|
|
<constant>GL_FOG_START</constant>,
|
|
<constant>GL_FOG_END</constant>,
|
|
<constant>GL_FOG_INDEX</constant>, and
|
|
<constant>GL_FOG_COORD_SRC</constant>
|
|
are accepted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>param</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the value that <parameter>pname</parameter> will be set to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glFogfv</function></funcdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>const GLfloat * <parameter>params</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glFogiv</function></funcdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>const GLint * <parameter>params</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="parameters2"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>pname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a fog parameter.
|
|
<constant>GL_FOG_MODE</constant>,
|
|
<constant>GL_FOG_DENSITY</constant>,
|
|
<constant>GL_FOG_START</constant>,
|
|
<constant>GL_FOG_END</constant>,
|
|
<constant>GL_FOG_INDEX</constant>,
|
|
<constant>GL_FOG_COLOR</constant>, and
|
|
<constant>GL_FOG_COORD_SRC</constant>
|
|
are accepted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>params</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the value or values to be assigned to <parameter>pname</parameter>.
|
|
<constant>GL_FOG_COLOR</constant> requires an array of four values.
|
|
All other parameters accept an array containing only a single value.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1 id="description"><title>Description</title>
|
|
<para>
|
|
Fog is initially disabled.
|
|
While enabled, fog affects rasterized geometry,
|
|
bitmaps, and pixel blocks, but not buffer clear operations. To enable
|
|
and disable fog, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
|
|
<constant>GL_FOG</constant>.
|
|
</para>
|
|
<para>
|
|
<function>glFog</function> assigns the value or values in <parameter>params</parameter> to the fog parameter
|
|
specified by <parameter>pname</parameter>.
|
|
The following values are accepted for <parameter>pname</parameter>:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_MODE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> is a single integer or floating-point value that specifies
|
|
the equation to be used to compute the fog blend factor,
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>.
|
|
Three symbolic constants are accepted:
|
|
<constant>GL_LINEAR</constant>,
|
|
<constant>GL_EXP</constant>,
|
|
and <constant>GL_EXP2</constant>.
|
|
The equations corresponding to these symbolic constants are defined below.
|
|
The initial fog mode is <constant>GL_EXP</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_DENSITY</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> is a single integer or floating-point value that specifies
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">density</mml:mi></mml:math></inlineequation>,
|
|
the fog density used in both exponential fog equations.
|
|
Only nonnegative densities are accepted.
|
|
The initial fog density is 1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_START</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> is a single integer or floating-point value that specifies
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">start</mml:mi></mml:math></inlineequation>,
|
|
the near distance used in the linear fog equation.
|
|
The initial near distance is 0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_END</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> is a single integer or floating-point value that specifies
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">end</mml:mi></mml:math></inlineequation>,
|
|
the far distance used in the linear fog equation.
|
|
The initial far distance is 1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_INDEX</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> is a single integer or floating-point value that specifies
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: i sub f:-->
|
|
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
</mml:msub>
|
|
</mml:math></inlineequation>,
|
|
the fog color index.
|
|
The initial fog index is 0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_COLOR</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> contains four integer or floating-point values that specify
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: C sub f:-->
|
|
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
</mml:msub>
|
|
</mml:math></inlineequation>,
|
|
the fog color.
|
|
Integer values are mapped linearly such that the most positive representable
|
|
value maps to 1.0,
|
|
and the most negative representable value maps to
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: -1.0:-->
|
|
<mml:mn>-1.0</mml:mn>
|
|
</mml:math></inlineequation>.
|
|
Floating-point values are mapped directly.
|
|
After conversion,
|
|
all color components are clamped to 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>.
|
|
The initial fog color is (0, 0, 0, 0).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FOG_COORD_SRC</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> contains either of the following symbolic constants:
|
|
<constant>GL_FOG_COORD</constant> or <constant>GL_FRAGMENT_DEPTH</constant>. <constant>GL_FOG_COORD</constant>
|
|
specifies that the current fog coordinate should be used as distance value
|
|
in the fog color computation. <constant>GL_FRAGMENT_DEPTH</constant> specifies that the
|
|
current fragment depth should be used as distance value in the fog
|
|
computation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
Fog blends a fog color with each rasterized pixel fragment's post-texturing
|
|
color using a blending factor
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>.
|
|
Factor
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
|
|
is computed in one of three ways,
|
|
depending on the fog mode.
|
|
Let
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
|
|
be either the distance in eye coordinate from the origin (in the
|
|
case that the <constant>GL_FOG_COORD_SRC</constant> is <constant>GL_FRAGMENT_DEPTH</constant>) or
|
|
the current fog coordinate (in the case that <constant>GL_FOG_COORD_SRC</constant>
|
|
is <constant>GL_FOG_COORD</constant>).
|
|
The equation for <constant>GL_LINEAR</constant> fog is
|
|
<informalequation><mml:math>
|
|
<!-- eqn: f = {end - c} over {end - start}:-->
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
<mml:mo>=</mml:mo>
|
|
<mml:mfrac>
|
|
<mml:mfenced open="" close="">
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">end</mml:mi>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mi mathvariant="italic">c</mml:mi>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
<mml:mfenced open="" close="">
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">end</mml:mi>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mi mathvariant="italic">start</mml:mi>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
</mml:mfrac>
|
|
</mml:mrow>
|
|
</mml:math></informalequation>
|
|
</para>
|
|
<para>
|
|
The equation for <constant>GL_EXP</constant> fog is
|
|
<informalequation><mml:math>
|
|
<!-- eqn: f = e sup {-(density cdot c)}:-->
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
<mml:mo>=</mml:mo>
|
|
<mml:msup><mml:mi mathvariant="italic">e</mml:mi>
|
|
<mml:mfenced open="" close="">
|
|
<mml:mrow>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mfenced open="(" close=")">
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">density</mml:mi>
|
|
<mml:mo>·</mml:mo>
|
|
<mml:mi mathvariant="italic">c</mml:mi>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
</mml:msup>
|
|
</mml:mrow>
|
|
</mml:math></informalequation>
|
|
</para>
|
|
<para>
|
|
The equation for <constant>GL_EXP2</constant> fog is
|
|
<informalequation><mml:math>
|
|
<!-- eqn: f = e sup {-(density cdot c)} sup 2:-->
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
<mml:mo>=</mml:mo>
|
|
<mml:msup><mml:mi mathvariant="italic">e</mml:mi>
|
|
<mml:msup><mml:mfenced open="" close="">
|
|
<mml:mrow>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mfenced open="(" close=")">
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">density</mml:mi>
|
|
<mml:mo>·</mml:mo>
|
|
<mml:mi mathvariant="italic">c</mml:mi>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
<mml:mn>2</mml:mn>
|
|
</mml:msup></mml:msup>
|
|
</mml:mrow>
|
|
</mml:math></informalequation>
|
|
</para>
|
|
<para>
|
|
Regardless of the fog mode,
|
|
<inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
|
|
is clamped to 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>
|
|
after it is computed.
|
|
Then,
|
|
if the GL is in RGBA color mode,
|
|
the fragment's red, green, and blue colors, represented by
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: C sub r:-->
|
|
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
|
|
<mml:mi mathvariant="italic">r</mml:mi>
|
|
</mml:msub>
|
|
</mml:math></inlineequation>,
|
|
are replaced by
|
|
</para>
|
|
<para>
|
|
<informalequation><mml:math>
|
|
<!-- eqn: {C sub r} sup prime = f * C sub r + (1 - f) * C sub f:-->
|
|
<mml:mrow>
|
|
<mml:msup><mml:mfenced open="" close="">
|
|
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
|
|
<mml:mi mathvariant="italic">r</mml:mi>
|
|
</mml:msub>
|
|
</mml:mfenced>
|
|
<mml:mo>″</mml:mo>
|
|
</mml:msup>
|
|
<mml:mo>=</mml:mo>
|
|
<mml:mrow>
|
|
<mml:mrow>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
<mml:mo>×</mml:mo>
|
|
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
|
|
<mml:mi mathvariant="italic">r</mml:mi>
|
|
</mml:msub>
|
|
</mml:mrow>
|
|
<mml:mo>+</mml:mo>
|
|
<mml:mrow>
|
|
<mml:mfenced open="(" close=")">
|
|
<mml:mrow>
|
|
<mml:mn>1</mml:mn>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
<mml:mo>×</mml:mo>
|
|
<mml:msub><mml:mi mathvariant="italic">C</mml:mi>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
</mml:msub>
|
|
</mml:mrow>
|
|
</mml:mrow>
|
|
</mml:mrow>
|
|
</mml:math></informalequation>
|
|
</para>
|
|
<para>
|
|
Fog does not affect a fragment's alpha component.
|
|
</para>
|
|
<para>
|
|
In color index mode, the fragment's color index
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: i sub r:-->
|
|
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
|
|
<mml:mi mathvariant="italic">r</mml:mi>
|
|
</mml:msub>
|
|
</mml:math></inlineequation>
|
|
is replaced by
|
|
</para>
|
|
<para>
|
|
<informalequation><mml:math>
|
|
<!-- eqn: {i sub r} sup prime = i sub r + (1 - f) * i sub f:-->
|
|
<mml:mrow>
|
|
<mml:msup><mml:mfenced open="" close="">
|
|
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
|
|
<mml:mi mathvariant="italic">r</mml:mi>
|
|
</mml:msub>
|
|
</mml:mfenced>
|
|
<mml:mo>″</mml:mo>
|
|
</mml:msup>
|
|
<mml:mo>=</mml:mo>
|
|
<mml:mrow>
|
|
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
|
|
<mml:mi mathvariant="italic">r</mml:mi>
|
|
</mml:msub>
|
|
<mml:mo>+</mml:mo>
|
|
<mml:mrow>
|
|
<mml:mfenced open="(" close=")">
|
|
<mml:mrow>
|
|
<mml:mn>1</mml:mn>
|
|
<mml:mo>-</mml:mo>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
</mml:mrow>
|
|
</mml:mfenced>
|
|
<mml:mo>×</mml:mo>
|
|
<mml:msub><mml:mi mathvariant="italic">i</mml:mi>
|
|
<mml:mi mathvariant="italic">f</mml:mi>
|
|
</mml:msub>
|
|
</mml:mrow>
|
|
</mml:mrow>
|
|
</mml:mrow>
|
|
</mml:math></informalequation>
|
|
</para>
|
|
<para>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="notes"><title>Notes</title>
|
|
<para>
|
|
<constant>GL_FOG_COORD_SRC</constant> is available only if the GL version is 1.4 or
|
|
greater.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="errors"><title>Errors</title>
|
|
<para>
|
|
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is not an accepted value,
|
|
or if <parameter>pname</parameter> is <constant>GL_FOG_MODE</constant> and <parameter>params</parameter> is not an accepted value.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>pname</parameter> is <constant>GL_FOG_DENSITY</constant>
|
|
and <parameter>params</parameter> is negative.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glFog</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>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_FOG</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_COLOR</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_INDEX</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_DENSITY</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_START</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_END</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_MODE</constant>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="seealso"><title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glEnable</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>
|