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

Revision 692, 15.2 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'): Copying Materials</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Copying Materials">
17<META NAME="keywords" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Copying Materials">
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="SEC106"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_19.html#SEC99"> &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_21.html#SEC111"> &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.6 Copying Materials </H3>
38<!--docid::SEC106::-->
39<P>
40
41When creating new materials scripts that are only slight variations of another material script, the script writer resorts to copy and pasting materials within scripts.  For simple materials, the copy/paste method is acceptable.  Complex materials that use multiple passes along with vertex and pixel shaders become very tedious to edit when many variations are needed.  To reduce the tediousness of making new materials that are just slight variations of previously defined materials, new materials can copy from previously defined materials and modify specific techniques, passes, texture units or add new ones.<BR><BR>
42</P><P>
43
44To make a new material that is based on one previously defined, add a <EM>colon</EM> <STRONG>:</STRONG> after the new material name followed by the name of the material that is to be copied.<BR><BR>
45</P><P>
46
47Format: material &#60;NewUniqueChildName&#62; : &#60;ReferanceParentMaterial&#62;<BR><BR>
48</P><P>
49
50The only caveat is that a parent material must have been defined/parsed prior to the child material script being parsed.  The easiest way to achieve this is to place parents at the begining of the material script file.  After material scripts are loaded into Ogre, materials no longer maintain their copy inheritance structure.  If a parent material is modified through code at runtime, the changes have no effect on child materials that were copied from it in the script.<BR><BR>
51</P><P>
52
53Material copying within the script alleviates some drudgery from copy/paste but having the ability to identify specific techniques, passes, and texture units to modify makes material copying easier.  Techniques, passes, texture units can be identified directly in the child material without having to layout previous techniques, passes, texture units by associating a name with them,  Techniques and passes can take a name and texture units can be numbered within the material script.<BR><BR>
54</P><P>
55
56<STRONG>NOTE:  Using names is optional so older scripts will still work just fine and you can inherit from them as well.</STRONG><BR><BR>
57</P><P>
58
59Names become very usefull in materials that copy from other materials.  In order to overide values they must be in the correct technique, pass, texture unit etc.  The script could be layed out using the sequence of techniques, passes, texture units in the child material but if only one paramter needs to change in say the 5th pass then the first four passes prior to the fith would have to be placed in the script:<BR><BR>
60</P><P>
61
62Here is an example:
63<TABLE><tr><td>&nbsp;</td><td class=example><pre>material test2 : test1
64{
65  technique
66  {
67    pass
68    {
69    }
70
71    pass
72    {
73    }
74
75    pass
76    {
77    }
78
79    pass
80    {
81    }
82
83    pass
84    {
85          ambient 0.5 0.7 0.3 1.0
86    }
87  }
88}
89</pre></td></tr></table></P><P>
90
91This method is tedious for materials that only have slight variations to their parent.
92An easier way is to name the pass directly without listing the previous passes:<BR>
93</P><P>
94
95<TABLE><tr><td>&nbsp;</td><td class=example><pre>material test2 : test1
96{
97  technique 0
98  {
99    pass 4
100    {
101          ambient 0.5 0.7 0.3 1.0
102    }
103  }
104}
105</pre></td></tr></table></P><P>
106
107The parent pass name must be known and the pass must be in the correct technique in order for this to work correctly.  Specifying the technique name and the pass name is the best method.  If the parent technique/pass are not named then use their index values for their name as done in the example.<BR><BR>
108</P><P>
109
110<A NAME="SEC107"></A>
111<H3> Adding new Techniques, Passes, to copied materials: </H3>
112<!--docid::SEC107::-->
113<P>
114
115If a new technique or pass needs to be added to a copied material then use a unique name for the technique or pass that does not exist in the parent material.  Using an index for the name that is one greater than the last index in the parent will do the same thing.  The new technique/pass will be added to the end of the techniques/passes copied from the parent material.<BR><BR>
116</P><P>
117
118Note:  if passes or techniques aren't given a name, they will take on a default name based on their index.  For example the first pass has index 0 so its name will be 0.
119</P><P>
120
121<A NAME="SEC108"></A>
122<H3> Dealing with Program References and Shader Parameters: </H3>
123<!--docid::SEC108::-->
124<P>
125
126For a child material that only needs to change some shader parameters within a pass, do the following:<BR><BR>
127</P><P>
128
129<TABLE><tr><td>&nbsp;</td><td class=example><pre>material furtest2 : furtest1
130{
131  technique ati8500
132  {
133    pass fur3
134    {
135      fragment_program_ref
136      {
137        param_named furlength float 0.5
138      }
139    }
140  }
141}
142</pre></td></tr></table></P><P>
143
144There is no requirement to give the name of the fragment program reference since the parent material has already done this and the same applies to a vertex program reference, but dropping the program reference name only applies if one is defined in the pass copied from the parent material.  If the parent didn't have a program reference then an exception is generated since the material parser has no clue as to what the script intended.<BR><BR>
145</P><P>
146
147Program references can be added to copied passes that had no program references.  The whole program reference will have to be defined with in the pass.<BR><BR>
148</P><P>
149
150If a different program ref is to be used in the copied pass then just put in the name of the different vertex/fragment program reference.  This is usefull when you want to inherit from a parent material but want to use a different shader program for one of the passes.<BR><BR>
151</P><P>
152
153<A NAME="SEC109"></A>
154<H3> Identifying Texture Units to overide values </H3>
155<!--docid::SEC109::-->
156<P>
157
158A specific texture unit state (TUS) can be given a unique name within a pass of a material so that it can be identified later in cloned materials that need to override specified texture unit states in the pass without declaring previous texture units.  Using a unique name for a Texture unit in a pass of a cloned material adds a new texture unit at the end of the texture unit list for the pass.<BR><BR>
159</P><P>
160
161<TABLE><tr><td>&nbsp;</td><td class=example><pre>material BumpMap2 : BumpMap1
162{
163  technique ati8500
164  {
165    pass 0
166    {
167      texture_unit NormalMap
168      {
169        texture BumpyMetalNM.png
170      }
171    }
172  }
173}
174</pre></td></tr></table></P><P>
175
176<A NAME="SEC110"></A>
177<H3> Texture Aliases </H3>
178<!--docid::SEC110::-->
179<P>
180
181Texture aliases are usefull for when only the textures used in texture units need to be specified for a cloned material.  In the source material ie the original material to be cloned, each texture unit can be given a texture alias name.  The cloned material in the script can then specify what textures should be used for each texture alias.<BR><BR>
182</P><P>
183
184Using texture aliases within texture units:<BR>
185Format:<BR>
186texture_alias &#60;name&#62;<BR><BR>
187</P><P>
188
189Default: &#60;name&#62; will default to texture_unit &#60;name&#62; if set
190<TABLE><tr><td>&nbsp;</td><td class=example><pre>texture_unit DiffuseTex
191{
192  texture diffuse.jpg
193}
194</pre></td></tr></table>texture_alias defaults to DiffuseTex.<BR>
195</P><P>
196
197Example: The base material to be cloned:<BR>
198<TABLE><tr><td>&nbsp;</td><td class=example><pre>material TSNormalSpecMapping
199{
200  technique GLSL
201  {
202    pass
203    {
204      ambient 0.1 0.1 0.1
205      diffuse 0.7 0.7 0.7
206      specular 0.7 0.7 0.7 128
207               
208      vertex_program_ref GLSLDemo/OffsetMappingVS
209      {
210        param_named_auto lightPosition light_position_object_space 0
211        param_named_auto eyePosition camera_position_object_space
212        param_named textureScale float 1.0
213      }
214
215      fragment_program_ref GLSLDemo/TSNormalSpecMappingFS
216      {
217        param_named normalMap int 0
218        param_named diffuseMap int 1
219        param_named fxMap int 2
220      }
221
222      // Normal map
223      texture_unit NormalMap
224      {
225        texture defaultNM.png
226        tex_coord_set 0
227        filtering trilinear
228      }
229
230      // Base diffuse texture map
231      texture_unit NormalMap
232      {
233        texture defaultDiff.png
234        filtering trilinear
235        tex_coord_set 1
236      }
237
238      // spec map for shinnines
239      texture_unit SpecMap
240      {
241        texture defaultSpec.png
242        filtering trilinear
243        tex_coord_set 2
244      }
245
246    }
247
248  }
249
250  technique HLSL_DX9
251  {
252    pass
253    {
254                       
255      vertex_program_ref FxMap_HLSL_VS
256      {
257        param_named_auto worldViewProj_matrix worldviewproj_matrix
258        param_named_auto lightPosition light_position_object_space 0
259        param_named_auto eyePosition camera_position_object_space
260      }
261
262      fragment_program_ref FxMap_HLSL_PS
263      {
264        param_named ambientColor float4 0.2 0.2 0.2 0.2
265      }
266
267      // Normal map
268      texture_unit
269      {
270        texture_alias NormalMap
271        texture defaultNM.png
272        tex_coord_set 0
273        filtering trilinear
274      }
275
276      // Base diffuse texture map
277      texture_unit
278      {
279        texture_alias DiffuseMap
280        texture defaultDiff.png
281        filtering trilinear
282        tex_coord_set 1
283      }
284
285      // spec map for shinnines
286      texture_unit
287      {
288        texture_alias SpecMap
289        texture defaultSpec.png
290        filtering trilinear
291        tex_coord_set 2
292      }
293
294    }
295
296  }
297}
298</pre></td></tr></table></P><P>
299
300Note that the GLSL and HLSL techniques use the same textures.  For each texture usage type a texture alias is given that describes what the texture is used for.  So the first texture unit in the GLSL technique has the same alias as the TUS in the HLSL technique since its the same texture used. Same goes for the second and third texture units.<BR>
301For demonstration purposes, the GLSL technique makes use of texture_unit naming and therefore the texture_alias name does not have to be set since it defaults to the texture unit name.  So why not use the default all the time since its less typing?  For most situations you can.  Its when you clone a material that and then want to change the alias that you must use the texture_alias command in the script.  You cannot change the name of a texture_unit in a cloned material so texture_alias provides a facility to assign an alias name.<BR><BR>
302</P><P>
303
304Now we want to clone the material but only want to change the textures used.  We could copy and paste the whole material but if we decide to change the base material later then we also have to update the copied material in the script.  With set_texture_alias, copying a material is very easy now.  set_texture_alias is specified at the top of the material definition.  All techniques using the specified texture alias will be effected by set_texture_alias.<BR><BR>
305</P><P>
306
307Format:<BR>
308set_texture_alias &#60;alias name&#62; = &#60;texture name&#62;<BR>
309<TABLE><tr><td>&nbsp;</td><td class=example><pre>material fxTest : TSNormalSpecMapping
310{
311  set_texture_alias NormalMap fxTestNMap.png
312  set_texture_alias DiffuseMap fxTestDiff.png
313  set_texture_alias SpecMap fxTestMap.png
314}
315</pre></td></tr></table></P><P>
316
317The textures in both techniques in the child material will automatically get replaced with the new ones we want to use.<BR><BR>
318</P><P>
319
320  The same process can be done in code as long you set up the texture alias names so then there is no need to traverse technique/pass/TUS to change a texture.  You just call myMaterialPtr-&#62;applyTextureAliases(myAliasTextureNameList) which will update all textures in all texture units that match the alias names in the map container reference you passed as a parameter.<BR><BR>
321</P><P>
322
323 You don't have to supply all the textures in the copied material.<BR>
324<TABLE><tr><td>&nbsp;</td><td class=example><pre>material fxTest2 : fxTest
325{
326  set_texture_alias DiffuseMap fxTest2Diff.png
327  set_texture_alias SpecMap fxTest2Map.png
328}
329</pre></td></tr></table></P><P>
330
331Material fxTest2 only changes the diffuse and spec maps of material fxTest and uses the same normal map.<BR><BR>
332</P><P>
333
334Another example:
335<TABLE><tr><td>&nbsp;</td><td class=example><pre>material fxTest3 : TSNormalSpecMapping
336{
337  set_texture_alias DiffuseMap fxTest2Diff.png
338}
339</pre></td></tr></table></P><P>
340
341fxTest3 will end up with the default textures for the normal map and spec map setup in TSNormalSpecMapping material but will have a different diffuse map.  So your base material can define the default textures to use and then the child materials can override specific textures.<BR><BR>
342</P><P>
343
344<A NAME="Compositor Scripts"></A>
345<HR SIZE=1>
346<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
347<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_19.html#SEC99"> &lt; </A>]</TD>
348<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
349<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_21.html#SEC111"> &gt; </A>]</TD>
350<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>
351<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
352<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
353<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
354</TR></TABLE>
355<BR> 
356<FONT SIZE="-1">
357This document was generated
358by <I>Steve Streeting</I> on <I>, 12 2006</I>
359using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
360"><I>texi2html</I></A>
361
362</BODY>
363</HTML>
Note: See TracBrowser for help on using the repository browser.