upstream-doc/man2/glFog.xml

   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="glFog">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glFog</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glFog</refname>
  17         <refpurpose>specify fog parameters</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glFogf</function></funcdef>
  23                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  24                 <paramdef>GLfloat <parameter>param</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27         <funcsynopsis>
  28             <funcprototype>
  29                 <funcdef>void <function>glFogi</function></funcdef>
  30                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  31                 <paramdef>GLint <parameter>param</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  36     <refsect1 id="parameters"><title>Parameters</title>
  37         <variablelist>
  38         <varlistentry>
  39             <term><parameter>pname</parameter></term>
  40             <listitem>
  41                 <para>
  42                     Specifies a single-valued fog parameter.
  43                     <constant>GL_FOG_MODE</constant>,
  44                     <constant>GL_FOG_DENSITY</constant>,
  45                     <constant>GL_FOG_START</constant>,
  46                     <constant>GL_FOG_END</constant>,
  47                     <constant>GL_FOG_INDEX</constant>, and
  48                     <constant>GL_FOG_COORD_SRC</constant>
  49                     are accepted.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>param</parameter></term>
  55             <listitem>
  56                 <para>
  57                     Specifies the value that <parameter>pname</parameter> will be set to.
  58                 </para>
  59             </listitem>
  60         </varlistentry>
  61         </variablelist>
  62     </refsect1>
  63     <refsynopsisdiv><title>C Specification</title>
  64         <funcsynopsis>
  65             <funcprototype>
  66                 <funcdef>void <function>glFogfv</function></funcdef>
  67                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  68                 <paramdef>const GLfloat * <parameter>params</parameter></paramdef>
  69             </funcprototype>
  70         </funcsynopsis>
  71         <funcsynopsis>
  72             <funcprototype>
  73                 <funcdef>void <function>glFogiv</function></funcdef>
  74                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  75                 <paramdef>const GLint * <parameter>params</parameter></paramdef>
  76             </funcprototype>
  77         </funcsynopsis>
  78     </refsynopsisdiv>
  79     <refsect1 id="parameters2"><title>Parameters</title>
  80         <variablelist>
  81         <varlistentry>
  82             <term><parameter>pname</parameter></term>
  83             <listitem>
  84                 <para>
  85                     Specifies a fog parameter.
  86                     <constant>GL_FOG_MODE</constant>,
  87                     <constant>GL_FOG_DENSITY</constant>,
  88                     <constant>GL_FOG_START</constant>,
  89                     <constant>GL_FOG_END</constant>,
  90                     <constant>GL_FOG_INDEX</constant>,
  91                     <constant>GL_FOG_COLOR</constant>, and
  92                     <constant>GL_FOG_COORD_SRC</constant>
  93                     are accepted.
  94                 </para>
  95             </listitem>
  96         </varlistentry>
  97         <varlistentry>
  98             <term><parameter>params</parameter></term>
  99             <listitem>
 100                 <para>
 101                     Specifies the value or values to be assigned to <parameter>pname</parameter>.
 102                     <constant>GL_FOG_COLOR</constant> requires an array of four values.
 103                     All other parameters accept an array containing only a single value.
 104                 </para>
 105             </listitem>
 106         </varlistentry>
 107         </variablelist>
 108     </refsect1>
 109     <refsect1 id="description"><title>Description</title>
 110         <para>
 111             Fog is initially disabled.
 112             While enabled, fog affects rasterized geometry,
 113             bitmaps, and pixel blocks, but not buffer clear operations. To enable
 114             and disable fog, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
 115             <constant>GL_FOG</constant>.
 116         </para>
 117         <para>
 118             <function>glFog</function> assigns the value or values in <parameter>params</parameter> to the fog parameter
 119             specified by <parameter>pname</parameter>.
 120             The following values are accepted for <parameter>pname</parameter>:
 121         </para>
 122         <variablelist>
 123             <varlistentry>
 124                 <term><constant>GL_FOG_MODE</constant></term>
 125                 <listitem>
 126                     <para>
 127                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 128                         the equation to be used to compute the fog blend factor,
 129                         <inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>.
 130                         Three symbolic constants are accepted:
 131                         <constant>GL_LINEAR</constant>,
 132                         <constant>GL_EXP</constant>,
 133                         and <constant>GL_EXP2</constant>.
 134                         The equations corresponding to these symbolic constants are defined below.
 135                         The initial fog mode is <constant>GL_EXP</constant>.
 136                     </para>
 137                 </listitem>
 138             </varlistentry>
 139             <varlistentry>
 140                 <term><constant>GL_FOG_DENSITY</constant></term>
 141                 <listitem>
 142                     <para>
 143                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 144                         <inlineequation><mml:math><mml:mi mathvariant="italic">density</mml:mi></mml:math></inlineequation>,
 145                         the fog density used in both exponential fog equations.
 146                         Only nonnegative densities are accepted.
 147                         The initial fog density is 1.
 148                     </para>
 149                 </listitem>
 150             </varlistentry>
 151             <varlistentry>
 152                 <term><constant>GL_FOG_START</constant></term>
 153                 <listitem>
 154                     <para>
 155                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 156                         <inlineequation><mml:math><mml:mi mathvariant="italic">start</mml:mi></mml:math></inlineequation>,
 157                         the near distance used in the linear fog equation.
 158                         The initial near distance is 0.
 159                     </para>
 160                 </listitem>
 161             </varlistentry>
 162             <varlistentry>
 163                 <term><constant>GL_FOG_END</constant></term>
 164                 <listitem>
 165                     <para>
 166                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 167                         <inlineequation><mml:math><mml:mi mathvariant="italic">end</mml:mi></mml:math></inlineequation>,
 168                         the far distance used in the linear fog equation.
 169                         The initial far distance is 1.
 170                     </para>
 171                 </listitem>
 172             </varlistentry>
 173             <varlistentry>
 174                 <term><constant>GL_FOG_INDEX</constant></term>
 175                 <listitem>
 176                     <para>
 177                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 178                         <inlineequation><mml:math>
 179                             <!-- eqn: i sub f:-->
 180                             <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 181                             <mml:mi mathvariant="italic">f</mml:mi>
 182                             </mml:msub>
 183                         </mml:math></inlineequation>,
 184                         the fog color index.
 185                         The initial fog index is 0.
 186                     </para>
 187                 </listitem>
 188             </varlistentry>
 189             <varlistentry>
 190                 <term><constant>GL_FOG_COLOR</constant></term>
 191                 <listitem>
 192                     <para>
 193                         <parameter>params</parameter> contains four integer or floating-point values that specify
 194                         <inlineequation><mml:math>
 195                             <!-- eqn: C sub f:-->
 196                             <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 197                             <mml:mi mathvariant="italic">f</mml:mi>
 198                             </mml:msub>
 199                         </mml:math></inlineequation>,
 200                         the fog color.
 201                         Integer values are mapped linearly such that the most positive representable
 202                         value maps to 1.0,
 203                         and the most negative representable value maps to
 204                         <inlineequation><mml:math>
 205                             <!-- eqn: -1.0:-->
 206                             <mml:mn>-1.0</mml:mn>
 207                         </mml:math></inlineequation>.
 208                         Floating-point values are mapped directly.
 209                         After conversion,
 210                         all color components are clamped to the range
 211                         <inlineequation><mml:math>
 212                             <!-- eqn: [0,1]:-->
 213                             <mml:mfenced open="[" close="]">
 214                                 <mml:mn>0</mml:mn>
 215                                 <mml:mn>1</mml:mn>
 216                             </mml:mfenced>
 217                         </mml:math></inlineequation>.
 218                         The initial fog color is (0, 0, 0, 0).
 219                     </para>
 220                 </listitem>
 221             </varlistentry>
 222             <varlistentry>
 223                 <term><constant>GL_FOG_COORD_SRC</constant></term>
 224                 <listitem>
 225                     <para>
 226                         <parameter>params</parameter> contains either of the following symbolic constants:
 227                         <constant>GL_FOG_COORD</constant> or <constant>GL_FRAGMENT_DEPTH</constant>.  <constant>GL_FOG_COORD</constant>
 228                         specifies that the current fog coordinate should be used as distance value
 229                         in the fog color computation.  <constant>GL_FRAGMENT_DEPTH</constant> specifies that the
 230                         current fragment depth should be used as distance value in the fog
 231                         computation.
 232                     </para>
 233                 </listitem>
 234             </varlistentry>
 235         </variablelist>
 236         <para>
 237             Fog blends a fog color with each rasterized pixel fragment's post-texturing
 238             color using a blending factor
 239             <inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>.
 240             Factor
 241             <inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
 242             is computed in one of three ways,
 243             depending on the fog mode.
 244             Let
 245             <inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
 246             be either the distance in eye coordinate from the origin (in the
 247             case that the <constant>GL_FOG_COORD_SRC</constant> is <constant>GL_FRAGMENT_DEPTH</constant>) or
 248             the current fog coordinate (in the case that <constant>GL_FOG_COORD_SRC</constant>
 249             is <constant>GL_FOG_COORD</constant>).
 250             The equation for <constant>GL_LINEAR</constant> fog is
 251             <informalequation><mml:math>
 252                 <!-- eqn: f  =  {end  -  c} over {end  -  start}:-->
 253                 <mml:mrow>
 254                     <mml:mi mathvariant="italic">f</mml:mi>
 255                     <mml:mo>=</mml:mo>
 256                     <mml:mfrac>
 257                         <mml:mfenced open="" close="">
 258                             <mml:mrow>
 259                                 <mml:mi mathvariant="italic">end</mml:mi>
 260                                 <mml:mo>-</mml:mo>
 261                                 <mml:mi mathvariant="italic">c</mml:mi>
 262                             </mml:mrow>
 263                         </mml:mfenced>
 264                         <mml:mfenced open="" close="">
 265                             <mml:mrow>
 266                                 <mml:mi mathvariant="italic">end</mml:mi>
 267                                 <mml:mo>-</mml:mo>
 268                                 <mml:mi mathvariant="italic">start</mml:mi>
 269                             </mml:mrow>
 270                         </mml:mfenced>
 271                     </mml:mfrac>
 272                 </mml:mrow>
 273             </mml:math></informalequation>
 274         </para>
 275         <para>
 276             The equation for <constant>GL_EXP</constant> fog is
 277             <informalequation><mml:math>
 278                 <!-- eqn: f  =  e sup {-(density  cdot  c)}:-->
 279                 <mml:mrow>
 280                     <mml:mi mathvariant="italic">f</mml:mi>
 281                     <mml:mo>=</mml:mo>
 282                     <mml:msup><mml:mi mathvariant="italic">e</mml:mi>
 283                     <mml:mfenced open="" close="">
 284                         <mml:mrow>
 285                             <mml:mo>-</mml:mo>
 286                             <mml:mfenced open="(" close=")">
 287                                 <mml:mrow>
 288                                     <mml:mi mathvariant="italic">density</mml:mi>
 289                                     <mml:mo>&CenterDot;</mml:mo>
 290                                     <mml:mi mathvariant="italic">c</mml:mi>
 291                                 </mml:mrow>
 292                             </mml:mfenced>
 293                         </mml:mrow>
 294                     </mml:mfenced>
 295                     </mml:msup>
 296                 </mml:mrow>
 297             </mml:math></informalequation>
 298         </para>
 299         <para>
 300             The equation for <constant>GL_EXP2</constant> fog is
 301             <informalequation><mml:math>
 302                 <!-- eqn: f  =  e sup {-(density  cdot  c)} sup 2:-->
 303                 <mml:mrow>
 304                     <mml:mi mathvariant="italic">f</mml:mi>
 305                     <mml:mo>=</mml:mo>
 306                     <mml:msup><mml:mi mathvariant="italic">e</mml:mi>
 307                     <mml:msup><mml:mfenced open="" close="">
 308                         <mml:mrow>
 309                             <mml:mo>-</mml:mo>
 310                             <mml:mfenced open="(" close=")">
 311                                 <mml:mrow>
 312                                     <mml:mi mathvariant="italic">density</mml:mi>
 313                                     <mml:mo>&CenterDot;</mml:mo>
 314                                     <mml:mi mathvariant="italic">c</mml:mi>
 315                                 </mml:mrow>
 316                             </mml:mfenced>
 317                         </mml:mrow>
 318                     </mml:mfenced>
 319                     <mml:mn>2</mml:mn>
 320                     </mml:msup></mml:msup>
 321                 </mml:mrow>
 322             </mml:math></informalequation>
 323         </para>
 324         <para>
 325             Regardless of the fog mode,
 326             <inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
 327             is clamped to the range
 328             <inlineequation><mml:math>
 329                 <!-- eqn: [0,1]:-->
 330                 <mml:mfenced open="[" close="]">
 331                     <mml:mn>0</mml:mn>
 332                     <mml:mn>1</mml:mn>
 333                 </mml:mfenced>
 334             </mml:math></inlineequation>
 335             after it is computed.
 336             Then,
 337             if the GL is in RGBA color mode,
 338             the fragment's red, green, and blue colors, represented by
 339             <inlineequation><mml:math>
 340                 <!-- eqn: C sub r:-->
 341                 <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 342                 <mml:mi mathvariant="italic">r</mml:mi>
 343                 </mml:msub>
 344             </mml:math></inlineequation>,
 345             are replaced by
 346         </para>
 347         <para>
 348             <informalequation><mml:math>
 349                 <!-- eqn: {C sub r} sup prime  =  f * C sub r  +  (1 - f) * C sub f:-->
 350                 <mml:mrow>
 351                     <mml:msup><mml:mfenced open="" close="">
 352                         <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 353                         <mml:mi mathvariant="italic">r</mml:mi>
 354                         </mml:msub>
 355                     </mml:mfenced>
 356                     <mml:mo>&Prime;</mml:mo>
 357                     </mml:msup>
 358                     <mml:mo>=</mml:mo>
 359                     <mml:mrow>
 360                         <mml:mrow>
 361                             <mml:mi mathvariant="italic">f</mml:mi>
 362                             <mml:mo>&times;</mml:mo>
 363                             <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 364                             <mml:mi mathvariant="italic">r</mml:mi>
 365                             </mml:msub>
 366                         </mml:mrow>
 367                         <mml:mo>+</mml:mo>
 368                         <mml:mrow>
 369                             <mml:mfenced open="(" close=")">
 370                                 <mml:mrow>
 371                                     <mml:mn>1</mml:mn>
 372                                     <mml:mo>-</mml:mo>
 373                                     <mml:mi mathvariant="italic">f</mml:mi>
 374                                 </mml:mrow>
 375                             </mml:mfenced>
 376                             <mml:mo>&times;</mml:mo>
 377                             <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 378                             <mml:mi mathvariant="italic">f</mml:mi>
 379                             </mml:msub>
 380                         </mml:mrow>
 381                     </mml:mrow>
 382                 </mml:mrow>
 383             </mml:math></informalequation>
 384         </para>
 385         <para>
 386             Fog does not affect a fragment's alpha component.
 387         </para>
 388         <para>
 389             In color index mode, the fragment's color index
 390             <inlineequation><mml:math>
 391                 <!-- eqn: i sub r:-->
 392                 <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 393                 <mml:mi mathvariant="italic">r</mml:mi>
 394                 </mml:msub>
 395             </mml:math></inlineequation>
 396             is replaced by
 397         </para>
 398         <para>
 399             <informalequation><mml:math>
 400                 <!-- eqn: {i sub r} sup prime  =  i sub r  +  (1 - f) * i sub f:-->
 401                 <mml:mrow>
 402                     <mml:msup><mml:mfenced open="" close="">
 403                         <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 404                         <mml:mi mathvariant="italic">r</mml:mi>
 405                         </mml:msub>
 406                     </mml:mfenced>
 407                     <mml:mo>&Prime;</mml:mo>
 408                     </mml:msup>
 409                     <mml:mo>=</mml:mo>
 410                     <mml:mrow>
 411                         <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 412                         <mml:mi mathvariant="italic">r</mml:mi>
 413                         </mml:msub>
 414                         <mml:mo>+</mml:mo>
 415                         <mml:mrow>
 416                             <mml:mfenced open="(" close=")">
 417                                 <mml:mrow>
 418                                     <mml:mn>1</mml:mn>
 419                                     <mml:mo>-</mml:mo>
 420                                     <mml:mi mathvariant="italic">f</mml:mi>
 421                                 </mml:mrow>
 422                             </mml:mfenced>
 423                             <mml:mo>&times;</mml:mo>
 424                             <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 425                             <mml:mi mathvariant="italic">f</mml:mi>
 426                             </mml:msub>
 427                         </mml:mrow>
 428                     </mml:mrow>
 429                 </mml:mrow>
 430             </mml:math></informalequation>
 431         </para>
 432         <para>
 433         </para>
 434     </refsect1>
 435     <refsect1 id="notes"><title>Notes</title>
 436         <para>
 437             <constant>GL_FOG_COORD_SRC</constant> is available only if the GL version is 1.4 or
 438             greater.
 439         </para>
 440     </refsect1>
 441     <refsect1 id="errors"><title>Errors</title>
 442         <para>
 443             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter> is not an accepted value,
 444             or if <parameter>pname</parameter> is <constant>GL_FOG_MODE</constant> and <parameter>params</parameter> is not an accepted value.
 445         </para>
 446         <para>
 447             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>pname</parameter> is <constant>GL_FOG_DENSITY</constant>
 448             and <parameter>params</parameter> is negative.
 449         </para>
 450         <para>
 451             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glFog</function>
 452             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 453             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 454         </para>
 455     </refsect1>
 456     <refsect1 id="associatedgets"><title>Associated Gets</title>
 457         <para>
 458             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_FOG</constant>
 459         </para>
 460         <para>
 461             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_COLOR</constant>
 462         </para>
 463         <para>
 464             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_INDEX</constant>
 465         </para>
 466         <para>
 467             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_DENSITY</constant>
 468         </para>
 469         <para>
 470             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_START</constant>
 471         </para>
 472         <para>
 473             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_END</constant>
 474         </para>
 475         <para>
 476             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FOG_MODE</constant>
 477         </para>
 478     </refsect1>
 479     <refsect1 id="seealso"><title>See Also</title>
 480         <para>
 481             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
 482         </para>
 483     </refsect1>
 484     <refsect1 id="Copyright"><title>Copyright</title>
 485         <para>
 486             Copyright <trademark class="copyright"></trademark> 1991-2006
 487             Silicon Graphics, Inc. This document is licensed under the SGI
 488             Free Software B License. For details, see
 489             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 490         </para>
 491     </refsect1>
 492 </refentry>