upstream-doc/man2/xhtml/glFog.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glFog</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glFog"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glFog — specify fog parameters</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glFogf</b>(</code></td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>GLfloat  </td><td><var class="pdparam">param</var><code>)</code>;</td></tr></table></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glFogi</b>(</code></td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">param</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
   4                     Specifies a single-valued fog parameter.
   5                     <code class="constant">GL_FOG_MODE</code>,
   6                     <code class="constant">GL_FOG_DENSITY</code>,
   7                     <code class="constant">GL_FOG_START</code>,
   8                     <code class="constant">GL_FOG_END</code>,
   9                     <code class="constant">GL_FOG_INDEX</code>, and
  10                     <code class="constant">GL_FOG_COORD_SRC</code>
  11                     are accepted.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>param</code></em></span></dt><dd><p>
  13                     Specifies the value that <em class="parameter"><code>pname</code></em> will be set to.
  14                 </p></dd></dl></div></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glFogfv</b>(</code></td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>const GLfloat *  </td><td><var class="pdparam">params</var><code>)</code>;</td></tr></table></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glFogiv</b>(</code></td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>const GLint *  </td><td><var class="pdparam">params</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters2"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
  15                     Specifies a fog parameter.
  16                     <code class="constant">GL_FOG_MODE</code>,
  17                     <code class="constant">GL_FOG_DENSITY</code>,
  18                     <code class="constant">GL_FOG_START</code>,
  19                     <code class="constant">GL_FOG_END</code>,
  20                     <code class="constant">GL_FOG_INDEX</code>,
  21                     <code class="constant">GL_FOG_COLOR</code>, and
  22                     <code class="constant">GL_FOG_COORD_SRC</code>
  23                     are accepted.
  24                 </p></dd><dt><span class="term"><em class="parameter"><code>params</code></em></span></dt><dd><p>
  25                     Specifies the value or values to be assigned to <em class="parameter"><code>pname</code></em>.
  26                     <code class="constant">GL_FOG_COLOR</code> requires an array of four values.
  27                     All other parameters accept an array containing only a single value.
  28                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  29             Fog is initially disabled.
  30             While enabled, fog affects rasterized geometry,
  31             bitmaps, and pixel blocks, but not buffer clear operations. To enable
  32             and disable fog, call <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a> and <a class="citerefentry" href="glDisable.xml"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a> with argument
  33             <code class="constant">GL_FOG</code>.
  34         </p><p>
  35             <code class="function">glFog</code> assigns the value or values in <em class="parameter"><code>params</code></em> to the fog parameter
  36             specified by <em class="parameter"><code>pname</code></em>.
  37             The following values are accepted for <em class="parameter"><code>pname</code></em>:
  38         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_FOG_MODE</code></span></dt><dd><p>
  39                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
  40                         the equation to be used to compute the fog blend factor,
  41                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">f</mml:mi></mml:math>.
  42                         Three symbolic constants are accepted:
  43                         <code class="constant">GL_LINEAR</code>,
  44                         <code class="constant">GL_EXP</code>,
  45                         and <code class="constant">GL_EXP2</code>.
  46                         The equations corresponding to these symbolic constants are defined below.
  47                         The initial fog mode is <code class="constant">GL_EXP</code>.
  48                     </p></dd><dt><span class="term"><code class="constant">GL_FOG_DENSITY</code></span></dt><dd><p>
  49                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
  50                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">density</mml:mi></mml:math>,
  51                         the fog density used in both exponential fog equations.
  52                         Only nonnegative densities are accepted.
  53                         The initial fog density is 1.
  54                     </p></dd><dt><span class="term"><code class="constant">GL_FOG_START</code></span></dt><dd><p>
  55                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
  56                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">start</mml:mi></mml:math>,
  57                         the near distance used in the linear fog equation.
  58                         The initial near distance is 0.
  59                     </p></dd><dt><span class="term"><code class="constant">GL_FOG_END</code></span></dt><dd><p>
  60                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
  61                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">end</mml:mi></mml:math>,
  62                         the far distance used in the linear fog equation.
  63                         The initial far distance is 1.
  64                     </p></dd><dt><span class="term"><code class="constant">GL_FOG_INDEX</code></span></dt><dd><p>
  65                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
  66                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  67
  68                             <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
  69                             <mml:mi mathvariant="italic">f</mml:mi>
  70                             </mml:msub>
  71                         </mml:math>,
  72                         the fog color index.
  73                         The initial fog index is 0.
  74                     </p></dd><dt><span class="term"><code class="constant">GL_FOG_COLOR</code></span></dt><dd><p>
  75                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
  76                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  77
  78                             <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
  79                             <mml:mi mathvariant="italic">f</mml:mi>
  80                             </mml:msub>
  81                         </mml:math>,
  82                         the fog color.
  83                         Integer values are mapped linearly such that the most positive representable
  84                         value maps to 1.0,
  85                         and the most negative representable value maps to
  86                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  87
  88                             <mml:mn>-1.0</mml:mn>
  89                         </mml:math>.
  90                         Floating-point values are mapped directly.
  91                         After conversion,
  92                         all color components are clamped to the range
  93                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  94
  95                             <mml:mfenced open="[" close="]">
  96                                 <mml:mn>0</mml:mn>
  97                                 <mml:mn>1</mml:mn>
  98                             </mml:mfenced>
  99                         </mml:math>.
 100                         The initial fog color is (0, 0, 0, 0).
 101                     </p></dd><dt><span class="term"><code class="constant">GL_FOG_COORD_SRC</code></span></dt><dd><p>
 102                         <em class="parameter"><code>params</code></em> contains either of the following symbolic constants:
 103                         <code class="constant">GL_FOG_COORD</code> or <code class="constant">GL_FRAGMENT_DEPTH</code>.  <code class="constant">GL_FOG_COORD</code>
 104                         specifies that the current fog coordinate should be used as distance value
 105                         in the fog color computation.  <code class="constant">GL_FRAGMENT_DEPTH</code> specifies that the
 106                         current fragment depth should be used as distance value in the fog
 107                         computation.
 108                     </p></dd></dl></div><p>
 109             Fog blends a fog color with each rasterized pixel fragment's post-texturing
 110             color using a blending factor
 111             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">f</mml:mi></mml:math>.
 112             Factor
 113             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">f</mml:mi></mml:math>
 114             is computed in one of three ways,
 115             depending on the fog mode.
 116             Let
 117             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">c</mml:mi></mml:math>
 118             be either the distance in eye coordinate from the origin (in the
 119             case that the <code class="constant">GL_FOG_COORD_SRC</code> is <code class="constant">GL_FRAGMENT_DEPTH</code>) or
 120             the current fog coordinate (in the case that <code class="constant">GL_FOG_COORD_SRC</code>
 121             is <code class="constant">GL_FOG_COORD</code>).
 122             The equation for <code class="constant">GL_LINEAR</code> fog is
 123             </p><div class="informalequation"><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 124
 125                 <mml:mrow>
 126                     <mml:mi mathvariant="italic">f</mml:mi>
 127                     <mml:mo>=</mml:mo>
 128                     <mml:mfrac>
 129                         <mml:mfenced open="" close="">
 130                             <mml:mrow>
 131                                 <mml:mi mathvariant="italic">end</mml:mi>
 132                                 <mml:mo>-</mml:mo>
 133                                 <mml:mi mathvariant="italic">c</mml:mi>
 134                             </mml:mrow>
 135                         </mml:mfenced>
 136                         <mml:mfenced open="" close="">
 137                             <mml:mrow>
 138                                 <mml:mi mathvariant="italic">end</mml:mi>
 139                                 <mml:mo>-</mml:mo>
 140                                 <mml:mi mathvariant="italic">start</mml:mi>
 141                             </mml:mrow>
 142                         </mml:mfenced>
 143                     </mml:mfrac>
 144                 </mml:mrow>
 145             </mml:math></div><p>
 146         </p><p>
 147             The equation for <code class="constant">GL_EXP</code> fog is
 148             </p><div class="informalequation"><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 149
 150                 <mml:mrow>
 151                     <mml:mi mathvariant="italic">f</mml:mi>
 152                     <mml:mo>=</mml:mo>
 153                     <mml:msup><mml:mi mathvariant="italic">e</mml:mi>
 154                     <mml:mfenced open="" close="">
 155                         <mml:mrow>
 156                             <mml:mo>-</mml:mo>
 157                             <mml:mfenced open="(" close=")">
 158                                 <mml:mrow>
 159                                     <mml:mi mathvariant="italic">density</mml:mi>
 160                                     <mml:mo>·</mml:mo>
 161                                     <mml:mi mathvariant="italic">c</mml:mi>
 162                                 </mml:mrow>
 163                             </mml:mfenced>
 164                         </mml:mrow>
 165                     </mml:mfenced>
 166                     </mml:msup>
 167                 </mml:mrow>
 168             </mml:math></div><p>
 169         </p><p>
 170             The equation for <code class="constant">GL_EXP2</code> fog is
 171             </p><div class="informalequation"><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 172
 173                 <mml:mrow>
 174                     <mml:mi mathvariant="italic">f</mml:mi>
 175                     <mml:mo>=</mml:mo>
 176                     <mml:msup><mml:mi mathvariant="italic">e</mml:mi>
 177                     <mml:msup><mml:mfenced open="" close="">
 178                         <mml:mrow>
 179                             <mml:mo>-</mml:mo>
 180                             <mml:mfenced open="(" close=")">
 181                                 <mml:mrow>
 182                                     <mml:mi mathvariant="italic">density</mml:mi>
 183                                     <mml:mo>·</mml:mo>
 184                                     <mml:mi mathvariant="italic">c</mml:mi>
 185                                 </mml:mrow>
 186                             </mml:mfenced>
 187                         </mml:mrow>
 188                     </mml:mfenced>
 189                     <mml:mn>2</mml:mn>
 190                     </mml:msup></mml:msup>
 191                 </mml:mrow>
 192             </mml:math></div><p>
 193         </p><p>
 194             Regardless of the fog mode,
 195             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">f</mml:mi></mml:math>
 196             is clamped to the range
 197             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 198
 199                 <mml:mfenced open="[" close="]">
 200                     <mml:mn>0</mml:mn>
 201                     <mml:mn>1</mml:mn>
 202                 </mml:mfenced>
 203             </mml:math>
 204             after it is computed.
 205             Then,
 206             if the GL is in RGBA color mode,
 207             the fragment's red, green, and blue colors, represented by
 208             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 209
 210                 <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 211                 <mml:mi mathvariant="italic">r</mml:mi>
 212                 </mml:msub>
 213             </mml:math>,
 214             are replaced by
 215         </p><p>
 216             </p><div class="informalequation"><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 217
 218                 <mml:mrow>
 219                     <mml:msup><mml:mfenced open="" close="">
 220                         <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 221                         <mml:mi mathvariant="italic">r</mml:mi>
 222                         </mml:msub>
 223                     </mml:mfenced>
 224                     <mml:mo>″</mml:mo>
 225                     </mml:msup>
 226                     <mml:mo>=</mml:mo>
 227                     <mml:mrow>
 228                         <mml:mrow>
 229                             <mml:mi mathvariant="italic">f</mml:mi>
 230                             <mml:mo>×</mml:mo>
 231                             <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 232                             <mml:mi mathvariant="italic">r</mml:mi>
 233                             </mml:msub>
 234                         </mml:mrow>
 235                         <mml:mo>+</mml:mo>
 236                         <mml:mrow>
 237                             <mml:mfenced open="(" close=")">
 238                                 <mml:mrow>
 239                                     <mml:mn>1</mml:mn>
 240                                     <mml:mo>-</mml:mo>
 241                                     <mml:mi mathvariant="italic">f</mml:mi>
 242                                 </mml:mrow>
 243                             </mml:mfenced>
 244                             <mml:mo>×</mml:mo>
 245                             <mml:msub><mml:mi mathvariant="italic">C</mml:mi>
 246                             <mml:mi mathvariant="italic">f</mml:mi>
 247                             </mml:msub>
 248                         </mml:mrow>
 249                     </mml:mrow>
 250                 </mml:mrow>
 251             </mml:math></div><p>
 252         </p><p>
 253             Fog does not affect a fragment's alpha component.
 254         </p><p>
 255             In color index mode, the fragment's color index
 256             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 257
 258                 <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 259                 <mml:mi mathvariant="italic">r</mml:mi>
 260                 </mml:msub>
 261             </mml:math>
 262             is replaced by
 263         </p><p>
 264             </p><div class="informalequation"><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 265
 266                 <mml:mrow>
 267                     <mml:msup><mml:mfenced open="" close="">
 268                         <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 269                         <mml:mi mathvariant="italic">r</mml:mi>
 270                         </mml:msub>
 271                     </mml:mfenced>
 272                     <mml:mo>″</mml:mo>
 273                     </mml:msup>
 274                     <mml:mo>=</mml:mo>
 275                     <mml:mrow>
 276                         <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 277                         <mml:mi mathvariant="italic">r</mml:mi>
 278                         </mml:msub>
 279                         <mml:mo>+</mml:mo>
 280                         <mml:mrow>
 281                             <mml:mfenced open="(" close=")">
 282                                 <mml:mrow>
 283                                     <mml:mn>1</mml:mn>
 284                                     <mml:mo>-</mml:mo>
 285                                     <mml:mi mathvariant="italic">f</mml:mi>
 286                                 </mml:mrow>
 287                             </mml:mfenced>
 288                             <mml:mo>×</mml:mo>
 289                             <mml:msub><mml:mi mathvariant="italic">i</mml:mi>
 290                             <mml:mi mathvariant="italic">f</mml:mi>
 291                             </mml:msub>
 292                         </mml:mrow>
 293                     </mml:mrow>
 294                 </mml:mrow>
 295             </mml:math></div><p>
 296         </p><p>
 297         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 298             <code class="constant">GL_FOG_COORD_SRC</code> is available only if the GL version is 1.4 or
 299             greater.
 300         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 301             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>pname</code></em> is not an accepted value,
 302             or if <em class="parameter"><code>pname</code></em> is <code class="constant">GL_FOG_MODE</code> and <em class="parameter"><code>params</code></em> is not an accepted value.
 303         </p><p>
 304             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>pname</code></em> is <code class="constant">GL_FOG_DENSITY</code>
 305             and <em class="parameter"><code>params</code></em> is negative.
 306         </p><p>
 307             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glFog</code>
 308             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
 309             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 310         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 311             <a class="citerefentry" href="glIsEnabled.xml"><span class="citerefentry"><span class="refentrytitle">glIsEnabled</span></span></a> with argument <code class="constant">GL_FOG</code>
 312         </p><p>
 313             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FOG_COLOR</code>
 314         </p><p>
 315             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FOG_INDEX</code>
 316         </p><p>
 317             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FOG_DENSITY</code>
 318         </p><p>
 319             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FOG_START</code>
 320         </p><p>
 321             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FOG_END</code>
 322         </p><p>
 323             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FOG_MODE</code>
 324         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 325             <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>
 326         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 327             Copyright <span class="trademark"></span>© 1991-2006
 328             Silicon Graphics, Inc. This document is licensed under the SGI
 329             Free Software B License. For details, see
 330             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 331         </p></div></div></body></html>