Blame |
Last modification |
View Log
| RSS feed
<?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>