source: OGRE/trunk/ogrenew/Docs/manual/manual_20.html @ 657

Revision 657, 20.6 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources
RevLine 
[657]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.0.7: Using Vertex and Fragment Programs in a Pass</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.0.7: Using Vertex and Fragment Programs in a Pass">
17<META NAME="keywords" CONTENT="OGRE Manual v1.0.7: Using Vertex and Fragment Programs in a Pass">
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="SEC86"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_19.html#SEC76"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_15.html#SEC24"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_21.html#SEC93"> &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.5 Using Vertex and Fragment Programs in a Pass </H3>
38<!--docid::SEC86::-->
39<P>
40
41Within a pass section of a material script, you can reference a vertex and / or a fragment program which is been defined in a .program script (See section <A HREF="manual_19.html#SEC76">3.1.4 Declaring Vertex and Fragment Programs</A>). The programs are defined separately from the usage of them in the pass, since the programs are very likely to be reused between many separate materials, probably across many different .material scripts, so this approach lets you define the program only once and use it many times.<BR><BR>
42</P><P>
43
44As well as naming the program in question, you can also provide parameters to it. Here's a simple example:
45<TABLE><tr><td>&nbsp;</td><td class=example><pre>vertex_program_ref myVertexProgram
46{
47        param_indexed_auto 0 worldviewproj_matrix
48        param_indexed      4 float4  10.0 0 0 0
49}
50</pre></td></tr></table>In this example, we bind a vertex program called 'myVertexProgram' (which will be defined elsewhere) to the pass, and give it 2 parameters, one is an 'auto' parameter, meaning we do not have to supply a value as such, just a recognised code (in this case it's the world/view/projection matrix which is kept up to date automatically by Ogre). The second parameter is a manually specified parameter, a 4-element float. The indexes are described later.<BR><BR>
51</P><P>
52
53The syntax of the link to a vertex program and a fragment program are identical, the only difference is that 'fragment_program_ref' is used instead of 'vertex_program_ref'.
54<A NAME="Program Parameter Specification"></A>
55<A NAME="SEC87"></A>
56<H3> Parameter specification </H3>
57<!--docid::SEC87::-->
58Parameters can be specified using one of 4 commands as shown below. The same syntax is used whether you are defining a parameter just for this particular use of the program, or when specifying the <A HREF="manual_19.html#SEC77">Default Program Parameters</A>. Parameters set in the specific use of the program override the defaults.
59<UL>
60<LI><A HREF="manual_20.html#SEC88">param_indexed</A>
61<LI><A HREF="manual_20.html#SEC89">param_indexed_auto</A>
62<LI><A HREF="manual_20.html#SEC90">param_named</A>
63<LI><A HREF="manual_20.html#SEC91">param_named_auto</A>
64</UL>
65<P>
66
67<A NAME="param_indexed"></A>
68<A NAME="SEC88"></A>
69<H3> param_indexed </H3>
70<!--docid::SEC88::-->
71This command sets the value of an indexed parameter. <BR><BR>
72<P>
73
74format: param_indexed &#60;index&#62; &#60;type&#62; &#60;value&#62;<BR><BR>
75example: param_indexed 0 float4 10.0 0 0 0<BR><BR>
76</P><P>
77
78The 'index' is simply a number representing the position in the parameter list which the value should be written, and you should derive this from your program definition. The index is relative to the way constants are stored on the card, which is in 4-element blocks. For example if you defined a float4 parameter at index 0, the next index would be 1. If you defined a matrix4x4 at index 0, the next usable index would be 4, since a 4x4 matrix takes up 4 indexes.<BR><BR>
79</P><P>
80
81The value of 'type' can be float4, matrix4x4, float&#60;n&#62;, int4, int&#60;n&#62;. Note that 'int' parameters are only available on some more advanced program syntaxes, check the D3D or GL vertex / fragment program documentation for full details. Typically the most useful ones will be float4 and matrix4x4. Note that if you use a type which is not a multiple of 4, then the remaining values up to the multiple of 4 will be filled with zeroes for you (since GPUs always use banks of 4 floats per constant even if only one is used).<BR><BR>
82</P><P>
83
84'value' is simply a space or tab-delimited list of values which can be converted into the type you have specified.
85</P><P>
86
87<A NAME="param_indexed_auto"></A>
88<A NAME="SEC89"></A>
89<H3> param_indexed_auto </H3>
90<!--docid::SEC89::-->
91<P>
92
93This command tells Ogre to automatically update a given parameter with a derived value. This frees you from writing code to update program parameters every frame when they are always changing.<BR><BR>
94</P><P>
95
96format: param_indexed_auto &#60;index&#62; &#60;value_code&#62; &#60;extra_params&#62;<BR><BR>
97example: param_indexed_auto 0 worldviewproj_matrix<BR><BR>
98</P><P>
99
100'index' has the same meaning as <A HREF="manual_20.html#SEC88">param_indexed</A>; note this time you do not have to specify the size of the parameter because the engine knows this already. In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4.<BR><BR>
101</P><P>
102
103'value_code' is one of a list of recognised values:<BR>
104<DL COMPACT>
105<DT>world_matrix
106<DD>The current world matrix.
107<DT>world_matrix_array_3x4
108<DD>An array of world matrices, each represented as only a 3x4 matrix (3 rows of 4columns) usually for doing hardware skinning. You should make enough entries available in your vertex program for the number of bones in use, ie an array of numBones*3 float4's.
109<DT>view_matrix
110<DD>The current view matrix.
111<DT>projection_matrix
112<DD>The current projection matrix.
113<DT>worldview_matrix
114<DD>The current world and view matrices concatenated.
115<DT>viewproj_matrix
116<DD>The current view and projection matrices concatenated.
117<DT>worldviewproj_matrix
118<DD>The current world, view and projection matrices concatenated.
119<DT>inverse_world_matrix
120<DD>The inverse of the current world matrix.
121<DT>inverse_view_matrix
122<DD>The inverse of the current view matrix.
123<DT>inverse_worldview_matrix
124<DD>The inverse of the current concatenated world and view matrices.
125<DT>inverse_transpose_world_matrix
126<DD>The inverse transpose of the current world matrix.
127<DT>inverse_transpose_worldview_matrix
128<DD>The inverse transpose of the current concatenated world and view matrices.
129<DT>inverse_viewproj_matrix
130<DD>The inverse of the view &#38; projection matrices
131<DT>inverse_transpose_viewproj_matrix
132<DD>The inverse transpose of the view &#38; projection matrices
133<DT>transpose_viewproj_matrix
134<DD>The transpose of the view &#38; projection matrices
135<DT>transpose_view_matrix
136<DD>The transpose of the view matrix
137<DT>inverse_transpose_view_matrix
138<DD>The inverse transpose of the view matrix
139<DT>transpose_projection_matrix
140<DD>The transpose of the projection matrix
141<DT>inverse_projection_matrix
142<DD>The inverse of the projection matrix
143<DT>inverse_transpose_projection_matrix
144<DD>The inverse transpose of the projection matrix
145<DT>transpose_worldviewproj_matrix
146<DD>The transpose of the world, view and projection matrices
147<DT>inverse_worldviewproj_matrix
148<DD>The inverse of the world, view and projection matrices
149<DT>inverse_transpose_worldviewproj_matrix
150<DD>The inverse transpose of the world, view and projection matrices
151<DT>transpose_worldview_matrix
152<DD>The transpose of the world and view matrices
153<DT>inverse_transpose_worldview_matrix
154<DD>The inverse transpose of the world and view matrices
155<DT>transpose_world_matrix
156<DD>The transpose of the world matrix
157<DT>inverse_transpose_world_matrix
158<DD>The inverse transpose of the world matrix
159<DT>light_diffuse_colour
160<DD>The diffuse colour of a given light; this requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light - note that directional lights are always first in the list and always present). NB if there are no lights this close, then the parameter will be set to black.
161<DT>light_specular_colour
162<DD>The specular colour of a given light; this requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to black.
163<DT>light_attenuation
164<DD>A float4 containing the 4 light attenuation variables for a given light. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. The order of the parameters is range, constant attenuation, linear attenuation, quadric attenuation.
165<DT>light_position
166<DD>The position of a given light in world space. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both.
167<DT>light_direction
168<DD>The direction of a given light in world space. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED - this property only works on directional lights, and we recommend that you use light_position instead since that returns a generic 4D vector.
169<DT>light_position_object_space
170<DD>The position of a given light in object space (ie when the object is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes.  Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both.
171<DT>light_direction_object_space
172<DD>The direction of a given light in object space (ie when the object is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes.  DEPRECATED - this property only works on directional lights, and we recommend that you use light_position_object_space instead since that returns a generic 4D vector.
173<DT>ambient_light_colour
174<DD>The colour of the ambient light currently set in the scene.
175<DT>camera_position
176<DD>The current cameras position in world space.
177<DT>camera_position_object_space
178<DD>The current cameras position in object space (ie when the object is at (0,0,0)).
179<DT>time
180<DD>The current time, factored by the optional parameter (or 1.0f if not supplied).
181<DT>time_0_x
182<DD>Single float time value, which repeats itself based on "cycle time" given as an 'extra_params' field
183<DT>costime_0_x
184<DD>Cosine of time_0_x
185<DT>sintime_0_x
186<DD>Sine of time_0_x
187<DT>tantime_0_x
188<DD>Tangent of time_0_x
189<DT>time_0_x_packed
190<DD>4-element vector of time0_x, sintime0_x, costime0_x, tantime0_x
191<DT>time_0_1
192<DD>As time0_x but scaled to [0..1]
193<DT>costime_0_1
194<DD>As costime0_x but scaled to [0..1]
195<DT>sintime_0_1
196<DD>As sintime0_x but scaled to [0..1]
197<DT>tantime_0_1
198<DD>As tantime0_x but scaled to [0..1]
199<DT>time_0_1_packed
200<DD>As time0_x_packed but all values scaled to [0..1]
201<DT>time_0_2pi
202<DD>As time0_x but scaled to [0..2*Pi]
203<DT>costime_0_2pi
204<DD>As costime0_x but scaled to [0..2*Pi]
205<DT>sintime_0_2pi
206<DD>As sintime0_x but scaled to [0..2*Pi]
207<DT>tantime_0_2pi
208<DD>As tantime0_x but scaled to [0..2*Pi]
209<DT>time_0_2pi_packed
210<DD>As time0_x_packed but scaled to [0..2*Pi]
211<DT>fps
212<DD>The current frames per second
213<DT>viewport_width
214<DD>The current viewport width in pixels
215<DT>viewport_height
216<DD>The current viewport height in pixels
217<DT>inverse_viewport_width
218<DD>1.0/the current viewport width in pixels
219<DT>inverse_viewport_height
220<DD>1.0/the current viewport height in pixels
221<DT>view_direction
222<DD>View direction vector in object space
223<DT>view_side_vector
224<DD>View local X axis
225<DT>view_up_vector
226<DD>View local Y axis
227<DT>fov
228<DD>Vertical field of view, in radians
229<DT>near_clip_distance
230<DD>Near clip distance, in world units
231<DT>far_clip_distance
232<DD>Far clip distance, in world units (may be 0 for infinite view projection)
233<DT>texture_viewproj_matrix
234<DD>Only applicable to vertex programs which have been specified as the 'shadow receiver' vertex program alternative; this provides details of the view/projection matrix for the current shadow projector.
235<DT>custom
236<DD>This allows you to map a custom parameter on an individual Renderable (see Renderable::setCustomParameter) to a parameter on a GPU program. It requires that you complete the 'extra_params' field with the index that was used in the Renderable::setCustomParameter call, and this will ensure that whenever this Renderable is used, it will have it's custom parameter mapped in. It's very important that this parameter has been defined on all Renderables that are assigned the material that contains this automatic mapping, otherwise the process will fail.
237</DL>
238<P>
239
240<A NAME="param_named"></A>
241<A NAME="SEC90"></A>
242<H3> param_named </H3>
243<!--docid::SEC90::-->
244This is the same as param_indexed, but uses a named parameter instead of an index. This can only be used with high-level programs which include parameter names; if you're using an assembler program then you have no choice but to use indexes. Note that you can use indexed parameters for high-level programs too, but it is less portable since if you reorder your parameters in the high-level program the indexes will change.<BR><BR>
245format: param_named &#60;name&#62; &#60;type&#62; &#60;value&#62;<BR><BR>
246example: param_named shininess float4 10.0 0 0 0<BR><BR>
247The type is required because the program is not compiled and loaded when the material script is parsed, so at this stage we have no idea what types the parameters are. Programs are only loaded and compiled when they are used, to save memory.
248<P>
249
250<A NAME="param_named_auto"></A>
251<A NAME="SEC91"></A>
252<H3> param_named_auto </H3>
253<!--docid::SEC91::-->
254<P>
255
256This is the named equivalent of param_indexed_auto, for use with high-level programs.<BR><BR>
257Format: param_named_auto &#60;name&#62; &#60;value_code&#62; &#60;extra_params&#62;<BR><BR>
258Example: param_named_auto worldViewProj WORLDVIEWPROJ_MATRIX<BR><BR>
259</P><P>
260
261The allowed value codes and the meaning of extra_params are detailed in <A HREF="manual_20.html#SEC89">param_indexed_auto</A>.
262</P><P>
263
264<A NAME="Shadows and Vertex Programs"></A>
265<A NAME="SEC92"></A>
266<H3> Shadows and Vertex Programs </H3>
267<!--docid::SEC92::-->
268When using shadows (See section <A HREF="manual_57.html#SEC212">7. Shadows</A>), the use of vertex programs can add some additional complexities, because Ogre can only automatically deal with everything when using the fixed-function pipeline. If you use vertex programs, and you are also using shadows, you may need to make some adjustments. <BR><BR>
269<P>
270
271If you use <STRONG>stencil shadows</STRONG>, then any vertex programs which do vertex deformation can be a problem, because stencil shadows are calculated on the CPU, which does not have access to the modified vertices. If the vertex program is doing standard skeletal animation, this is ok (see section above) because Ogre knows how to replicate the effect in software, but any other vertex deformation cannot be replicated, and you will either have to accept that the shadow will not reflect this deformation, or you should turn off shadows for that object. <BR><BR>
272</P><P>
273
274If you use <STRONG>texture shadows</STRONG>, then vertex deformation is acceptable; however, when rendering the object into the shadow texture (the shadow caster pass), the shadow has to be rendered in a solid colour (linked to the ambient colour). You must therefore provide an alternative vertex program, so Ogre provides you with a way of specifying one to use when rendering the caster. Basically you link an alternative vertex program, using exactly the same syntax as the original vertex program link:
275</P><P>
276
277<TABLE><tr><td>&nbsp;</td><td class=example><pre>shadow_caster_vertex_program_ref myShadowCasterVertexProgram
278{
279        param_indexed_auto 0 worldviewproj_matrix
280        param_indexed_auto 4 ambient_light_colour
281}
282</pre></td></tr></table></P><P>
283
284When rendering a shadow caster, Ogre will automatically use the alternate program. You can bind the same or different parameters to the program - the most important thing is that you bind <STRONG>ambiend_light_colour</STRONG>, since this determines the colour of the shadow in modulative texture shadows. If you don't supply an alternate program, Ogre will fall back on a fixed-function material which will not reflect any vertex deformation you do in your vertex program. <BR><BR>
285</P><P>
286
287In addition, when rendering the shadow receivers with shadow textures, Ogre needs to project the shadow texture. It does this automatically in fixed function mode, but if the receivers use vertex programs, they need to have a shadow receiver program which does the usual vertex deformation, but also generates projective texture coordinates. The additional program linked into the pass like this:
288</P><P>
289
290<TABLE><tr><td>&nbsp;</td><td class=example><pre>shadow_receiver_vertex_program_ref myShadowReceiverVertexProgram
291{
292        param_indexed_auto 0 worldviewproj_matrix
293        param_indexed_auto 4 texture_viewproj_matrix
294}
295</pre></td></tr></table></P><P>
296
297For the purposes of writing this alternate program, there is an automatic parameter binding of 'texture_viewproj_matrix' which provides the program with texture projection parameters. The vertex program should do it's normal vertex processing, and generate texture coordinates using this matrix and place them in texture coord sets 0 and 1, since some shadow techniques use 2 texture units. The colour of the vertices output by this vertex program must always be white, so as not to affect the final colour of the rendered shadow.
298</P><P>
299
300<A NAME="Particle Scripts"></A>
301<HR SIZE=1>
302<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
303<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_19.html#SEC76"> &lt; </A>]</TD>
304<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_15.html#SEC24"> Up </A>]</TD>
305<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_21.html#SEC93"> &gt; </A>]</TD>
306<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>
307<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
308<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
309<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
310</TR></TABLE>
311<BR> 
312<FONT SIZE="-1">
313This document was generated
314by <I>Steve Streeting</I> on <I>, 12 2006</I>
315using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
316"><I>texi2html</I></A>
317
318</BODY>
319</HTML>
Note: See TracBrowser for help on using the repository browser.