source: OGRE/trunk/ogrenew/Docs/manual/manual_16.html @ 692

Revision 692, 33.6 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies
Line 
1<HTML>
2<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3<!-- Created on , 12 2006 by texi2html 1.64 -->
4<!--
5Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6            Karl Berry  <karl@freefriends.org>
7            Olaf Bachmann <obachman@mathematik.uni-kl.de>
8            and many others.
9Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
10Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
11 
12-->
13<HEAD>
14<TITLE>OGRE Manual v1.2.0 ('Dagon'): Passes</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Passes">
17<META NAME="keywords" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Passes">
18<META NAME="resource-type" CONTENT="document">
19<META NAME="distribution" CONTENT="global">
20<META NAME="Generator" CONTENT="texi2html 1.64">
21<LINK TYPE="text/css" rel="stylesheet" href="../style.css"> 
22</HEAD>
23
24<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
25
26<A NAME="SEC35"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_15.html#SEC31"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_17.html#SEC61"> &gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36<HR SIZE=1>
37<H3> 3.1.2 Passes </H3>
38<!--docid::SEC35::-->
39A pass is a single render of the geometry in question; a single call to the rendering API with a certain set of rendering properties. A technique can have between one and 16 passes, although clearly the more passes you use, the more expensive the technique will be to render.<BR><BR>
40<P>
41
42To help clearly identify what each pass is used for, the pass can be named but its optional.  Passes not named within the script will take on a name that is the pass index number.  For example: the first pass in a technique is index 0 so its name would be "0" if it was not given a name in the script.  The pass name must be unqiue within the technique or else the final pass is the resulting merge of all passes with the same name in the technique.  A warning message is posted in the Ogre.log if this occurs.  Named passes can help when copying a material and modifying an existing pass: (See section <A HREF="manual_20.html#SEC106">3.1.6 Copying Materials</A>)<BR><BR>
43</P><P>
44
45Passes have a set of global attributes (described below), zero or more nested texture_unit entries (See section <A HREF="manual_17.html#SEC61">3.1.3 Texture Units</A>), and optionally a reference to a vertex and / or a fragment program (See section <A HREF="manual_19.html#SEC99">3.1.5 Using Vertex and Fragment Programs in a Pass</A>).
46</P><P>
47
48<BR><BR>
49Here are the attributes you can use in a 'pass' section of a .material script:
50</P><P>
51
52<UL>
53<LI>
54<A HREF="manual_16.html#SEC37">ambient</A>
55<LI>
56<A HREF="manual_16.html#SEC38">diffuse</A>
57<LI>
58<A HREF="manual_16.html#SEC39">specular</A>
59<LI>
60<A HREF="manual_16.html#SEC40">emissive</A>
61<LI>
62<A HREF="manual_16.html#SEC41">scene_blend</A>
63<LI>
64<A HREF="manual_16.html#SEC42">depth_check</A>
65<LI>
66<A HREF="manual_16.html#SEC43">depth_write</A>
67<LI>
68<A HREF="manual_16.html#SEC44">depth_func</A>
69<LI>
70<A HREF="manual_16.html#SEC45">depth_bias</A>
71<LI>
72<A HREF="manual_16.html#SEC46">alpha_rejection</A>
73<LI>
74<A HREF="manual_16.html#SEC47">cull_hardware</A>
75<LI>
76<A HREF="manual_16.html#SEC48">cull_software</A>
77<LI>
78<A HREF="manual_16.html#SEC49">lighting</A>
79<LI>
80<A HREF="manual_16.html#SEC50">shading</A>
81<LI>
82<A HREF="manual_16.html#SEC51">polygon_mode</A>
83<LI>
84<A HREF="manual_16.html#SEC52">fog_override</A>
85<LI>
86<A HREF="manual_16.html#SEC53">colour_write</A>
87<LI>
88<A HREF="manual_16.html#SEC54">max_lights</A>
89<LI>
90<A HREF="manual_16.html#SEC55">iteration</A>
91<LI>
92<A HREF="manual_16.html#SEC56">point_size</A>
93<LI>
94<A HREF="manual_16.html#SEC57">point_sprites</A>
95<LI>
96<A HREF="manual_16.html#SEC58">point_size_attenuation</A>
97<LI>
98<A HREF="manual_16.html#SEC59">point_size_min</A>
99<LI>
100<A HREF="manual_16.html#SEC60">point_size_max</A>
101</UL>
102<P>
103
104<A NAME="SEC36"></A>
105<H2> Attribute Descriptions </H2>
106<!--docid::SEC36::-->
107<A NAME="ambient"></A>
108<A NAME="SEC37"></A>
109<H3> ambient </H3>
110<!--docid::SEC37::-->
111<P>
112
113Sets the ambient colour reflectance properties of this pass. <STRONG>This attribute has no effect if a asm, CG, or HLSL shader program is used.  With GLSL, the shader can read the OpenGL material state.</STRONG> <BR><BR>
114</P><P>
115
116Format: ambient (&#60;red&#62; &#60;green&#62; &#60;blue&#62; [&#60;alpha&#62;]| vertexcolour)<BR>
117NB valid colour values are between 0.0 and 1.0.<BR><BR>
118</P><P>
119
120Example: ambient 0.0 0.8 0.0<BR><BR>
121</P><P>
122
123The base colour of a pass is determined by how much red, green and blue light is reflects at each vertex. This property determines how much ambient light (directionless global light) is reflected.
124It is also possible to make the ambient reflectance track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values.
125The default is full white, meaning objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light effects, or change the blend of colours to make the object have a base colour other than white. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.<BR><BR>
126</P><P>
127
128Default: ambient 1.0 1.0 1.0 1.0<BR><BR>
129</P><P>
130
131<A NAME="diffuse"></A>
132<A NAME="SEC38"></A>
133<H3> diffuse </H3>
134<!--docid::SEC38::-->
135<P>
136
137Sets the diffuse colour reflectance properties of this pass. <STRONG>This attribute has no effect if a asm, CG, or HLSL shader program is used.  With GLSL, the shader can read the OpenGL material state.</STRONG><BR><BR>
138</P><P>
139
140Format: diffuse (&#60;red&#62; &#60;green&#62; &#60;blue&#62; [&#60;alpha&#62;]| vertexcolour)<BR>
141NB valid colour values are between 0.0 and 1.0.<BR><BR>
142</P><P>
143
144Example: diffuse 1.0 0.5 0.5<BR><BR>
145</P><P>
146
147The base colour of a pass is determined by how much red, green and blue light is reflects at each vertex. This property determines how much diffuse light (light from instances of the Light class in the scene) is reflected.
148It is also possible to make the diffuse reflectance track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values.
149The default is full white, meaning objects reflect the maximum white light they can from Light objects. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.<BR><BR>
150</P><P>
151
152Default: diffuse 1.0 1.0 1.0 1.0<BR><BR>
153</P><P>
154
155<A NAME="specular"></A>
156<A NAME="SEC39"></A>
157<H3> specular </H3>
158<!--docid::SEC39::-->
159<P>
160
161Sets the specular colour reflectance properties of this pass. <STRONG>This attribute has no effect if a asm, CG, or HLSL shader program is used.  With GLSL, the shader can read the OpenGL material state.</STRONG><BR><BR>
162</P><P>
163
164Format: specular (&#60;red&#62; &#60;green&#62; &#60;blue&#62; [&#60;alpha&#62;]| vertexcolour) &#60;shininess&#62;<BR>
165NB valid colour values are between 0.0 and 1.0. Shininess can be any value greater than 0.<BR><BR>
166</P><P>
167
168Example: specular 1.0 1.0 1.0 12.5<BR><BR>
169</P><P>
170
171The base colour of a pass is determined by how much red, green and blue light is reflects at each vertex. This property determines how much specular light (highlights from instances of the Light class in the scene) is reflected.
172It is also possible to make the diffuse reflectance track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values.
173The default is to reflect no specular light. The colour of the specular highlights is determined by the colour parameters, and the size of the highlights by the separate shininess parameter.. The higher the value of the shininess parameter, the sharper the highlight ie the radius is smaller.  Beware of using shininess values in the range of 0 to 1 since this causes the the specular colour to be applied to the whole surface that has the material applied to it.  When the viewing angle to the surface changes, ugly flickering will also occur when shininess is in the range of 0 to 1.  Shininess values between 1 and 128 work best in both DirectX and OpenGL renderers.  This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.<BR><BR>
174</P><P>
175
176Default: specular 0.0 0.0 0.0 0.0 0.0<BR><BR>
177</P><P>
178
179<A NAME="emissive"></A>
180<A NAME="SEC40"></A>
181<H3> emissive </H3>
182<!--docid::SEC40::-->
183<P>
184
185Sets the amount of self-illumination an object has. <STRONG>This attribute has no effect if a asm, CG, or HLSL shader program is used.  With GLSL, the shader can read the OpenGL material state.</STRONG><BR><BR>
186</P><P>
187
188Format: emissive (&#60;red&#62; &#60;green&#62; &#60;blue&#62; [&#60;alpha&#62;]| vertexcolour)<BR>
189NB valid colour values are between 0.0 and 1.0.<BR><BR>
190</P><P>
191
192Example: emissive 1.0 0.0 0.0<BR><BR>
193</P><P>
194
195If an object is self-illuminating, it does not need external sources to light it, ambient or otherwise. It's like the object has it's own personal ambient light. Unlike the name suggests, this object doesn't act as a light source for other objects in the scene (if you want it to, you have to create a light which is centered on the object).
196It is also possible to make the emissive colour track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values.
197This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.<BR><BR>
198</P><P>
199
200Default: emissive 0.0 0.0 0.0 0.0<BR><BR>
201</P><P>
202
203<A NAME="scene_blend"></A>
204<A NAME="SEC41"></A>
205<H3> scene_blend </H3>
206<!--docid::SEC41::-->
207<P>
208
209Sets the kind of blending this pass has with the existing contents of the scene. Wheras the texture blending operations seen in the texture_unit entries are concerned with blending between texture layers, this blending is about combining the output of this pass as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects. There are 2 formats, one using predefined blend types, the other allowing a roll-your-own approach using source and destination factors.<BR><BR>
210</P><P>
211
212Format1: scene_blend &#60;add|modulate|alpha_blend|colour_blend&#62;<BR><BR>
213</P><P>
214
215Example: scene_blend add<BR><BR>
216</P><P>
217
218This is the simpler form, where the most commonly used blending modes are enumerated using a single parameter. Valid &#60;blend_type&#62; parameters are:
219<DL COMPACT>
220<DT>add
221<DD>The colour of the rendering output is added to the scene. Good for exposions, flares, lights, ghosts etc. Equivalent to 'scene_blend one one'.
222<DT>modulate
223<DD>The colour of the rendering output is multiplied with the scene contents. Generally colours and darkens the scene, good for smoked glass, semi-transparent objects etc. Equivalent to 'scene_blend dest_colour zero'.
224<DT>colour_blend
225<DD>Colour the scene based on the brightness of the input colours, but don't darken. Equivalent to 'scene_blend src_colour one_minus_src_colour'
226<DT>alpha_blend
227<DD>The alpha value of the rendering output is used as a mask. Equivalent to 'scene_blend src_alpha one_minus_src_alpha'
228</DL>
229<BR>
230Format2: scene_blend &#60;src_factor&#62; &#60;dest_factor&#62;<BR><BR>
231<P>
232
233Example: scene_blend one one_minus_dest_alpha<BR><BR>
234</P><P>
235
236This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors. The resulting colour which is written to the rendering target is (texture * sourceFactor) + (scene_pixel * destFactor). Valid values for both parameters are:
237<DL COMPACT>
238<DT>one
239<DD>Constant value of 1.0
240<DT>zero
241<DD>Constant value of 0.0
242<DT>dest_colour
243<DD>The existing pixel colour
244<DT>src_colour
245<DD>The texture pixel (texel) colour
246<DT>one_minus_dest_colour
247<DD>1 - (dest_colour)
248<DT>one_minus_src_colour
249<DD>1 - (src_colour)
250<DT>dest_alpha
251<DD>The existing pixel alpha value
252<DT>src_alpha
253<DD>The texel alpha value
254<DT>one_minus_dest_alpha
255<DD>1 - (dest_alpha)
256<DT>one_minus_src_alpha
257<DD>1 - (src_alpha)
258</DL>
259<BR>
260Default: scene_blend one zero (opaque)
261<BR>
262<A NAME="depth_check"></A>
263<A NAME="SEC42"></A>
264<H3> depth_check </H3>
265<!--docid::SEC42::-->
266<P>
267
268Sets whether or not this pass renders with depth-buffer checking on or not.<BR><BR>
269</P><P>
270
271Format: depth_check &#60;on|off&#62;<BR><BR>
272</P><P>
273
274If depth-buffer checking is on, whenever a pixel is about to be written to the frame buffer the depth buffer is checked to see if the pixel is in front of all other pixels written at that point. If not, the pixel is not written. If depth checking is off, pixels are written no matter what has been rendered before. Also see depth_func for more advanced depth check configuration.<BR><BR>
275</P><P>
276
277Default: depth_check on<BR><BR>
278</P><P>
279
280<A NAME="depth_write"></A>
281<A NAME="SEC43"></A>
282<H3> depth_write </H3>
283<!--docid::SEC43::-->
284<P>
285
286Sets whether or not this pass renders with depth-buffer writing on or not.<BR>
287</P><P>
288
289Format: depth_write &#60;on|off&#62;<BR><BR>
290</P><P>
291
292If depth-buffer writing is on, whenever a pixel is written to the frame buffer the depth buffer is updated with the depth value of that new pixel, thus affecting future rendering operations if future pixels are behind this one. If depth writing is off, pixels are written without updating the depth buffer. Depth writing should normally be on but can be turned off when rendering static backgrounds or when rendering a collection of transparent objects at the end of a scene so that they overlap each other correctly.<BR><BR>
293</P><P>
294
295Default: depth_write on<BR>
296</P><P>
297
298<A NAME="depth_func"></A>
299<A NAME="SEC44"></A>
300<H3> depth_func </H3>
301<!--docid::SEC44::-->
302<P>
303
304Sets the function used to compare depth values when depth checking is on.<BR><BR>
305</P><P>
306
307Format: depth_func &#60;func&#62;<BR><BR>
308</P><P>
309
310If depth checking is enabled (see depth_check) a comparison occurs between the depth value of the pixel to be written and the current contents of the buffer. This comparison is normally less_equal, i.e. the pixel is written if it is closer (or at the same distance) than the current contents. The possible functions are:
311<DL COMPACT>
312<DT>always_fail
313<DD>Never writes a pixel to the render target
314<DT>always_pass
315<DD>Always writes a pixel to the render target
316<DT>less
317<DD>Write if (new_Z &#60; existing_Z)
318<DT>less_equal
319<DD>Write if (new_Z &#60;= existing_Z)
320<DT>equal
321<DD>Write if (new_Z == existing_Z)
322<DT>not_equal
323<DD>Write if (new_Z != existing_Z)
324<DT>greater_equal
325<DD>Write if (new_Z &#62;= existing_Z)
326<DT>greater
327<DD>Write if (new_Z &#62;existing_Z)
328</DL>
329<BR>
330Default: depth_func less_equal
331<P>
332
333<A NAME="depth_bias"></A>
334<A NAME="SEC45"></A>
335<H3> depth_bias </H3>
336<!--docid::SEC45::-->
337<P>
338
339Sets the bias applied to the depth value of this pass. Can be used to make coplanar polygons appear on top of others e.g. for decals. <BR><BR>
340</P><P>
341
342Format: depth_bias &#60;value&#62;<BR><BR>
343</P><P>
344
345Where &#60;value&#62; is between 0 and 16, the default being 0. The higher the value, the greater the offset (for if you want to do multiple overlapping decals).<BR><BR>
346</P><P>
347
348<A NAME="alpha_rejection"></A>
349<A NAME="SEC46"></A>
350<H3> alpha_rejection </H3>
351<!--docid::SEC46::-->
352<P>
353
354Sets the way the pass will have use alpha to totally reject pixels from the pipeline.<BR><BR>
355</P><P>
356
357Format: alpha_rejection &#60;function&#62; &#60;value&#62;<BR><BR>
358</P><P>
359
360Example: alpha_rejection greater_equal 128<BR><BR>
361</P><P>
362
363The function parameter can be any of the options listed in the material depth_function attribute. The value parameter can theoretically be any value between 0 and 255, but is best limited to 0 or 128 for hardware compatibility.<BR><BR>
364</P><P>
365
366Default: alpha_rejection always_pass<BR><BR>
367</P><P>
368
369<A NAME="cull_hardware"></A>
370<A NAME="SEC47"></A>
371<H3> cull_hardware </H3>
372<!--docid::SEC47::-->
373<P>
374
375Sets the hardware culling mode for this pass.<BR><BR>
376</P><P>
377
378Format: cull_hardware &#60;clockwise|anticlockwise|none&#62;<BR><BR>
379</P><P>
380
381A typical way for the hardware rendering engine to cull triangles is based on the 'vertex winding' of triangles. Vertex winding refers to the direction in which the vertices are passed or indexed to in the rendering operation as viewed from the camera, and will wither be clockwise or anticlockwise (that's 'counterclockwise' for you Americans out there ;). If the option 'cull_hardware clockwise' is set, all triangles whose vertices are viewed in clockwise order from the camera will be culled by the hardware. 'anticlockwise' is the reverse (obviously), and 'none' turns off hardware culling so all triagles are rendered (useful for creating 2-sided passes).<BR><BR>
382</P><P>
383
384Default: cull_hardware clockwise<BR>
385NB this is the same as OpenGL's default but the opposite of Direct3D's default (because Ogre uses a right-handed coordinate system like OpenGL).
386</P><P>
387
388<A NAME="cull_software"></A>
389<A NAME="SEC48"></A>
390<H3> cull_software </H3>
391<!--docid::SEC48::-->
392<P>
393
394Sets the software culling mode for this pass.<BR><BR>
395</P><P>
396
397Format: cull_software &#60;back|front|none&#62;<BR><BR>
398</P><P>
399
400In some situations the engine will also cull geometry in software before sending it to the hardware renderer. This setting only takes effect on SceneManager's that use it (since it is best used on large groups of planar world geometry rather than on movable geometry since this would be expensive), but if used can cull geometry before it is sent to the hardware. In this case the culling is based on whether the 'back' or 'front' of the traingle is facing the camera - this definition is based on the face normal (a vector which sticks out of the front side of the polygon perpendicular to the face). Since Ogre expects face normals to be on anticlockwise side of the face, 'cull_software back' is the software equivalent of 'cull_hardware clockwise' setting, which is why they are both the default. The naming is different to reflect the way the culling is done though, since most of the time face normals are precalculated and they don't have to be the way Ogre expects - you could set 'cull_hardware none' and completely cull in software based on your own face normals, if you have the right SceneManager which uses them.<BR><BR>
401</P><P>
402
403Default: cull_software back<BR><BR>
404</P><P>
405
406<A NAME="lighting"></A>
407<A NAME="SEC49"></A>
408<H3> lighting </H3>
409<!--docid::SEC49::-->
410<P>
411
412Sets whether or not dynamic lighting is turned on for this pass or not. If lighting is turned off, all objects rendered using the pass will be fully lit. <STRONG>This attribute has no effect if a vertex program is used.</STRONG><BR><BR>
413</P><P>
414
415Format: lighting &#60;on|off&#62;<BR><BR>
416</P><P>
417
418Turning dynamic lighting off makes any ambient, diffuse, specular, emissive and shading properties for this pass redundant. When lighting is turned on, objects are lit according to their vertex normals for diffuse and specular light, and globally for ambient and emissive.<BR><BR>
419</P><P>
420
421Default: lighting on<BR><BR>
422</P><P>
423
424<A NAME="shading"></A>
425<A NAME="SEC50"></A>
426<H3> shading </H3>
427<!--docid::SEC50::-->
428<P>
429
430Sets the kind of shading which should be used for representing dynamic lighting for this pass.<BR><BR>
431</P><P>
432
433Format: shading &#60;flat|gouraud|phong&#62;<BR><BR>
434</P><P>
435
436When dynamic lighting is turned on, the effect is to generate colour values at each vertex. Whether these values are interpolated across the face (and how) depends on this setting.<BR><BR>
437<DL COMPACT>
438<DT>flat
439<DD>    No interpolation takes place. Each face is shaded with a single colour determined from the first vertex in the face.
440<DT>gouraud
441<DD>    Colour at each vertex is linearly interpolated across the face.
442<DT>phong
443<DD>    Vertex normals are interpolated across the face, and these are used to determine colour at each pixel. Gives a more natural lighting effect but is more expensive and works better at high levels of tesselation. Not supported on all hardware.
444</DL>
445Default: shading gouraud<BR><BR>
446<P>
447
448<A NAME="polygon_mode"></A>
449<A NAME="SEC51"></A>
450<H3> polygon_mode </H3>
451<!--docid::SEC51::-->
452<P>
453
454Sets how polygons should be rasterised, ie whether they should be filled in, or just drawn as lines or points.<BR><BR>
455</P><P>
456
457Format: polygon_mode &#60;solid|wireframe|points&#62;<BR><BR>
458</P><P>
459
460<DL COMPACT>
461<DT>solid
462<DD>The normal situation - polygons are filled in.
463<DT>wireframe
464<DD>Polygons are drawn in outline only.
465<DT>points
466<DD>Only the points of each polygon are rendered.
467</DL>
468Default: polygon_mode solid<BR><BR>
469<P>
470
471<A NAME="fog_override"></A>
472<A NAME="SEC52"></A>
473<H3> fog_override </H3>
474<!--docid::SEC52::-->
475<P>
476
477Tells the pass whether it should override the scene fog settings, and enforce it's own. Very useful for things that you don't want to be affected by fog when the rest of the scene is fogged, or vice versa.<BR><BR>
478</P><P>
479
480Format: fog_override &#60;override?&#62; [&#60;type&#62; &#60;colour&#62; &#60;density&#62; &#60;start&#62; &#60;end&#62;]<BR><BR>
481</P><P>
482
483Default: fog_override false<BR><BR>
484</P><P>
485
486If you specify 'true' for the first parameter and you supply the rest of the parameters, you are telling the pass to use these fog settings in preference to the scene settings, whatever they might be. If you specify 'true' but provide no further parameters, you are telling this pass to never use fogging no matter what the scene says. Here is an explanation of the parameters:<BR>
487<DL COMPACT>
488<DT>type
489<DD><STRONG>none</STRONG> = No fog, equivalent of just using 'fog_override true'<BR>
490<STRONG>linear</STRONG> = Linear fog from the &#60;start&#62; and &#60;end&#62; distances<BR>
491<STRONG>exp</STRONG> = Fog increases exponentially from the camera (fog = 1/e^(distance * density)), use &#60;density&#62; param to control it<BR>
492<STRONG>exp2</STRONG> = Fog increases at the square of FOG_EXP, i.e. even quicker (fog = 1/e^(distance * density)^2), use &#60;density&#62; param to control it
493<DT>colour
494<DD>    Sequence of 3 floating point values from 0 to 1 indicating the red, green and blue intensities
495<DT>density
496<DD>    The density parameter used in the 'exp' or 'exp2' fog types. Not used in linear mode but param must still be there as a placeholder
497<DT>start
498<DD>    The start distance from the camera of linear fog. Must still be present in other modes, even though it is not used.
499<DT>end
500<DD>    The end distance from the camera of linear fog. Must still be present in other modes, even though it is not used.
501</DL>
502<BR>
503Example: fog_override true exp 1 1 1 0.002 100 10000
504<P>
505
506<A NAME="colour_write"></A>
507<A NAME="SEC53"></A>
508<H3> colour_write </H3>
509<!--docid::SEC53::-->
510<P>
511
512Sets whether or not this pass renders with colour writing on or not.<BR>
513</P><P>
514
515Format: colour_write &#60;on|off&#62;<BR><BR>
516</P><P>
517
518If colour writing is off no visible pixels are written to the screen during this pass. You might think this is useless, but if you render with colour writing off, and with very minimal other settings, you can use this pass to initialise the depth buffer before subsequently rendering other passes which fill in the colour data. This can give you significant performance boosts on some newer cards, especially when using complex fragment programs, because if the depth check fails then the fragment program is never run. <BR><BR>
519</P><P>
520
521Default: colour_write on<BR>
522</P><P>
523
524<A NAME="max_lights"></A>
525<A NAME="SEC54"></A>
526<H3> max_lights </H3>
527<!--docid::SEC54::-->
528<P>
529
530Sets the maximum number of lights which will be considered for use with this pass.<BR><BR>
531Format: max_lights &#60;number&#62;<BR><BR>
532</P><P>
533
534The maximum number of lights which can be used when rendering fixed-function materials is set by the rendering system, and is typically set at 8. When you are using the programmable pipeline (See section <A HREF="manual_19.html#SEC99">3.1.5 Using Vertex and Fragment Programs in a Pass</A>) this limit is dependent on the program you are running, or, if you use 'iteration once_per_light' (See section <A HREF="manual_16.html#SEC55">iteration</A>), it effectively only bounded by the number of passes you are willing to use. Whichever method you use, however, the max_lights limit applies.<BR><BR>
535</P><P>
536
537Default: max_lights 8<BR>
538</P><P>
539
540<A NAME="iteration"></A>
541<A NAME="SEC55"></A>
542<H3> iteration </H3>
543<!--docid::SEC55::-->
544<P>
545
546Sets whether or not this pass is iterated, ie issued more than once.<BR><BR>
547</P><P>
548
549Basic Format: iteration &#60;once | once_per_light&#62; [lightType]<BR><BR>
550Advanced Format: iteration &#60;number&#62; [&#60;per_light&#62; [lightType]]<BR><BR>
551Examples:
552<DL COMPACT>
553<DT>iteration once
554<DD>    The pass is only executed once which is the default behaviour.
555<DT>iteration once_per_light point
556<DD>    The pass is executed once for each point light.
557<DT>iteration 5
558<DD>    The render state for the pass will be setup and then the draw call will execute 5 times.
559<DT>iteration 5 per_light point
560<DD>    The render state for the pass will be setup and then the draw call will execute 5 times.  This will be done for each point light.
561</DL>
562<BR>
563<P>
564
565By default, passes are only issued once. However, if you use the programmable pipeline, or you wish to exceed the normal limits on the number of lights which are supported, you might want to use the once_per_light option. In this case, only light index 0 is ever used, and the pass is issued multiple times, each time with a different light in light index 0. Clearly this will make the pass more expensive, but it may be the only way to achieve certain effects such as per-pixel lighting effects which take into account 1..n lights.<BR><BR>
566</P><P>
567
568Using a number instead of "once" instructs the pass to iterate more than once after the render state is setup.  The render state is not changed after the initial setup so repeated draw calls are very fast and ideal for passes using programmable shaders that must iterate more than once with the same render state ie. shaders that do fur, motion blur, special filtering.<BR><BR>
569</P><P>
570
571If you use once_per_light, you should also add an ambient pass to the technique before this pass, otherwise when no lights are in range of this object it will not get rendered at all; this is important even when you have no ambient light in the scene, because you would still want the objects sihouette to appear.<BR><BR>
572</P><P>
573
574The second parameter to the attribute only applies if you use once_per_light or per_light, and restricts the pass to being run for lights of a single type (either 'point', 'directional' or 'spot'). In the example, the pass will be run once per point light. This can be useful because when you're writing a vertex / fragment program it is a lot better if you can assume the kind of lights you'll be dealing with.
575<BR><BR>
576Default: iteration once<BR><BR>
577</P><P>
578
579<A NAME="fur_example"></A>
580Example: Simple Fur shader material script that uses a second pass with 10 iterations to grow the fur:
581<TABLE><tr><td>&nbsp;</td><td class=example><pre>// GLSL simple Fur
582vertex_program GLSLDemo/FurVS glsl
583{
584  source fur.vert
585  default_params
586  {
587    param_named_auto lightPosition light_position_object_space 0
588    param_named_auto eyePosition camera_position_object_space
589    param_named_auto passNumber pass_number
590    param_named_auto multiPassNumber pass_iteration_number
591    param_named furLength float 0.15
592  }
593}
594
595fragment_program GLSLDemo/FurFS glsl
596{
597  source fur.frag
598  default_params
599  {
600    param_named Ka float 0.2
601    param_named Kd float 0.5
602    param_named Ks float 0.0
603    param_named furTU int 0
604  }
605}
606
607material Fur
608{
609  technique GLSL
610  {
611    pass base_coat
612    {
613      ambient 0.7 0.7 0.7
614      diffuse 0.5 0.8 0.5
615      specular 1.0 1.0 1.0 1.5
616
617      vertex_program_ref GLSLDemo/FurVS
618      {
619      }
620
621      fragment_program_ref GLSLDemo/FurFS
622      {
623      }
624
625      texture_unit
626      {
627        texture Fur.tga
628        tex_coord_set 0
629        filtering trilinear
630      }
631
632    }
633
634    pass grow_fur
635    {
636      ambient 0.7 0.7 0.7
637      diffuse 0.8 1.0 0.8
638      specular 1.0 1.0 1.0 64
639      depth_write off
640
641      scene_blend src_alpha one
642      iteration 10
643     
644      vertex_program_ref GLSLDemo/FurVS
645      {
646      }
647
648      fragment_program_ref GLSLDemo/FurFS
649      {
650      }
651
652      texture_unit
653      {
654        texture Fur.tga
655        tex_coord_set 0
656        filtering trilinear
657      }
658    }
659  }
660}
661</pre></td></tr></table>Note: use gpu program auto parameters  <A HREF="manual_19.html#pass_number">pass_number</A> and  <A HREF="manual_19.html#pass_iteration_number">pass_iteration_number</A> to tell the vertex or fragment program the pass number and iteration number.<BR><BR>
662</P><P>
663
664<A NAME="point_size"></A>
665<A NAME="SEC56"></A>
666<H3> point_size </H3>
667<!--docid::SEC56::-->
668<P>
669
670This setting allows you to change the size of points when rendering a point list, or a list of point sprites. The interpretation of this command depends on the <A HREF="manual_16.html#SEC58">point_size_attenuation</A> option - if it is off (the default), the point size is in screen pixels, if it is on, it expressed as normalised screen coordinates (1.0 is the height of the screen) when the point is at the origin.  <BR><BR>
671</P><P>
672
673NOTE: Some drivers have an upper limit on the size of points they support - this can even vary between APIs on the same card! Don't rely on point sizes that cause the points to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.<BR><BR>
674</P><P>
675
676Format: point_size &#60;size&#62;<BR><BR>
677Default: point_size 1.0<BR><BR>
678</P><P>
679
680<A NAME="point_sprites"></A>
681<A NAME="SEC57"></A>
682<H3> point_sprites </H3>
683<!--docid::SEC57::-->
684<P>
685
686This setting specifies whether or not hardware point sprite rendering is enabled for this pass. Enabling it means that a point list is rendered as a list of quads rather than a list of dots. It is very useful to use this option if you're using a billboardset and only need to use point oriented billboards which are all of the same size. You can also use it for any other point list render. <BR><BR>
687</P><P>
688
689Format: point_sprites &#60;on|off&#62;<BR><BR>
690Default: point_sprites off<BR><BR>
691</P><P>
692
693<A NAME="point_size_attenuation"></A>
694<A NAME="SEC58"></A>
695<H3> point_size_attenuation </H3>
696<!--docid::SEC58::-->
697<P>
698
699Defines whether point size is attenuated with view space distance, and in what fashion. This option is especially useful when you're using point sprites (See section <A HREF="manual_16.html#SEC57">point_sprites</A>) since it defines how they reduce in size as they get further away from the camera. You can also disable this option to make point sprites a constant screen size (like points), or enable it for points so they change size with distance.<BR><BR>
700</P><P>
701
702You only have to provide the final 3 parameters if you turn attenuation on. The formula for attenuation is that the size of the point is multiplied by 1 / (constant + linear * dist + quadratic * d^2); therefore turning it off is equivalent to (constant = 1, linear = 0, quadratic = 0) and standard perspective attenuation is (constant = 0, linear = 1, quadratic = 0). The latter is assumed if you leave out the final 3 parameters when you specify 'on'.<BR><BR>
703</P><P>
704
705Note that the resulting attenuated size is clamped to the minimum and maximum point size, see the next section.<BR><BR>
706</P><P>
707
708Format: point_size_attenuation &#60;on|off&#62; [constant linear quadratic]
709Default: point_size_attenuation off
710</P><P>
711
712<A NAME="point_size_min"></A>
713<A NAME="SEC59"></A>
714<H3> point_size_min </H3>
715<!--docid::SEC59::-->
716<P>
717
718Sets the minimum point size after attenuation (<A HREF="manual_16.html#SEC58">point_size_attenuation</A>). For details on the size metrics, See section <A HREF="manual_16.html#SEC56">point_size</A>.<BR><BR>
719</P><P>
720
721Format: point_size_min &#60;size&#62;
722Default: point_size_min 0
723</P><P>
724
725<A NAME="point_size_max"></A>
726<A NAME="SEC60"></A>
727<H3> point_size_max </H3>
728<!--docid::SEC60::-->
729<P>
730
731Sets the maximum point size after attenuation (<A HREF="manual_16.html#SEC58">point_size_attenuation</A>). For details on the size metrics, See section <A HREF="manual_16.html#SEC56">point_size</A>. A value of 0 means the maximum is set to the same as the max size reported by the current card. <BR><BR>
732</P><P>
733
734Format: point_size_max &#60;size&#62;
735Default: point_size_max 0
736</P><P>
737
738<A NAME="Texture Units"></A>
739<HR SIZE=1>
740<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
741<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_15.html#SEC31"> &lt; </A>]</TD>
742<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
743<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_17.html#SEC61"> &gt; </A>]</TD>
744<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
745<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
746<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
747<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
748</TR></TABLE>
749<BR> 
750<FONT SIZE="-1">
751This document was generated
752by <I>Steve Streeting</I> on <I>, 12 2006</I>
753using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
754"><I>texi2html</I></A>
755
756</BODY>
757</HTML>
Note: See TracBrowser for help on using the repository browser.