source: OGRE/trunk/ogrenew/Docs/src/MaterialScriptCopy.inc @ 692

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

adding ogre 1.2 and dependencies

RevLine 
[692]1@node Copying Materials
2@subsection Copying Materials
3
4When 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.@*@*
5
6To make a new material that is based on one previously defined, add a @emph{colon} @strong{:} after the new material name followed by the name of the material that is to be copied.@*@*
7
8Format: material <NewUniqueChildName> : <ReferanceParentMaterial>@*@*
9
10The 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.@*@*
11
12Material 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.@*@*
13
14@strong{NOTE:  Using names is optional so older scripts will still work just fine and you can inherit from them as well.}@*@*
15
16Names 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:@*@*
17
18Here is an example:
19@example
20material test2 : test1
21{
22  technique
23  {
24    pass
25    {
26    }
27
28    pass
29    {
30    }
31
32    pass
33    {
34    }
35
36    pass
37    {
38    }
39
40    pass
41    {
42          ambient 0.5 0.7 0.3 1.0
43    }
44  }
45}
46@end example
47
48This method is tedious for materials that only have slight variations to their parent.
49An easier way is to name the pass directly without listing the previous passes:@*
50
51@example
52material test2 : test1
53{
54  technique 0
55  {
56    pass 4
57    {
58          ambient 0.5 0.7 0.3 1.0
59    }
60  }
61}
62@end example
63
64The 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.@*@*
65
66@subheading Adding new Techniques, Passes, to copied materials:
67
68If 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.@*@*
69
70Note:  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.
71
72@subheading Dealing with Program References and Shader Parameters:
73
74For a child material that only needs to change some shader parameters within a pass, do the following:@*@*
75
76@example
77material furtest2 : furtest1
78{
79  technique ati8500
80  {
81    pass fur3
82    {
83      fragment_program_ref
84      {
85        param_named furlength float 0.5
86      }
87    }
88  }
89}
90@end example
91
92There 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.@*@*
93
94Program 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.@*@*
95
96If 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.@*@*
97
98@subheading Identifying Texture Units to overide values
99
100A 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.@*@*
101
102@example
103material BumpMap2 : BumpMap1
104{
105  technique ati8500
106  {
107    pass 0
108    {
109      texture_unit NormalMap
110      {
111        texture BumpyMetalNM.png
112      }
113    }
114  }
115}
116@end example
117
118@subheading Texture Aliases
119
120Texture 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.@*@*
121
122Using texture aliases within texture units:@*
123Format:@*
124texture_alias <name>@*@*
125
126Default: <name> will default to texture_unit <name> if set
127@example
128texture_unit DiffuseTex
129{
130  texture diffuse.jpg
131}
132@end example
133texture_alias defaults to DiffuseTex.@*
134
135Example: The base material to be cloned:@*
136@example
137material TSNormalSpecMapping
138{
139  technique GLSL
140  {
141    pass
142    {
143      ambient 0.1 0.1 0.1
144      diffuse 0.7 0.7 0.7
145      specular 0.7 0.7 0.7 128
146               
147      vertex_program_ref GLSLDemo/OffsetMappingVS
148      {
149        param_named_auto lightPosition light_position_object_space 0
150        param_named_auto eyePosition camera_position_object_space
151        param_named textureScale float 1.0
152      }
153
154      fragment_program_ref GLSLDemo/TSNormalSpecMappingFS
155      {
156        param_named normalMap int 0
157        param_named diffuseMap int 1
158        param_named fxMap int 2
159      }
160
161      // Normal map
162      texture_unit NormalMap
163      {
164        texture defaultNM.png
165        tex_coord_set 0
166        filtering trilinear
167      }
168
169      // Base diffuse texture map
170      texture_unit NormalMap
171      {
172        texture defaultDiff.png
173        filtering trilinear
174        tex_coord_set 1
175      }
176
177      // spec map for shinnines
178      texture_unit SpecMap
179      {
180        texture defaultSpec.png
181        filtering trilinear
182        tex_coord_set 2
183      }
184
185    }
186
187  }
188
189  technique HLSL_DX9
190  {
191    pass
192    {
193                       
194      vertex_program_ref FxMap_HLSL_VS
195      {
196        param_named_auto worldViewProj_matrix worldviewproj_matrix
197        param_named_auto lightPosition light_position_object_space 0
198        param_named_auto eyePosition camera_position_object_space
199      }
200
201      fragment_program_ref FxMap_HLSL_PS
202      {
203        param_named ambientColor float4 0.2 0.2 0.2 0.2
204      }
205
206      // Normal map
207      texture_unit
208      {
209        texture_alias NormalMap
210        texture defaultNM.png
211        tex_coord_set 0
212        filtering trilinear
213      }
214
215      // Base diffuse texture map
216      texture_unit
217      {
218        texture_alias DiffuseMap
219        texture defaultDiff.png
220        filtering trilinear
221        tex_coord_set 1
222      }
223
224      // spec map for shinnines
225      texture_unit
226      {
227        texture_alias SpecMap
228        texture defaultSpec.png
229        filtering trilinear
230        tex_coord_set 2
231      }
232
233    }
234
235  }
236}
237@end example
238
239Note 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.@*
240For 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.@*@*
241
242Now 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.@*@*
243
244Format:@*
245set_texture_alias <alias name> = <texture name>@*
246@example
247material fxTest : TSNormalSpecMapping
248{
249  set_texture_alias NormalMap fxTestNMap.png
250  set_texture_alias DiffuseMap fxTestDiff.png
251  set_texture_alias SpecMap fxTestMap.png
252}
253@end example
254
255The textures in both techniques in the child material will automatically get replaced with the new ones we want to use.@*@*
256
257  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->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.@*@*
258
259 You don't have to supply all the textures in the copied material.@*
260@example
261material fxTest2 : fxTest
262{
263  set_texture_alias DiffuseMap fxTest2Diff.png
264  set_texture_alias SpecMap fxTest2Map.png
265}
266@end example
267
268Material fxTest2 only changes the diffuse and spec maps of material fxTest and uses the same normal map.@*@*
269
270Another example:
271@example
272material fxTest3 : TSNormalSpecMapping
273{
274  set_texture_alias DiffuseMap fxTest2Diff.png
275}
276@end example
277
278fxTest3 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.@*@*
Note: See TracBrowser for help on using the repository browser.