<?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>&CenterDot;</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>&CenterDot;</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>&Prime;</mml:mo>
                    </mml:msup>
                    <mml:mo>=</mml:mo>
                    <mml:mrow>
                        <mml:mrow>
                            <mml:mi mathvariant="italic">f</mml:mi>
                            <mml:mo>&times;</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>&times;</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>&Prime;</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>&times;</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>
