Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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>·</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>·</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>″</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>×</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>×</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>″</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>×</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> |