1# Material Scripts {#Material-Scripts} 2 3Material scripts offer you the ability to define complex materials in a script which can be reused easily. Whilst you could set up all materials for a scene in code using the methods of the Material and TextureLayer classes, in practice it's a bit unwieldy. Instead you can store material definitions in text files which can then be loaded whenever required. 4 5@tableofcontents 6 7It’s important to realise that materials are not loaded completely by the parsing process: only the definition is loaded, no textures or other resources are loaded. This is because it is common to have a large library of materials, but only use a relatively small subset of them in any one scene. To load every material completely in every script would therefore cause unnecessary memory overhead. You can access a ’deferred load’ Material in the normal way (Ogre::MaterialManager::getSingleton().getByName()), but you must call the ’load’ method before trying to use it. Ogre does this for you when using the normal material assignment methods of entities etc. 8 9To start with, we only consider fixed-function materials which don’t use vertex, geometry or fragment programs, these are covered later: 10 11```cpp 12// This is a comment 13material walls/funkywall1 14{ 15 // first, preferred technique 16 technique 17 { 18 // first pass 19 pass 20 { 21 ambient 0.5 0.5 0.5 22 diffuse 1.0 1.0 1.0 23 24 // Texture unit 0 25 texture_unit 26 { 27 texture wibbly.jpg 28 scroll_anim 0.1 0.0 29 wave_xform scale sine 0.0 0.7 0.0 1.0 30 } 31 // Texture unit 1 (this is a multitexture pass) 32 texture_unit 33 { 34 texture wobbly.png 35 rotate_anim 0.25 36 colour_op add 37 } 38 39 // Additional RT Shader system options 40 rtshader_system 41 { 42 // Do lighting calculations per-pixel 43 lighting_stage per_pixel 44 } 45 } 46 } 47 48 // Second technique, can be used as a fallback or LOD level 49 technique 50 { 51 // .. and so on 52 } 53} 54``` 55 56A material can be made up of many @ref Techniques - a technique is one way of achieving the effect you are looking for. You can supply more than one technique in order to provide fallback approaches where a card does not have the ability to render the preferred technique, or where you wish to define lower level of detail versions of the material in order to conserve rendering power when objects are more distant. 57 58Each technique can be made up of many @ref Passes, that is a complete render of the object can be performed multiple times with different settings in order to produce composite effects. Ogre may also split the passes you have defined into many passes at runtime, if you define a pass which uses too many texture units for the card you are currently running on (note that it can only do this if you are not using a fragment program). Each pass has a number of top-level attributes such as ’ambient’ to set the amount & colour of the ambient light reflected by the material. Some of these options do not apply if you are using vertex programs, See @ref Passes for more details. 59 60Within each pass, there can be zero or many @ref Texture-Units in use. These define the texture to be used, and optionally some blending operations (which use multitexturing) and texture effects. 61 62You can also reference vertex and fragment programs (or vertex and pixel shaders, if you want to use that terminology) in a pass with a given set of parameters. Programs themselves are declared in separate .program scripts (See @ref Declaring-Vertex_002fGeometry_002fFragment-Programs) and are used as described in @ref Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass. 63 64<a name="Top_002dlevel-material-attributes"></a> 65 66# Material {#Material} 67 68The outermost section of a material definition does not have a lot of attributes of its own (most of the configurable parameters are within the child sections. However, it does have some, and here they are: 69 70<a name="lod_005fstrategy"></a> 71<a name="lod_005fstrategy-1"></a> 72 73## lod\_strategy 74 75Sets the name of the LOD strategy to use. Defaults to ’Distance’ which means LOD changes based on distance from the camera. Also supported is ’PixelCount’ which changes LOD based on an estimate of the screen-space pixels affected. 76@par 77Format: lod\_strategy <name><br> Default: lod\_strategy Distance 78 79<a name="lod_005fvalues"></a> 80<a name="lod_005fvalues-1"></a> 81 82## lod\_values 83 84This attribute defines the values used to control the LOD transition for this material. By setting this attribute, you indicate that you want this material to alter the Technique that it uses based on some metric, such as the distance from the camera, or the approximate screen space coverage. The exact meaning of these values is determined by the option you select for [lod\_strategy](#lod_005fstrategy) - it is a list of distances for the ’Distance’ strategy, and a list of pixel counts for the ’PixelCount’ strategy, for example. You must give it a list of values, in order from highest LOD value to lowest LOD value, each one indicating the point at which the material will switch to the next LOD. Implicitly, all materials activate LOD index 0 for values less than the first entry, so you do not have to specify ’0’ at the start of the list. You must ensure that there is at least one Technique with a [lod\_index](#lod_005findex) value for each value in the list (so if you specify 3 values, you must have techniques for LOD indexes 0, 1, 2 and 3). Note you must always have at least one Technique at lod\_index 0. 85 86@par 87Format: lod\_values <value0> <value1> <value2> ...<br> Default: none 88@par 89Example: <br> lod\_strategy Distance lod\_values 300.0 600.5 1200 90 91The above example would cause the material to use the best Technique at lod\_index 0 up to a distance of 300 world units, the best from lod\_index 1 from 300 up to 600, lod\_index 2 from 600 to 1200, and lod\_index 3 from 1200 upwards. 92 93<a name="lod_005fdistances"></a> 94## lod\_distances 95 96@deprecated This option is deprecated in favour of [lod\_values](#lod_005fvalues) now. 97 98<a name="receive_005fshadows"></a><a name="receive_005fshadows-1"></a> 99 100## receive\_shadows 101 102This attribute controls whether objects using this material can have shadows cast upon them. 103 104@par 105Format: receive\_shadows <on|off><br> Default: on 106 107Whether or not an object receives a shadow is the combination of a number of factors, See @ref Shadows for full details; however this allows you to make a material opt-out of receiving shadows if required. Note that transparent materials never receive shadows so this option only has an effect on solid materials. 108 109<a name="transparency_005fcasts_005fshadows"></a><a name="transparency_005fcasts_005fshadows-1"></a> 110 111## transparency\_casts\_shadows 112 113This attribute controls whether transparent materials can cast certain kinds of shadow. 114 115@par 116Format: transparency\_casts\_shadows <on|off><br> 117Default: off 118 119Whether or not an object casts a shadow is the combination of a number of factors, See @ref Shadows for full details; however this allows you to make a transparent material cast shadows, when it would otherwise not. For example, when using texture shadows, transparent materials are normally not rendered into the shadow texture because they should not block light. This flag overrides that. 120 121<a name="set_005ftexture_005falias"></a><a name="set_005ftexture_005falias-1"></a> 122 123## set\_texture\_alias 124 125This attribute associates a texture alias with a texture name. 126 127@par 128Format: set\_texture\_alias <alias name> <texture name> 129 130This attribute can be used to set the textures used in texture unit states that were inherited from another material.(See @ref Texture-Aliases) 131 132 133 134# Techniques {#Techniques} 135 136A "technique" section in your material script encapsulates a single method of rendering an object. The simplest of material definitions only contains a single technique, however since PC hardware varies quite greatly in it’s capabilities, you can only do this if you are sure that every card for which you intend to target your application will support the capabilities which your technique requires. In addition, it can be useful to define simpler ways to render a material if you wish to use material LOD, such that more distant objects use a simpler, less performance-hungry technique. 137 138When a material is used for the first time, it is ’compiled’. That involves scanning the techniques which have been defined, and marking which of them are supportable using the current rendering API and graphics card. If no techniques are supportable, your material will render as blank white. The compilation examines a number of things, such as: 139 140- The number of texture\_unit entries in each pass<br> Note that if the number of texture\_unit entries exceeds the number of texture units in the current graphics card, the technique may still be supportable so long as a fragment program is not being used. In this case, Ogre will split the pass which has too many entries into multiple passes for the less capable card, and the multitexture blend will be turned into a multipass blend (See [colour\_op\_multipass\_fallback](#colour_005fop_005fmultipass_005ffallback)). 141- Whether vertex, geometry or fragment programs are used, and if so which syntax they use (e.g. vs\_1\_1, ps\_2\_x, arbfp1 etc.) 142- Other effects like cube mapping and dot3 blending 143- Whether the vendor or device name of the current graphics card matches some user-specified rules 144 145<br> 146 147In a material script, techniques must be listed in order of preference, i.e. the earlier techniques are preferred over the later techniques. This normally means you will list your most advanced, most demanding techniques first in the script, and list fallbacks afterwards. 148 149To help clearly identify what each technique is used for, the technique can be named but its optional. Techniques not named within the script will take on a name that is the technique index number. For example: the first technique in a material is index 0, its name would be "0" if it was not given a name in the script. The technique name must be unique within the material or else the final technique is the resulting merge of all techniques with the same name in the material. A warning message is posted in the Ogre.log if this occurs. Named techniques can help when inheriting a material and modifying an existing technique: (See @ref Script-Inheritance) 150 151@par 152Format: technique name 153 154Techniques have only a small number of attributes of their own: 155 156- [scheme](#scheme) 157- [lod\_index](#lod_005findex) (and also see [lod\_distances](#lod_005fdistances) in the parent material) 158- [shadow\_caster\_material](#shadow_005fcaster_005fmaterial) 159- [shadow\_receiver\_material](#shadow_005freceiver_005fmaterial) 160- [gpu\_vendor\_rule](#gpu_005fvendor_005frule) 161- [gpu\_device\_rule](#gpu_005fdevice_005frule) 162 163<a name="scheme"></a><a name="scheme-1"></a> 164 165## scheme 166 167Sets the ’scheme’ this Technique belongs to. Material schemes are used to control top-level switching from one set of techniques to another. For example, you might use this to define ’high’, ’medium’ and ’low’ complexity levels on materials to allow a user to pick a performance / quality ratio. Another possibility is that you have a fully HDR-enabled pipeline for top machines, rendering all objects using unclamped shaders, and a simpler pipeline for others; this can be implemented using schemes. The active scheme is typically controlled at a viewport level, and the active one defaults to ’Default’. 168 169@par 170Format: scheme <name><br> Example: scheme hdr<br> Default: scheme Default 171 172<a name="lod_005findex"></a><a name="lod_005findex-1"></a> 173 174## lod\_index 175 176Sets the level-of-detail (LOD) index this Technique belongs to. 177 178@par 179Format: lod\_index <number><br> NB Valid values are 0 (highest level of detail) to 65535, although this is unlikely. You should not leave gaps in the LOD indexes between Techniques. 180 181@par 182Example: lod\_index 1 183 184All techniques must belong to a LOD index, by default they all belong to index 0, i.e. the highest LOD. Increasing indexes denote lower levels of detail. You can (and often will) assign more than one technique to the same LOD index, what this means is that OGRE will pick the best technique of the ones listed at the same LOD index. For readability, it is advised that you list your techniques in order of LOD, then in order of preference, although the latter is the only prerequisite (OGRE determines which one is ’best’ by which one is listed first). You must always have at least one Technique at lod\_index 0. The distance at which a LOD level is applied is determined by the lod\_distances attribute of the containing material, See [lod\_distances](#lod_005fdistances) for details. 185 186@par 187Default: lod\_index 0 188 189Techniques also contain one or more @ref Passes (and there must be at least one). 190 191<a name="shadow_005fcaster_005fmaterial"></a><a name="shadow_005fcaster_005fmaterial-1"></a> 192 193## shadow\_caster\_material 194 195When using @ref Texture_002dbased-Shadows you can specify an alternate material to use when rendering the object using this material into the shadow texture. This is like a more advanced version of using shadow\_caster\_vertex\_program, however note that for the moment you are expected to render the shadow in one pass, i.e. only the first pass is respected. 196 197<a name="shadow_005freceiver_005fmaterial"></a><a name="shadow_005freceiver_005fmaterial-1"></a> 198 199## shadow\_receiver\_material 200 201When using @ref Texture_002dbased-Shadows you can specify an alternate material to use when performing the receiver shadow pass. Note that this explicit ’receiver’ pass is only done when you’re **not** using @ref Integrated-Texture-Shadows - i.e. the shadow rendering is done separately (either as a modulative pass, or a masked light pass). This is like a more advanced version of using shadow\_receiver\_vertex\_program and shadow\_receiver\_fragment\_program, however note that for the moment you are expected to render the shadow in one pass, i.e. only the first pass is respected. 202 203<a name="gpu_005fvendor_005frule"></a><a name="gpu_005fdevice_005frule"></a><a name="gpu_005fvendor_005frule-and-gpu_005fdevice_005frule"></a> 204 205## gpu\_vendor\_rule and gpu\_device\_rule 206 207Although Ogre does a good job of detecting the capabilities of graphics cards and setting the supportability of techniques from that, occasionally card-specific behaviour exists which is not necessarily detectable and you may want to ensure that your materials go down a particular path to either use or avoid that behaviour. This is what these rules are for - you can specify matching rules so that a technique will be considered supportable only on cards from a particular vendor, or which match a device name pattern, or will be considered supported only if they **don’t** fulfil such matches. The format of the rules are as follows: 208 209@par 210gpu\_vendor\_rule <include|exclude> <vendor\_name><br> gpu\_device\_rule <include|exclude> <device\_pattern> \[case\_sensitive\] 211 212An ’include’ rule means that the technique will only be supported if one of the include rules is matched (if no include rules are provided, anything will pass). An ’exclude’ rules means that the technique is considered unsupported if any of the exclude rules are matched. You can provide as many rules as you like, although <vendor\_name> and <device\_pattern> must obviously be unique. The valid list of <vendor\_name> values is currently ’nvidia’, ’ati’, ’intel’, ’s3’, ’matrox’ and ’3dlabs’. <device\_pattern> can be any string, and you can use wildcards (’\*’) if you need to match variants. Here’s an example: 213 214@par 215gpu\_vendor\_rule include nvidia<br> gpu\_vendor\_rule include intel<br> gpu\_device\_rule exclude \*950\* 216 217These rules, if all included in one technique, will mean that the technique will only be considered supported on graphics cards made by NVIDIA and Intel, and so long as the device name doesn’t have ’950’ in it. 218 219Note that these rules can only mark a technique ’unsupported’ when it would otherwise be considered ’supported’ judging by the hardware capabilities. Even if a technique passes these rules, it is still subject to the usual hardware support tests. 220 221# Passes {#Passes} 222 223A 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. 224 225To 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 unique 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 inheriting a material and modifying an existing pass: (See @ref Script-Inheritance) 226 227Passes have a set of global attributes (described below) and optionally 228- zero or more nested texture\_unit entries (See @ref Texture-Units) 229- references to shader programs (See @ref Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass) 230- additional instructions for the RTSS (See @ref rtss_custom_mat) 231 232 233 234Here are the attributes you can use in a ’pass’ section of a .material script: 235 236- [ambient](#ambient) 237- [diffuse](#diffuse) 238- [specular](#specular) 239- [emissive](#emissive) 240- [scene\_blend](#scene_005fblend) 241- [separate\_scene\_blend](#separate_005fscene_005fblend) 242- [scene\_blend\_op](#scene_005fblend_005fop) 243- [separate\_scene\_blend\_op](#separate_005fscene_005fblend_005fop) 244- [depth\_check](#depth_005fcheck) 245- [depth\_write](#depth_005fwrite) 246- [depth\_func](#depth_005ffunc) 247- [depth\_bias](#depth_005fbias) 248- [iteration\_depth\_bias](#iteration_005fdepth_005fbias) 249- [alpha\_rejection](#alpha_005frejection) 250- [alpha\_to\_coverage](#alpha_005fto_005fcoverage) 251- [light\_scissor](#light_005fscissor) 252- [light\_clip\_planes](#light_005fclip_005fplanes) 253- [illumination\_stage](#illumination_005fstage) 254- [transparent\_sorting](#transparent_005fsorting) 255- [normalise\_normals](#normalise_005fnormals) 256- [cull\_hardware](#cull_005fhardware) 257- [cull\_software](#cull_005fsoftware) 258- [lighting](#lighting) 259- [shading](#shading) 260- [polygon\_mode](#polygon_005fmode) 261- [polygon\_mode\_overrideable](#polygon_005fmode_005foverrideable) 262- [fog\_override](#fog_005foverride) 263- [colour\_write](#colour_005fwrite) 264- [max\_lights](#max_005flights) 265- [start\_light](#start_005flight) 266- [iteration](#iteration) 267- [point\_size](#point_005fsize) 268- [point\_sprites](#point_005fsprites) 269- [point\_size\_attenuation](#point_005fsize_005fattenuation) 270- [point\_size\_min](#point_005fsize_005fmin) 271- [point\_size\_max](#point_005fsize_005fmax) 272- [line_width](#line_width) 273 274<a name="Attribute-Descriptions"></a> 275 276# Attribute Descriptions 277 278<a name="ambient"></a><a name="ambient-1"></a> 279 280## ambient 281 282Sets the ambient colour reflectance properties of this pass. 283 284@par 285Format: ambient (<red> <green> <blue> \[<alpha>\]| vertexcolour)<br> NB valid colour values are between 0.0 and 1.0. 286 287@copydetails Ogre::Pass::setAmbient 288@note When using shader programs, you have to explicitely forward this property in the @ref Program-Parameter-Specification 289 290@par 291Example: ambient 0.0 0.8 0.0 292@par 293Default: ambient 1.0 1.0 1.0 1.0 294 295<a name="diffuse"></a><a name="diffuse-1"></a> 296 297## diffuse 298 299Sets the diffuse colour reflectance properties of this pass. 300@par 301Format: diffuse (<red> <green> <blue> \[<alpha>\]| vertexcolour)<br> NB valid colour values are between 0.0 and 1.0. 302 303@copydetails Ogre::Pass::setDiffuse 304@note When using shader programs, you have to explicitely forward this property in the @ref Program-Parameter-Specification 305 306@par 307Example: diffuse 1.0 0.5 0.5 308@par 309Default: diffuse 1.0 1.0 1.0 1.0 310 311<a name="specular"></a><a name="specular-1"></a> 312 313## specular 314 315Sets the specular colour reflectance properties of this pass. 316@par 317Format: specular (<red> <green> <blue> \[<alpha>\]| vertexcolour) <shininess><br> NB valid colour values are between 0.0 and 1.0. Shininess can be any value greater than 0. 318 319 320This property determines how much specular light (highlights from instances of the Light class in the scene) is reflected. The 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. 321It is also possible to make the specular reflectance track the vertex colour as defined in 322the mesh instead of the colour values. 323 324@copydetails Ogre::Pass::setShininess 325@note When using shader programs, you have to explicitely forward this property in the @ref Program-Parameter-Specification 326 327@par 328Example: specular 1.0 1.0 1.0 12.5 329 330@par 331Default: specular 0.0 0.0 0.0 0.0 0.0 332 333<a name="emissive"></a><a name="emissive-1"></a> 334 335## emissive 336 337Sets the amount of self-illumination an object has. 338 339@par 340Format: emissive (<red> <green> <blue> \[<alpha>\]| vertexcolour)<br> NB valid colour values are between 0.0 and 1.0. 341 342Unlike 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). 343@copydetails Ogre::Pass::setSelfIllumination 344@note When using shader programs, you have to explicitely forward this property in the @ref Program-Parameter-Specification 345 346@par 347Example: emissive 1.0 0.0 0.0 348@par 349Default: emissive 0.0 0.0 0.0 0.0 350 351<a name="scene_005fblend"></a><a name="scene_005fblend-1"></a> 352 353## scene\_blend 354 355Sets the kind of blending this pass has with the existing contents of the scene. 356 357Whereas 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. 358 359There are 2 formats, one using predefined blend types, the other allowing a roll-your-own approach using source and destination factors. 360@par 361Format1: scene\_blend <blend\_type> 362@par 363Example: scene\_blend add 364 365This is the simpler form, where the most commonly used blending modes are enumerated using a single parameter. 366 367@param blend_type 368<dl compact="compact"> 369<dt>add</dt> 370<dd>@copybrief Ogre::SBT_ADD 371 372Equivalent to ’scene_blend one one’.</dd> 373<dt>modulate</dt> 374<dd>@copybrief Ogre::SBT_MODULATE 375 376Equivalent to ’scene_blend dest_colour zero’.</dd> 377<dt>colour_blend</dt> 378<dd>@copybrief Ogre::SBT_TRANSPARENT_COLOUR 379 380Equivalent to ’scene_blend src_colour one_minus_src_colour’</dd> 381<dt>alpha_blend</dt> 382<dd>@copybrief Ogre::SBT_TRANSPARENT_ALPHA 383 384Equivalent to ’scene_blend src_alpha one_minus_src_alpha’</dd> 385</dl> 386 387@par 388Format2: scene\_blend <sourceFactor> <destFactor> 389 390@copydetails Ogre::Pass::setSceneBlending(const SceneBlendFactor, const SceneBlendFactor) 391 392Valid values for both parameters are one of Ogre::SceneBlendFactor without the `SBF_` prefix. E.g. `SBF_DEST_COLOUR` becomes `dest_colour`. 393 394@par 395Example: scene\_blend one one\_minus\_dest\_alpha 396 397@par 398Default: scene\_blend one zero (opaque) 399 400Also see [separate\_scene\_blend](#separate_005fscene_005fblend). 401 402<a name="separate_005fscene_005fblend"></a><a name="separate_005fscene_005fblend-1"></a> 403 404## separate\_scene\_blend 405 406This option operates in exactly the same way as [scene\_blend](#scene_005fblend), except that it allows you to specify the operations to perform between the rendered pixel and the frame buffer separately for colour and alpha components. By nature this option is only useful when rendering to targets which have an alpha channel which you’ll use for later processing, such as a render texture. 407@par 408Format1: separate\_scene\_blend <simple\_colour\_blend> <simple\_alpha\_blend> 409@par 410Example: separate\_scene\_blend add modulate 411 412This example would add colour components but multiply alpha components. The blend modes available are as in [scene\_blend](#scene_005fblend). The more advanced form is also available: 413@par 414Format2: separate\_scene\_blend <colour\_src\_factor> <colour\_dest\_factor> <alpha\_src\_factor> <alpha\_dest\_factor> 415@par 416Example: separate\_scene\_blend one one\_minus\_dest\_alpha one one 417 418Again the options available in the second format are the same as those in the second format of [scene\_blend](#scene_005fblend). 419 420<a name="scene_005fblend_005fop"></a><a name="scene_005fblend_005fop-1"></a> 421 422## scene\_blend\_op 423 424This directive changes the operation which is applied between the two components of the scene blending equation 425 426@par 427Format: scene\_blend\_op <op> 428 429@copydoc Ogre::Pass::setSceneBlendingOperation 430You may change this to ’add’, ’subtract’, ’reverse_subtract’, ’min’ or ’max’. 431 432<a name="separate_005fscene_005fblend_005fop"></a><a name="separate_005fscene_005fblend_005fop-1"></a> 433 434## separate\_scene\_blend\_op 435 436This directive is as scene\_blend\_op, except that you can set the operation for colour and alpha separately. 437@par 438Format: separate\_scene\_blend\_op <colourOp> <alphaOp> Default: separate\_scene\_blend\_op add add 439 440<a name="depth_005fcheck"></a><a name="depth_005fcheck-1"></a> 441 442## depth\_check 443 444Sets whether or not this pass renders with depth-buffer checking on or not. 445@par 446Format: depth\_check <on|off> 447 448@copydetails Ogre::Pass::setDepthCheckEnabled 449 450Default: depth\_check on 451 452<a name="depth_005fwrite"></a><a name="depth_005fwrite-1"></a> 453 454## depth\_write 455 456Sets whether or not this pass renders with depth-buffer writing on or not. 457 458@par 459Format: depth\_write <on|off> 460 461@copydetails Ogre::Pass::setDepthWriteEnabled 462 463@par 464Default: depth\_write on<br> 465 466<a name="depth_005ffunc"></a><a name="depth_005ffunc-1"></a> 467 468## depth\_func 469 470Sets the function used to compare depth values when depth checking is on. 471@par 472Format: depth\_func <func> 473 474@copydetails Ogre::Pass::setDepthFunction 475 476@param func one of Ogre::CompareFunction without the `CMPF_` prefix. E.g. `CMPF_LESS_EQUAL` becomes `less_equal`. 477 478@par 479Default: depth\_func less\_equal 480 481<a name="depth_005fbias"></a><a name="depth_005fbias-1"></a> 482 483## depth\_bias 484 485Sets the bias applied to the depth value of this pass. 486@par 487Format: depth\_bias <constantBias> \[<slopeScaleBias>\] 488 489@copydetails Ogre::Pass::setDepthBias 490 491Also see [iteration\_depth\_bias](#iteration_005fdepth_005fbias) 492 493<a name="iteration_005fdepth_005fbias"></a><a name="iteration_005fdepth_005fbias-1"></a> 494 495## iteration\_depth\_bias 496 497Sets an additional bias derived from the number of times a given pass has been iterated. Operates just like [depth\_bias](#depth_005fbias) except that it applies an additional bias factor to the base depth\_bias value, multiplying the provided value by the number of times this pass has been iterated before, through one of the [iteration](#iteration) variants. So the first time the pass will get the depth\_bias value, the second time it will get depth\_bias + iteration\_depth\_bias, the third time it will get depth\_bias + iteration\_depth\_bias \* 2, and so on. The default is zero. 498@par 499Format: iteration\_depth\_bias <bias\_per\_iteration> 500 501 <a name="alpha_005frejection"></a><a name="alpha_005frejection-1"></a> 502 503## alpha\_rejection 504 505Sets the way the pass will have use alpha to totally reject pixels from the pipeline. 506@par 507Format: alpha\_rejection <function> <value> 508@par 509Example: alpha\_rejection greater\_equal 128 510 511The 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. 512@par 513Default: alpha\_rejection always\_pass 514 515<a name="alpha_005fto_005fcoverage"></a><a name="alpha_005fto_005fcoverage-1"></a> 516 517## alpha\_to\_coverage 518 519Sets whether this pass will use ’alpha to coverage’, 520 521@par 522Format: alpha\_to\_coverage <on|off> 523 524@copydetails Ogre::Pass::setAlphaToCoverageEnabled 525 526@par 527Default: alpha\_to\_coverage off <a name="light_005fscissor"></a> 528 529<a name="light_005fscissor-1"></a> 530 531## light_scissor 532 533Sets whether when rendering this pass, rendering will be limited to a screen-space scissor rectangle representing the coverage of the light(s) being used in this pass. 534@par 535Format: light\_scissor <on|off> 536@par 537Default: light\_scissor off 538 539@copydetails Ogre::Pass::setLightScissoringEnabled 540 541<a name="light_005fclip_005fplanes"></a><a name="light_005fclip_005fplanes-1"></a> 542 543## light\_clip\_planes 544 545Sets whether when rendering this pass, triangle setup will be limited to clipping volume covered by the light. 546@par 547Format: light\_clip\_planes <on|off> 548@par 549Default: light\_clip\_planes off 550 551@copydetails Ogre::Pass::setLightClipPlanesEnabled 552 553@see @ref Integrated-Texture-Shadows 554 555## illumination_stage {#illumination_005fstage} 556 557@copydetails Ogre::Pass::setIlluminationStage 558 559@par 560Format: illumination\_stage <ambient|per\_light|decal> Default: none (autodetect) 561 562<a name="normalise_005fnormals"></a><a name="normalise_005fnormals-1"></a> 563 564## normalise\_normals 565 566Sets whether or not this pass renders with all vertex normals being automatically re-normalised.<br> 567@par 568Format: normalise\_normals <on|off> 569 570@copydetails Ogre::Pass::setNormaliseNormals 571 572@par 573Default: normalise\_normals off<br> 574 575<a name="transparent_005fsorting"></a><a name="transparent_005fsorting-1"></a> 576 577## transparent\_sorting 578 579Sets if transparent textures should be sorted by depth or not. 580@par 581Format: transparent\_sorting <on|off|force> 582 583By default all transparent materials are sorted such that renderables furthest away from the camera are rendered first. This is usually the desired behaviour but in certain cases this depth sorting may be unnecessary and undesirable. If for example it is necessary to ensure the rendering order does not change from one frame to the next. In this case you could set the value to ’off’ to prevent sorting. 584 585You can also use the keyword ’force’ to force transparent sorting on, regardless of other circumstances. Usually sorting is only used when the pass is also transparent, and has a depth write or read which indicates it cannot reliably render without sorting. By using ’force’, you tell OGRE to sort this pass no matter what other circumstances are present. 586@par 587Default: transparent\_sorting on 588 589<a name="cull_005fhardware"></a><a name="cull_005fhardware-1"></a> 590 591## cull\_hardware 592 593Sets the hardware culling mode for this pass. 594@par 595Format: cull\_hardware <clockwise|anticlockwise|none> 596 597@copydetails Ogre::Pass::setCullingMode 598 599@par 600Default: cull\_hardware clockwise<br> NB 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). 601 602<a name="cull_005fsoftware"></a><a name="cull_005fsoftware-1"></a> 603 604## cull\_software 605 606Sets the software culling mode for this pass. 607@par 608Format: cull\_software <back|front|none> 609 610@copydetails Ogre::Pass::setManualCullingMode 611 612@par 613Default: cull\_software back 614 615<a name="lighting"></a><a name="lighting-1"></a> 616 617## lighting 618 619Sets whether or not dynamic lighting is turned on for this pass or not. 620 621@par 622Format: lighting <on|off> 623 624@copydetails Ogre::Pass::setLightingEnabled 625@par 626Default: lighting on 627 628<a name="shading"></a><a name="shading-1"></a> 629 630## shading 631 632Sets the kind of shading which should be used for representing dynamic lighting for this pass. 633@par 634Format: shading <mode> 635 636@copydetails Ogre::Pass::setShadingMode 637 638@param mode one of Ogre::ShadeOptions without the `SO_` prefix. E.g. `SO_FLAT` becomes `flat`. 639 640@par 641Default: shading gouraud 642 643<a name="polygon_005fmode"></a><a name="polygon_005fmode-1"></a> 644 645## polygon\_mode 646 647@copydetails Ogre::Pass::setPolygonMode 648 649@par 650Format: polygon_mode <solid|wireframe|points> 651 652@param mode one of Ogre::PolygonMode without the `PM_` prefix. E.g. `PM_SOLID` becomes `solid`. 653 654@par 655Default: polygon\_mode solid 656 657<a name="polygon_005fmode_005foverrideable"></a><a name="polygon_005fmode_005foverrideable-1"></a> 658 659## polygon\_mode\_overrideable 660 661Sets whether or not the [polygon\_mode](#polygon_005fmode) set on this pass can be downgraded by the camera 662 663@par 664Format: polygon\_mode\_overrideable <override> 665 666@copydetails Ogre::Pass::setPolygonModeOverrideable 667 668<a name="fog_005foverride"></a><a name="fog_005foverride-1"></a> 669 670## fog\_override 671 672Tells 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. Note that this only affects fixed-function fog - the original scene fog parameters are still sent to shaders which use the fog\_params parameter binding (this allows you to turn off fixed function fog and calculate it in the shader instead; if you want to disable shader fog you can do that through shader parameters anyway). 673@par 674Format: fog\_override <override?> \[<type> <colour> <density> <start> <end>\] 675@par 676Default: fog\_override false 677 678If 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. 679 680@param type **none** = No fog, equivalent of just using ’fog\_override true’<br> **linear** = Linear fog from the <start> and <end> distances<br> **exp** = Fog increases exponentially from the camera (fog = 1/e^(distance \* density)), use <density> param to control it<br> **exp2** = Fog increases at the square of FOG\_EXP, i.e. even quicker (fog = 1/e^(distance \* density)^2), use <density> param to control it 681 682@param colour Sequence of 3 floating point values from 0 to 1 indicating the red, green and blue intensities 683 684@param density 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 685 686@param start The start distance from the camera of linear fog. Must still be present in other modes, even though it is not used. 687 688@param end The end distance from the camera of linear fog. Must still be present in other modes, even though it is not used. 689 690@par 691Example: fog\_override true exp 1 1 1 0.002 100 10000 692 693<a name="colour_005fwrite"></a><a name="colour_005fwrite-1"></a> 694 695## colour\_write 696 697Sets whether this pass renders with colour writing on or not. Alternatively, it can also be used to enable/disable colour writing specific channels. 698In the second format, the parameters are in the red, green, blue, alpha order. 699 700@par 701Format 1: colour\_write <on|off> 702@par 703Format 2: colour\_write <on|off> <on|off> <on|off> <on|off> 704 705@copydetails Ogre::Pass::setColourWriteEnabled 706 707@par 708Default: colour\_write on<br> 709 710<a name="colour_005fmask"></a><a name="colour_005fmask-1"></a> 711 712## start\_light 713 714Sets the first light which will be considered for use with this pass. 715@par 716Format: start\_light <number> 717 718@copydetails Ogre::Pass::setStartLight 719 720@par 721Default: start\_light 0<br> 722 723<a name="max_005flights"></a><a name="max_005flights-1"></a> 724 725## max\_lights 726 727Sets the maximum number of lights which will be considered for use with this pass. 728@par 729Format: max\_lights <number> 730 731The 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 [Using Vertex/Geometry/Fragment Programs in a Pass](@ref Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass)) this limit is dependent on the program you are running, or, if you use ’iteration once\_per\_light’ or a variant (See @ref iteration), it effectively only bounded by the number of passes you are willing to use. If you are not using pass iteration, the light limit applies once for this pass. If you are using pass iteration, the light limit applies across all iterations of this pass - for example if you have 12 lights in range with an ’iteration once\_per\_light’ setup but your max\_lights is set to 4 for that pass, the pass will only iterate 4 times. 732@par 733Default: max\_lights 8<br> 734 735## iteration {#iteration} 736 737Sets whether or not this pass is iterated, i.e. issued more than once. 738@par 739Format 1: iteration <once | once\_per\_light> \[lightType\] Format 2: iteration <number> \[<per\_light> \[lightType\]\] 740@par 741Format 3: iteration <number> \[<per\_n\_lights> <num\_lights> \[lightType\]\] Examples: 742 743<dl compact="compact"> 744<dt>iteration once</dt> <dd> 745 746The pass is only executed once which is the default behaviour. 747 748</dd> <dt>iteration once\_per\_light point</dt> <dd> 749 750The pass is executed once for each point light. 751 752</dd> <dt>iteration 5</dt> <dd> 753 754The render state for the pass will be setup and then the draw call will execute 5 times. 755 756</dd> <dt>iteration 5 per\_light point</dt> <dd> 757 758The 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. 759 760</dd> <dt>iteration 1 per\_n\_lights 2 point</dt> <dd> 761 762The render state for the pass will be setup and the draw call executed once for every 2 lights. 763 764</dd> </dl> <br> 765 766By 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. 767 768Using 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 i.e. shaders that do fur, motion blur, special filtering. 769 770If 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 silhouette to appear. 771 772The lightType parameter to the attribute only applies if you use once\_per\_light, per\_light, or per\_n\_lights 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 easier if you can assume the kind of lights you’ll be dealing with. However at least point and directional lights can be dealt with in one way. Default: iteration once 773 774<a name="fur_005fexample"></a> 775 776Example: Simple Fur shader material script that uses a second pass with 10 iterations to grow the fur: 777 778```cpp 779// GLSL simple Fur 780vertex_program GLSLDemo/FurVS glsl 781{ 782 source fur.vert 783 default_params 784 { 785 param_named_auto lightPosition light_position_object_space 0 786 param_named_auto eyePosition camera_position_object_space 787 param_named_auto passNumber pass_number 788 param_named_auto multiPassNumber pass_iteration_number 789 param_named furLength float 0.15 790 } 791} 792 793fragment_program GLSLDemo/FurFS glsl 794{ 795 source fur.frag 796 default_params 797 { 798 param_named Ka float 0.2 799 param_named Kd float 0.5 800 param_named Ks float 0.0 801 param_named furTU int 0 802 } 803} 804 805material Fur 806{ 807 technique GLSL 808 { 809 pass base_coat 810 { 811 ambient 0.7 0.7 0.7 812 diffuse 0.5 0.8 0.5 813 specular 1.0 1.0 1.0 1.5 814 815 vertex_program_ref GLSLDemo/FurVS 816 { 817 } 818 819 fragment_program_ref GLSLDemo/FurFS 820 { 821 } 822 823 texture_unit 824 { 825 texture Fur.tga 826 tex_coord_set 0 827 filtering trilinear 828 } 829 } 830 831 pass grow_fur 832 { 833 ambient 0.7 0.7 0.7 834 diffuse 0.8 1.0 0.8 835 specular 1.0 1.0 1.0 64 836 depth_write off 837 838 scene_blend src_alpha one 839 iteration 10 840 841 vertex_program_ref GLSLDemo/FurVS 842 { 843 } 844 845 fragment_program_ref GLSLDemo/FurFS 846 { 847 } 848 849 texture_unit 850 { 851 texture Fur.tga 852 tex_coord_set 0 853 filtering trilinear 854 } 855 } 856 } 857} 858``` 859 860@note use gpu program auto parameters [pass\_number](#pass_005fnumber) and [pass\_iteration\_number](#pass_005fiteration_005fnumber) to tell the vertex, geometry or fragment program the pass number and iteration number. 861 862<a name="point_005fsize"></a><a name="point_005fsize-1"></a> 863 864## point\_size 865 866@copydetails Ogre::Pass::setPointSize 867 868@par 869Format: point\_size <size> Default: point\_size 1.0 870 871<a name="point_005fsprites"></a><a name="point_005fsprites-1"></a> 872 873## point\_sprites 874 875@copydetails Ogre::Pass::setPointSpritesEnabled 876 877@par 878Format: point\_sprites <on|off> Default: point\_sprites off 879 880<a name="point_005fsize_005fattenuation"></a><a name="point_005fsize_005fattenuation-1"></a> 881 882## point\_size\_attenuation 883 884Defines whether point size is attenuated with view space distance, and in what fashion. 885 886@par 887Format: point\_size\_attenuation <enabled> \[constant linear quadratic\] Default: point\_size\_attenuation off 888 889@copydetails Ogre::Pass::setPointAttenuation 890 891 892<a name="point_005fsize_005fmin"></a><a name="point_005fsize_005fmin-1"></a> 893 894## point\_size\_min 895 896Sets the minimum point size after attenuation ([point\_size\_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point\_size](#point_005fsize). 897@par 898Format: point\_size\_min <size> Default: point\_size\_min 0 899 900<a name="point_005fsize_005fmax"></a><a name="point_005fsize_005fmax-1"></a> 901 902## point\_size\_max 903 904Sets the maximum point size after attenuation ([point\_size\_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point\_size](#point_005fsize). A value of 0 means the maximum is set to the same as the max size reported by the current card. 905@par 906Format: point\_size\_max <size> Default: point\_size\_max 0 907 908<a name="line_width"></a> 909## line_width 910@copydetails Ogre::Pass::setLineWidth 911 912@par 913Format: line_width <width> 914@par 915Default: line_width 1 916 917# Texture Units {#Texture-Units} 918 919Here are the attributes you can use in a ’texture\_unit’ section of a .material script: 920 921<a name="Available-Texture-Layer-Attributes"></a> 922 923## Available Texture Layer Attributes 924 925- [texture\_alias](#texture_005falias) 926- [texture](#texture) 927- [anim\_texture](#anim_005ftexture) 928- [cubic\_texture](#cubic_005ftexture) 929- [tex\_coord\_set](#tex_005fcoord_005fset) 930- [colour\_op](#colour_005fop) 931- [colour\_op\_ex](#colour_005fop_005fex) 932- [colour\_op\_multipass\_fallback](#colour_005fop_005fmultipass_005ffallback) 933- [alpha\_op\_ex](#alpha_005fop_005fex) 934- [env\_map](#env_005fmap) 935- [scroll](#scroll) 936- [scroll\_anim](#scroll_005fanim) 937- [rotate](#rotate) 938- [rotate\_anim](#rotate_005fanim) 939- [scale](#scale) 940- [wave\_xform](#wave_005fxform) 941- [transform](#transform) 942- [binding\_type](#binding_005ftype) 943- [content\_type](#content_005ftype) 944- [sampler_ref](#sampler_ref) 945 946Additionally you can use all attributes of @ref Samplers directly to implicitly create a Ogre::Sampler contained in this TextureUnit. 947 948You can also use a nested ’texture\_source’ section in order to use a special add-in as a source of texture data, See @ref External-Texture-Sources for details. 949 950<a name="Attribute-Descriptions-1"></a> 951 952## Attribute Descriptions 953 954<a name="texture_005falias"></a><a name="texture_005falias-1"></a> 955 956## texture\_alias 957 958Sets the alias name for this texture unit. 959@par 960Format: texture\_alias <name> 961@par 962Example: texture\_alias NormalMap 963 964Setting the texture alias name is useful if this material is to be inherited by other other materials and only the textures will be changed in the new material.(See @ref Texture-Aliases) Default: If a texture\_unit has a name then the texture\_alias defaults to the texture\_unit name. 965 966<a name="texture"></a><a name="texture-1"></a> 967 968## texture 969 970Sets the name of the static texture image this layer will use. 971@par 972Format: texture <texturename> \[<type>\] \[unlimited | numMipMaps\] \[alpha\] \[<PixelFormat>\] \[gamma\] 973@par 974Example: texture funkywall.jpg 975 976This setting is mutually exclusive with the anim\_texture attribute. Note that the texture file cannot include spaces. Those of you Windows users who like spaces in filenames, please get over it and use underscores instead. 977 978@param type 979specify a the type of texture to create - the default is ’2d’, but you can override this; here’s the full list: 980<dl compact="compact"> 981<dt>1d</dt> <dd> 982 983A 1-dimensional texture; that is, a texture which is only 1 pixel high. These kinds of textures can be useful when you need to encode a function in a texture and use it as a simple lookup, perhaps in a fragment program. It is important that you use this setting when you use a fragment program which uses 1-dimensional texture coordinates, since GL requires you to use a texture type that matches (D3D will let you get away with it, but you ought to plan for cross-compatibility). Your texture widths should still be a power of 2 for best compatibility and performance. 984 985</dd> <dt>2d</dt> <dd> 986 987The default type which is assumed if you omit it, your texture has a width and a height, both of which should preferably be powers of 2, and if you can, make them square because this will look best on the most hardware. These can be addressed with 2D texture coordinates. 988 989</dd> <dt>3d</dt> <dd> 990 991A 3 dimensional texture i.e. volume texture. Your texture has a width, a height, both of which should be powers of 2, and has depth. These can be addressed with 3d texture coordinates i.e. through a pixel shader. 992 993</dd> <dt>cubic</dt> <dd> 994 995This texture is made up of 6 2D textures which are pasted around the inside of a cube. The base_name in this format is something like ’skybox.jpg’, and the system will expect you to provide skybox_fr.jpg, skybox_bk.jpg, skybox_up.jpg, skybox_dn.jpg, skybox_lf.jpg, and skybox_rt.jpg for the individual faces. 996Alternatively 1 cube texture can be used if supported by the texture format(DDS for example) and rendersystem. Can be addressed with 3D texture coordinates and are useful for cubic reflection maps and normal maps. 997</dd> </dl> 998 999@param numMipMaps 1000specify the number of mipmaps to generate for this texture. The default is ’unlimited’ which means mips down to 1x1 size are generated. You can specify a fixed number (even 0) if you like instead. Note that if you use the same texture in many material scripts, the number of mipmaps generated will conform to the number specified in the first texture\_unit used to load the texture - so be consistent with your usage. 1001 1002@param alpha @copydoc Ogre::Texture::setTreatLuminanceAsAlpha 1003Default: none 1004 1005@param PixelFormat 1006specify the desired pixel format of the texture to create, which may be different to the pixel format of the texture file being loaded. Bear in mind that the final pixel format will be constrained by hardware capabilities so you may not get exactly what you ask for. 1007Names defined in Ogre::PixelFormat are valid values. 1008 1009@param gamma 1010informs the renderer that you want the graphics hardware to perform gamma correction on the texture values as they are sampled for rendering. This is only applicable for textures which have 8-bit colour channels (e.g.PF\_R8G8B8). Often, 8-bit per channel textures will be stored in gamma space in order to increase the precision of the darker colours (<http://en.wikipedia.org/wiki/Gamma_correction>) but this can throw out blending and filtering calculations since they assume linear space colour values. For the best quality shading, you may want to enable gamma correction so that the hardware converts the texture values to linear space for you automatically when sampling the texture, then the calculations in the pipeline can be done in a reliable linear colour space. When rendering to a final 8-bit per channel display, you’ll also want to convert back to gamma space which can be done in your shader (by raising to the power 1/2.2) or you can enable gamma correction on the texture being rendered to or the render window. Note that the ’gamma’ option on textures is applied on loading the texture so must be specified consistently if you use this texture in multiple places. 1011 1012<a name="anim_005ftexture"></a><a name="anim_005ftexture-1"></a> 1013 1014## anim\_texture 1015 1016Sets the images to be used in an animated texture layer. There are 2 formats, one for implicitly determined image names, one for explicitly named images. 1017@par 1018Format1 (short): anim\_texture <name> <numFrames> <duration> 1019 1020@copydetails Ogre::TextureUnitState::setAnimatedTextureName 1021 1022@par 1023Example: anim\_texture flame.jpg 5 2.5 1024 1025@par 1026Format2 (long): anim\_texture <frame1> <frame2> ... <duration> 1027@par 1028Example: anim\_texture flamestart.jpg flamemore.png flameagain.jpg moreflame.jpg lastflame.tga 2.5 1029 1030This sets up the same duration animation but from 5 separately named image files. The first format is more concise, but the second is provided if you cannot make your images conform to the naming standard required for it. 1031@par 1032Default: none 1033 1034<a name="cubic_005ftexture"></a><a name="cubic_005ftexture-1"></a> 1035 1036## cubic\_texture 1037 1038Sets the images used in a cubic texture, i.e. one made up of 6 individual images making up the faces of a cube or 1 cube texture if supported by the texture format(DDS for example) and rendersystem.. These kinds of textures are used for reflection maps (if hardware supports cubic reflection maps) or skyboxes. There are 2 formats, a brief format expecting image names of a particular format and a more flexible but longer format for arbitrarily named textures. 1039@par 1040Format1 (short): cubic\_texture <base\_name> <combinedUVW|separateUV> 1041 1042@deprecated use the format '`texture <basename> cubic`' instead 1043 1044The base\_name in this format is something like ’skybox.jpg’, and the system will expect you to provide skybox\_fr.jpg, skybox\_bk.jpg, skybox\_up.jpg, skybox\_dn.jpg, skybox\_lf.jpg, and skybox\_rt.jpg for the individual faces. 1045 1046@par 1047Format2 (long): cubic\_texture <front> <back> <left> <right> <up> <down> <combinedUVW|separateUV> 1048 1049In this case each face is specified explicitly, incase you don’t want to conform to the image naming standards above. You can only use this for the separateUV version since the combinedUVW version requires a single texture name to be assigned to the combined 3D texture (see below). 1050 1051In both cases the final parameter means the following: 1052 1053<dl compact="compact"> 1054<dt>separateUV</dt> <dd> 1055 1056@deprecated Use real cubic textures due to hardware support 1057 1058The 6 textures are kept separate but are all referenced by this single texture layer. One texture at a time is active (they are actually stored as 6 frames), and they are addressed using standard 2D UV coordinates. 1059</dd> 1060<dt>combinedUVW</dt> <dd> 1061 1062The 6 textures are combined into a single ’cubic’ texture map which is then addressed using 3D texture coordinates. 1063 1064</dd> 1065</dl> <br> 1066 1067<a name="binding_005ftype"></a><a name="binding_005ftype-1"></a> 1068 1069## binding\_type 1070 1071@copydetails Ogre::TextureUnitState::setBindingType 1072 1073@see @ref Vertex-Texture-Fetch 1074 1075Format: binding\_type <vertex|fragment> 1076@par 1077Default: binding\_type fragment 1078 1079<a name="content_005ftype"></a> 1080 1081## content_type 1082 1083Tells this texture unit where it should get its content from. The default is to get texture content from a named texture, as defined with the [texture](#texture), [cubic\_texture](#cubic_005ftexture), [anim\_texture](#anim_005ftexture) attributes. However you can also pull texture information from other automated sources. 1084 1085@par 1086Format: content\_type <type> \[<compositorName>\] \[<textureName>\] \[<mrtIndex>\] 1087 1088@param type 1089<dl compact="compact"> 1090<dt>named</dt> <dd> 1091 1092@copydoc Ogre::TextureUnitState::CONTENT_NAMED 1093 1094</dd> <dt>shadow</dt> <dd> 1095 1096This option allows you to pull in a shadow texture, and is only valid when you use texture shadows and one of the ’custom sequence’ shadowing types (See @ref Shadows). The shadow texture in question will be from the ’n’th closest light that casts shadows, unless you use light-based pass iteration or the light\_start option which may start the light index higher. When you use this option in multiple texture units within the same pass, each one references the next shadow texture. The shadow texture index is reset in the next pass, in case you want to take into account the same shadow textures again in another pass (e.g. a separate specular / gloss pass). By using this option, the correct light frustum projection is set up for you for use in fixed-function, if you use shaders just reference the texture\_viewproj\_matrix auto parameter in your shader. 1097 1098</dd> <dt>compositor</dt> <dd> 1099 1100@copydoc Ogre::TextureUnitState::CONTENT_COMPOSITOR This can be either in a render\_scene directive inside a compositor script, or in a general pass in a viewport that has a compositor attached. Note that this is a reference only, meaning that it does not change the render order. You must make sure that the order is reasonable for what you are trying to achieve (for example, texture pooling might cause the referenced texture to be overwritten by something else by the time it is referenced). 1101 1102</dd> </dl> 1103 1104@copydetails Ogre::TextureUnitState::setCompositorReference 1105 1106@par 1107Example: content\_type compositor DepthCompositor OutputTexture 1108 1109@par 1110Default: content\_type named 1111 1112 1113<a name="tex_005fcoord_005fset"></a><a name="tex_005fcoord_005fset-1"></a> 1114 1115## tex\_coord\_set 1116 1117@copydoc Ogre::TextureUnitState::setTextureCoordSet 1118 1119@par 1120Format: tex\_coord\_set <set\_num> 1121 1122@note Only has an effect with the fixed-function pipeline or the @ref rtss 1123 1124@par 1125Example: tex\_coord\_set 2 1126@par 1127Default: tex\_coord\_set 0 1128 1129<a name="colour_005fop"></a><a name="colour_005fop-1"></a> 1130 1131## colour\_op 1132 1133@note Only has an effect with the fixed-function pipeline or the @ref rtss 1134 1135Determines how the colour of this texture layer is combined with the one below it (or the lighting effect on the geometry if this is the first layer). 1136@par 1137Format: colour\_op <op> 1138 1139@copydetails Ogre::TextureUnitState::setColourOperation Without the `LBO_` prefix. E.g. `LBO_REPLACE` becomes `replace`. 1140 1141@par 1142Default: colour\_op modulate 1143 1144<a name="colour_005fop_005fex"></a><a name="colour_005fop_005fex-1"></a> 1145 1146## colour\_op\_ex 1147 1148@note Only has an effect with the fixed-function pipeline or the @ref rtss 1149@par 1150Format: colour\_op\_ex <op> <source1> <source2> \[<manualBlend>\] \[<arg1>\] \[<arg2>\] 1151@par 1152Example colour\_op\_ex add\_signed src\_manual src\_current 0.5 1153 1154@copydetails Ogre::TextureUnitState::setColourOperationEx 1155 1156Each parameter can be one of Ogre::LayerBlendOperationEx or Ogre::LayerBlendSource without the prefix. E.g. `LBX_MODULATE_X4` becomes `modulate_x4`. 1157 1158@par 1159Default: none (colour\_op modulate)<br> 1160 1161<a name="colour_005fop_005fmultipass_005ffallback"></a><a name="colour_005fop_005fmultipass_005ffallback-1"></a> 1162 1163## colour\_op\_multipass\_fallback 1164 1165Sets the multipass fallback operation for this layer, if you used colour\_op\_ex and not enough multitexturing hardware is available. 1166@par 1167Format: colour\_op\_multipass\_fallback <src\_factor> <dest\_factor> 1168@par 1169Example: colour\_op\_multipass\_fallback one one\_minus\_dest\_alpha 1170 1171@copydetails Ogre::TextureUnitState::setColourOpMultipassFallback 1172 1173<a name="alpha_005fop_005fex"></a><a name="alpha_005fop_005fex-1"></a> 1174 1175## alpha\_op\_ex 1176 1177@note Only has an effect with the fixed-function pipeline or the @ref rtss 1178 1179@par 1180Format: alpha\_op\_ex <op> <source1> <source2> \[<manualBlend>\] \[<arg1>\] \[<arg2>\] 1181 1182@copydetails Ogre::TextureUnitState::setAlphaOperation 1183 1184<a name="env_005fmap"></a><a name="env_005fmap-1"></a> 1185 1186## env\_map 1187 1188Turns on/off texture coordinate effect that makes this layer an environment map. @note Only has an effect with the fixed-function pipeline or the @ref rtss 1189@par 1190Format: env\_map <off|spherical|planar|cubic\_reflection|cubic\_normal> 1191 1192Environment maps make an object look reflective by using automatic texture coordinate generation depending on the relationship between the objects vertices or normals and the eye. 1193 1194<dl compact="compact"> 1195<dt>spherical</dt> <dd> 1196 1197A spherical environment map. Requires a single texture which is either a fish-eye lens view of the reflected scene, or some other texture which looks good as a spherical map (a texture of glossy highlights is popular especially in car sims). This effect is based on the relationship between the eye direction and the vertex normals of the object, so works best when there are a lot of gradually changing normals, i.e. curved objects. 1198 1199</dd> <dt>planar</dt> <dd> 1200 1201Similar to the spherical environment map, but the effect is based on the position of the vertices in the viewport rather than vertex normals. This effect is therefore useful for planar geometry (where a spherical env\_map would not look good because the normals are all the same) or objects without normals. 1202 1203</dd> <dt>cubic\_reflection</dt> <dd> 1204 1205A more advanced form of reflection mapping which uses a group of 6 textures making up the inside of a cube, each of which is a view if the scene down each axis. Works extremely well in all cases but has a higher technical requirement from the card than spherical mapping. Requires that you bind a [cubic\_texture](#cubic_005ftexture) to this texture unit and use the ’combinedUVW’ option. 1206 1207</dd> <dt>cubic\_normal</dt> <dd> 1208 1209Generates 3D texture coordinates containing the camera space normal vector from the normal information held in the vertex data. Again, full use of this feature requires a [cubic\_texture](#cubic_005ftexture) with the ’combinedUVW’ option. 1210 1211</dd> </dl> <br> 1212@par 1213Default: env\_map off<br> 1214 1215<a name="scroll"></a><a name="scroll-1"></a> 1216 1217## scroll 1218 1219@copybrief Ogre::TextureUnitState::setTextureScroll 1220@par 1221Format: scroll <u> <v> 1222 1223@copydetails Ogre::TextureUnitState::setTextureScroll 1224 1225@note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1226 1227<a name="scroll_005fanim"></a><a name="scroll_005fanim-1"></a> 1228 1229## scroll\_anim 1230 1231@copybrief Ogre::TextureUnitState::setScrollAnimation 1232@par 1233Format: scroll\_anim <uSpeed> <vSpeed><br> 1234 1235@copydetails Ogre::TextureUnitState::setScrollAnimation 1236 1237@note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1238<a name="rotate"></a><a name="rotate-1"></a> 1239 1240## rotate 1241 1242@copybrief Ogre::TextureUnitState::setTextureRotate 1243 1244@par 1245Format: rotate <angle> 1246 1247@copydetails Ogre::TextureUnitState::setTextureRotate 1248 1249@note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1250 1251<a name="rotate_005fanim"></a><a name="rotate_005fanim-1"></a> 1252 1253## rotate\_anim 1254 1255@copybrief Ogre::TextureUnitState::setRotateAnimation 1256 1257@par 1258Format: rotate\_anim <speed> 1259 1260@copydetails Ogre::TextureUnitState::setRotateAnimation 1261 1262@note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1263 1264<a name="scale"></a><a name="scale-1"></a> 1265 1266## scale 1267 1268@copybrief Ogre::TextureUnitState::setTextureScale 1269 1270@par 1271Format: scale <uScale> <vScale> 1272 1273@copydetails Ogre::TextureUnitState::setTextureScale 1274 1275 1276 @note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1277 1278<a name="wave_005fxform"></a><a name="wave_005fxform-1"></a> 1279 1280## wave\_xform 1281 1282@copybrief Ogre::TextureUnitState::setTransformAnimation 1283 1284@par 1285Format: wave\_xform <ttype> <waveType> <base> <frequency> <phase> <amplitude> 1286@par 1287Example: wave\_xform scale\_x sine 1.0 0.2 0.0 5.0 1288 1289@copydetails Ogre::TextureUnitState::setTransformAnimation 1290 1291ttype is one of 1292<dl compact="compact"> 1293<dt>scroll\_x</dt> <dd> 1294 1295Animate the u scroll value 1296 1297</dd> <dt>scroll\_y</dt> <dd> 1298 1299Animate the v scroll value 1300 1301</dd> <dt>rotate</dt> <dd> 1302 1303Animate the rotate value 1304 1305</dd> <dt>scale\_x</dt> <dd> 1306 1307Animate the u scale value 1308 1309</dd> <dt>scale\_y</dt> <dd> 1310 1311Animate the v scale value 1312 1313</dd> </dl> 1314 1315waveType is one of Ogre::WaveformType without the `WFT_` prefix. E.g. `WFT_SQUARE` becomes `square`. 1316 1317@note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1318 1319<a name="transform"></a><a name="transform-1"></a> 1320 1321## transform 1322 1323This attribute allows you to specify a static 4x4 transformation matrix for the texture unit, thus replacing the individual scroll, rotate and scale attributes mentioned above. 1324@par 1325Format: transform m00 m01 m02 m03 m10 m11 m12 m13 m20 m21 m22 m23 m30 m31 m32 m33 1326 1327The indexes of the 4x4 matrix value above are expressed as m<row><col>. 1328 1329 @note if you’re using a vertex program this will have no effect unless you use the texture\_matrix auto-param. 1330 1331<a name="sampler_ref"></a> 1332## sampler_ref 1333 1334By default all texture units use a shared default Sampler object. This parameter allows you to explicitly set a different one. 1335 1336@par 1337Format: sampler_ref <name> 1338 1339@par 1340Example: sampler_ref mySampler 1341 1342# Samplers {#Samplers} 1343 1344Samplers allow you to quickly change the settings for all associated Textures. Typically you have many Textures but only a few sampling states in your application. 1345 1346```cpp 1347sampler mySampler 1348{ 1349 filtering bilinear 1350 max_anisotropy 16 1351} 1352 1353... 1354 texture_unit 1355 { 1356 texture myTexture.dds 1357 sampler_ref mySampler 1358 } 1359... 1360``` 1361 1362## Available parameters 1363 1364- [filtering](#filtering) 1365- [max\_anisotropy](#max_005fanisotropy) 1366- [tex\_address\_mode](#tex_005faddress_005fmode) 1367- [tex\_border\_colour](#tex_005fborder_005fcolour) 1368- [mipmap\_bias](#mipmap_005fbias) 1369- [compare_test](#compare_test) 1370- [comp_func](#comp_func) 1371 1372<a name="tex_005faddress_005fmode"></a><a name="tex_005faddress_005fmode-1"></a> 1373 1374## tex\_address\_mode 1375 1376Defines what happens when texture coordinates exceed 1.0 for this texture layer.You can use the simple format to specify the addressing mode for all 3 potential texture coordinates at once, or you can use the 2/3 parameter extended format to specify a different mode per texture coordinate. 1377@par 1378Simple Format: tex\_address\_mode <uvw\_mode> <br> Extended Format: tex\_address\_mode <u\_mode> <v\_mode> \[<w\_mode>\] 1379 1380Valid values for both are one of Ogre::TextureAddressingMode without the `TAM_` prefix. E.g. `TAM_WRAP` becomes `wrap`. 1381 1382@par 1383Default: tex\_address\_mode wrap 1384 1385<a name="tex_005fborder_005fcolour"></a><a name="tex_005fborder_005fcolour-1"></a> 1386 1387## tex\_border\_colour 1388 1389Sets the border colour of border texture address mode (see [tex\_address\_mode](#tex_005faddress_005fmode)). 1390@par 1391Format: tex\_border\_colour <red> <green> <blue> \[<alpha>\]<br> NB valid colour values are between 0.0 and 1.0. 1392@par 1393Example: tex\_border\_colour 0.0 1.0 0.3 1394@par 1395Default: tex\_border\_colour 0.0 0.0 0.0 1.0 1396 1397<a name="filtering"></a><a name="filtering-1"></a> 1398 1399## filtering 1400 1401Sets the type of texture filtering used when magnifying or minifying a texture. There are 2 formats to this attribute, the simple format where you simply specify the name of a predefined set of filtering options, and the complex format, where you individually set the minification, magnification, and mip filters yourself. 1402 1403### Simple Format 1404With this format, you only need to provide a single parameter 1405 1406@par 1407Format: filtering <none|bilinear|trilinear|anisotropic><br> Default: filtering bilinear 1408 1409<dl compact="compact"> 1410<dt>none</dt> <dd> 1411@copydoc Ogre::TFO_NONE 1412</dd> 1413<dt>bilinear</dt> <dd> 1414@copydoc Ogre::TFO_BILINEAR 1415</dd> 1416<dt>trilinear</dt> <dd> 1417@copydoc Ogre::TFO_TRILINEAR 1418</dd> 1419<dt>anisotropic</dt> <dd> 1420@copydoc Ogre::TFO_ANISOTROPIC 1421</dd> </dl> 1422 1423### Complex Format 1424This format gives you complete control over the minification, magnification, and mip filters. 1425 1426@par 1427Format: filtering <minFilter> <magFilter> <mipFilter> 1428@par 1429Default: filtering linear linear point 1430 1431Each parameter can be one of Ogre::FilterOptions without the `FO_` prefix. E.g. `FO_LINEAR` becomes `linear`. 1432 1433@copydetails Ogre::TextureUnitState::setTextureFiltering(FilterOptions,FilterOptions,FilterOptions) 1434 1435<a name="max_005fanisotropy"></a><a name="max_005fanisotropy-1"></a> 1436 1437## max\_anisotropy 1438 1439@copybrief Ogre::TextureUnitState::setTextureAnisotropy 1440 1441@par 1442Format: max\_anisotropy <maxAniso><br> Default: max\_anisotropy 1 1443 1444@copydetails Ogre::TextureUnitState::setTextureAnisotropy 1445 1446<a name="mipmap_005fbias"></a><a name="mipmap_005fbias-1"></a> 1447 1448## mipmap\_bias 1449 1450@copydetails Ogre::TextureUnitState::setTextureMipmapBias 1451 1452@par 1453Format: mipmap\_bias <value><br> Default: mipmap\_bias 0 1454 1455<a name="compare_test"></a> 1456## compare_test 1457 1458@copydoc Ogre::Sampler::setCompareEnabled 1459 1460@par 1461Format: compare_test on 1462 1463@par 1464Default: compare_test off 1465 1466<a name="comp_func"></a> 1467 1468## comp_func 1469 1470The comparison func to use when @c compare_test is enabled 1471@par 1472Format: comp_func <func> 1473 1474@param func one of Ogre::CompareFunction without the `CMPF_` prefix. E.g. `CMPF_LESS_EQUAL` becomes `less_equal`. 1475 1476# Declaring GPU Programs {#Declaring-Vertex_002fGeometry_002fFragment-Programs} 1477 1478In order to use a vertex, geometry or fragment program in your materials (See [Using Vertex/Geometry/Fragment Programs in a Pass](@ref Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass)), you first have to define them. A single program definition can be used by any number of materials, the only prerequisite is that a program must be defined before being referenced in the pass section of a material. 1479 1480The definition of a program can either be embedded in the .material script itself (in which case it must precede any references to it in the script), or if you wish to use the same program across multiple .material files, you can define it in an external .program script. You define the program in exactly the same way whether you use a .program script or a .material script, the only difference is that all .program scripts are guaranteed to have been parsed before **all** .material scripts, so you can guarantee that your program has been defined before any .material script that might use it. Just like .material scripts, .program scripts will be read from any location which is on your resource path, and you can define many programs in a single script. 1481 1482Vertex, geometry and fragment programs can be low-level (i.e. assembler code written to the specification of a given low level syntax such as vs\_1\_1 or arbfp1) or high-level such as DirectX9 HLSL, Open GL Shader Language, or nVidia’s Cg language (See @ref High-level-Programs). High level languages give you a number of advantages, such as being able to write more intuitive code, and possibly being able to target multiple architectures in a single program (for example, the same Cg program might be able to be used in both D3D and GL, whilst the equivalent low-level programs would require separate techniques, each targeting a different API). High-level programs also allow you to use named parameters instead of simply indexed ones, although parameters are not defined here, they are used in the Pass. 1483 1484Here is an example of a definition of a low-level vertex program: 1485 1486```cpp 1487vertex_program myVertexProgram asm 1488{ 1489 source myVertexProgram.asm 1490 syntax vs_1_1 1491} 1492``` 1493 1494As you can see, that’s very simple, and defining a fragment or geometry program is exactly the same, just with vertex\_program replaced with fragment\_program or geometry\_program, respectively. You give the program a name in the header, followed by the word ’asm’ to indicate that this is a low-level program. Inside the braces, you specify where the source is going to come from (and this is loaded from any of the resource locations as with other media), and also indicate the syntax being used. You might wonder why the syntax specification is required when many of the assembler syntaxes have a header identifying them anyway - well the reason is that the engine needs to know what syntax the program is in before reading it, because during compilation of the material, we want to skip programs which use an unsupportable syntax quickly, without loading the program first. 1495 1496The current supported syntaxes are: 1497 1498<dl compact="compact"> 1499<dt>vs\_1\_1</dt> <dd> 1500 1501This is one of the DirectX vertex shader assembler syntaxes. <br> Supported on cards from: ATI Radeon 8500, nVidia GeForce 3 <br> 1502 1503</dd> <dt>vs\_2\_0</dt> <dd> 1504 1505Another one of the DirectX vertex shader assembler syntaxes. <br> Supported on cards from: ATI Radeon 9600, nVidia GeForce FX 5 series <br> 1506 1507</dd> <dt>vs\_2\_x</dt> <dd> 1508 1509Another one of the DirectX vertex shader assembler syntaxes. <br> Supported on cards from: ATI Radeon X series, nVidia GeForce FX 6 series <br> 1510 1511</dd> <dt>vs\_3\_0</dt> <dd> 1512 1513Another one of the DirectX vertex shader assembler syntaxes. <br> Supported on cards from: ATI Radeon HD 2000+, nVidia GeForce FX 6 series 1514 1515</dd> <dt>arbvp1</dt> <dd> 1516 1517This is the OpenGL standard assembler format for vertex programs. It’s roughly equivalent to DirectX vs\_1\_1. 1518 1519</dd> <dt>vp20</dt> <dd> 1520 1521This is an nVidia-specific OpenGL vertex shader syntax which is a superset of vs 1.1. ATI Radeon HD 2000+ also supports it. 1522 1523</dd> <dt>vp30</dt> <dd> 1524 1525Another nVidia-specific OpenGL vertex shader syntax. It is a superset of vs 2.0, which is supported on nVidia GeForce FX 5 series and higher. ATI Radeon HD 2000+ also supports it. 1526 1527</dd> <dt>vp40</dt> <dd> 1528 1529Another nVidia-specific OpenGL vertex shader syntax. It is a superset of vs 3.0, which is supported on nVidia GeForce FX 6 series and higher. 1530 1531</dd> <dt>ps\_1\_1, ps\_1\_2, ps\_1\_3</dt> <dd> 1532 1533DirectX pixel shader (i.e. fragment program) assembler syntax. <br> Supported on cards from: ATI Radeon 8500, nVidia GeForce 3 <br> @note for ATI 8500, 9000, 9100, 9200 hardware, this profile can also be used in OpenGL. The ATI 8500 to 9200 do not support arbfp1 but do support atifs extension in OpenGL which is very similar in function to ps\_1\_4 in DirectX. Ogre has a built in ps\_1\_x to atifs compiler that is automatically invoked when ps\_1\_x is used in OpenGL on ATI hardware. 1534 1535</dd> <dt>ps\_1\_4</dt> <dd> 1536 1537DirectX pixel shader (i.e. fragment program) assembler syntax. <br> Supported on cards from: ATI Radeon 8500, nVidia GeForce FX 5 series <br> @note for ATI 8500, 9000, 9100, 9200 hardware, this profile can also be used in OpenGL. The ATI 8500 to 9200 do not support arbfp1 but do support atifs extension in OpenGL which is very similar in function to ps\_1\_4 in DirectX. Ogre has a built in ps\_1\_x to atifs compiler that is automatically invoked when ps\_1\_x is used in OpenGL on ATI hardware. 1538 1539</dd> <dt>ps\_2\_0</dt> <dd> 1540 1541DirectX pixel shader (i.e. fragment program) assembler syntax. <br> Supported cards: ATI Radeon 9600, nVidia GeForce FX 5 series<br> 1542 1543</dd> <dt>ps\_2\_x</dt> <dd> 1544 1545DirectX pixel shader (i.e. fragment program) assembler syntax. This is basically ps\_2\_0 with a higher number of instructions. <br> Supported cards: ATI Radeon X series, nVidia GeForce FX 6 series<br> 1546 1547</dd> <dt>ps\_3\_0</dt> <dd> 1548 1549DirectX pixel shader (i.e. fragment program) assembler syntax. <br> Supported cards: ATI Radeon HD 2000+, nVidia GeForce FX6 series<br> 1550 1551</dd> <dt>ps\_3\_x</dt> <dd> 1552 1553DirectX pixel shader (i.e. fragment program) assembler syntax. <br> Supported cards: nVidia GeForce FX7 series<br> 1554 1555</dd> <dt>arbfp1</dt> <dd> 1556 1557This is the OpenGL standard assembler format for fragment programs. It’s roughly equivalent to ps\_2\_0, which means that not all cards that support basic pixel shaders under DirectX support arbfp1 (for example neither the GeForce3 or GeForce4 support arbfp1, but they do support ps\_1\_1). 1558 1559</dd> <dt>fp20</dt> <dd> 1560 1561This is an nVidia-specific OpenGL fragment syntax which is a superset of ps 1.3. It allows you to use the ’nvparse’ format for basic fragment programs. It actually uses NV\_texture\_shader and NV\_register\_combiners to provide functionality equivalent to DirectX’s ps\_1\_1 under GL, but only for nVidia cards. However, since ATI cards adopted arbfp1 a little earlier than nVidia, it is mainly nVidia cards like the GeForce3 and GeForce4 that this will be useful for. You can find more information about nvparse at http://developer.nvidia.com/object/nvparse.html. 1562 1563</dd> <dt>fp30</dt> <dd> 1564 1565Another nVidia-specific OpenGL fragment shader syntax. It is a superset of ps 2.0, which is supported on nVidia GeForce FX 5 series and higher. ATI Radeon HD 2000+ also supports it. 1566 1567</dd> <dt>fp40</dt> <dd> 1568 1569Another nVidia-specific OpenGL fragment shader syntax. It is a superset of ps 3.0, which is supported on nVidia GeForce FX 6 series and higher. 1570 1571</dd> <dt>gpu\_gp, gp4\_gp</dt> <dd> 1572 1573An nVidia-specific OpenGL geometry shader syntax. <br> Supported cards: nVidia GeForce FX8 series<br> 1574 1575</dd> <dt>glsles</dt> <dd> 1576 1577OpenGL Shading Language for Embedded Systems. It is a variant of GLSL, streamlined for low power devices. Supported cards: PowerVR SGX series 1578 1579</dd> </dl> 1580 1581You can get a definitive list of the syntaxes supported by the current card by calling GpuProgramManager::getSingleton().getSupportedSyntax(). 1582 1583# Specifying Named Constants for Assembler Shaders {#Specifying-Named-Constants-for-Assembler-Shaders} 1584 1585Assembler shaders don’t have named constants (also called uniform parameters) because the language does not support them - however if you for example decided to precompile your shaders from a high-level language down to assembler for performance or obscurity, you might still want to use the named parameters. Well, you actually can - GpuNamedConstants which contains the named parameter mappings has a ’save’ method which you can use to write this data to disk, where you can reference it later using the manual\_named\_constants directive inside your assembler program declaration, e.g. 1586 1587```cpp 1588vertex_program myVertexProgram asm 1589{ 1590 source myVertexProgram.asm 1591 syntax vs_1_1 1592 manual_named_constants myVertexProgram.constants 1593} 1594``` 1595 1596In this case myVertexProgram.constants has been created by calling highLevelGpuProgram->getNamedConstants().save("myVertexProgram.constants"); sometime earlier as preparation, from the original high-level program. Once you’ve used this directive, you can use named parameters here even though the assembler program itself has no knowledge of them. 1597 1598# Default Program Parameters {#Default-Program-Parameters} 1599 1600While defining a vertex, geometry or fragment program, you can also specify the default parameters to be used for materials which use it, unless they specifically override them. You do this by including a nested ’default\_params’ section, like so: 1601 1602```cpp 1603vertex_program Ogre/CelShadingVP cg 1604{ 1605 source Example_CelShading.cg 1606 entry_point main_vp 1607 profiles vs_1_1 arbvp1 1608 1609 default_params 1610 { 1611 param_named_auto lightPosition light_position_object_space 0 1612 param_named_auto eyePosition camera_position_object_space 1613 param_named_auto worldViewProj worldviewproj_matrix 1614 param_named shininess float 10 1615 } 1616} 1617``` 1618 1619The syntax of the parameter definition is exactly the same as when you define parameters when using programs, See @ref Program-Parameter-Specification. Defining default parameters allows you to avoid rebinding common parameters repeatedly (clearly in the above example, all but ’shininess’ are unlikely to change between uses of the program) which makes your material declarations shorter. 1620 1621# Declaring Shared Parameters {#Declaring-Shared-Parameters} 1622 1623Often, not every parameter you want to pass to a shader is unique to that program, and perhaps you want to give the same value to a number of different programs, and a number of different materials using that program. Shared parameter sets allow you to define a ’holding area’ for shared parameters that can then be referenced when you need them in particular shaders, while keeping the definition of that value in one place. To define a set of shared parameters, you do this: 1624 1625```cpp 1626shared_params YourSharedParamsName 1627{ 1628 shared_param_named mySharedParam1 float4 0.1 0.2 0.3 0.4 1629 ... 1630} 1631``` 1632 1633As you can see, you need to use the keyword ’shared\_params’ and follow it with the name that you will use to identify these shared parameters. Inside the curly braces, you can define one parameter per line, in a way which is very similar to the [param\_named](#param_005fnamed) syntax. The definition of these lines is: 1634@par 1635Format: shared\_param\_name <param\_name> <param\_type> \[<\[array\_size\]>\] \[<initial\_values>\] 1636 1637@param param_name must be unique within the set 1638@param param_type can be any one of float, float2, float3, float4, int, int2, int3, int4, matrix2x2, matrix2x3, matrix2x4, matrix3x2, matrix3x3, matrix3x4, matrix4x2, matrix4x3 and matrix4x4. 1639@param array_size allows you to define arrays of param\_type should you wish, and if present must be a number enclosed in square brackets (and note, must be separated from the param\_type with whitespace). 1640@param initial_values If you wish, you can also initialise the parameters by providing a list of values. 1641 1642Once you have defined the shared parameters, you can reference them inside default\_params and params blocks using [shared\_params\_ref](#shared_005fparams_005fref). You can also obtain a reference to them in your code via GpuProgramManager::getSharedParameters, and update the values for all instances using them. 1643 1644# Adding new Techniques, Passes, to copied materials {#Adding-new-Techniques_002c-Passes_002c-to-copied-materials_003a} 1645 1646If 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. 1647 1648@note 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. 1649 1650# Identifying Texture Units to override values {#Identifying-Texture-Units-to-override-values} 1651 1652A 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. 1653 1654```cpp 1655material BumpMap2 : BumpMap1 1656{ 1657 technique ati8500 1658 { 1659 pass 0 1660 { 1661 texture_unit NormalMap 1662 { 1663 texture BumpyMetalNM.png 1664 } 1665 } 1666 } 1667} 1668``` 1669 1670# Texture Aliases {#Texture-Aliases} 1671 1672Texture aliases are useful for when only the textures used in texture units need to be specified for a cloned material. In the source material i.e. 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. Note that texture aliases are a more specific version of [Script Variables](#Script-Variables) which can be used to easily set other values. 1673 1674Using texture aliases within texture units: 1675@par 1676Format: texture\_alias <name> 1677@par 1678Default: <name> will default to texture\_unit <name> if set 1679 1680```cpp 1681texture_unit DiffuseTex 1682{ 1683 texture diffuse.jpg 1684} 1685``` 1686 1687texture\_alias defaults to DiffuseTex.<br> 1688 1689Example: The base material to be cloned:<br> 1690 1691```cpp 1692material TSNormalSpecMapping 1693{ 1694 technique GLSL 1695 { 1696 pass 1697 { 1698 ambient 0.1 0.1 0.1 1699 diffuse 0.7 0.7 0.7 1700 specular 0.7 0.7 0.7 128 1701 1702 vertex_program_ref GLSLDemo/OffsetMappingVS 1703 { 1704 param_named_auto lightPosition light_position_object_space 0 1705 param_named_auto eyePosition camera_position_object_space 1706 param_named textureScale float 1.0 1707 } 1708 1709 fragment_program_ref GLSLDemo/TSNormalSpecMappingFS 1710 { 1711 param_named normalMap int 0 1712 param_named diffuseMap int 1 1713 param_named fxMap int 2 1714 } 1715 1716 // Normal map 1717 texture_unit NormalMap 1718 { 1719 texture defaultNM.png 1720 tex_coord_set 0 1721 filtering trilinear 1722 } 1723 1724 // Base diffuse texture map 1725 texture_unit DiffuseMap 1726 { 1727 texture defaultDiff.png 1728 filtering trilinear 1729 tex_coord_set 1 1730 } 1731 1732 // spec map for shininess 1733 texture_unit SpecMap 1734 { 1735 texture defaultSpec.png 1736 filtering trilinear 1737 tex_coord_set 2 1738 } 1739 1740 } 1741 } 1742 1743 technique HLSL_DX9 1744 { 1745 pass 1746 { 1747 1748 vertex_program_ref FxMap_HLSL_VS 1749 { 1750 param_named_auto worldViewProj_matrix worldviewproj_matrix 1751 param_named_auto lightPosition light_position_object_space 0 1752 param_named_auto eyePosition camera_position_object_space 1753 } 1754 1755 fragment_program_ref FxMap_HLSL_PS 1756 { 1757 param_named ambientColor float4 0.2 0.2 0.2 0.2 1758 } 1759 1760 // Normal map 1761 texture_unit 1762 { 1763 texture_alias NormalMap 1764 texture defaultNM.png 1765 tex_coord_set 0 1766 filtering trilinear 1767 } 1768 1769 // Base diffuse texture map 1770 texture_unit 1771 { 1772 texture_alias DiffuseMap 1773 texture defaultDiff.png 1774 filtering trilinear 1775 tex_coord_set 1 1776 } 1777 1778 // spec map for shininess 1779 texture_unit 1780 { 1781 texture_alias SpecMap 1782 texture defaultSpec.png 1783 filtering trilinear 1784 tex_coord_set 2 1785 } 1786 1787 } 1788 } 1789} 1790``` 1791 1792Note 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> For 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. 1793 1794Now 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. 1795 1796@par 1797Format: set\_texture\_alias <alias name> <texture name><br> 1798 1799```cpp 1800material fxTest : TSNormalSpecMapping 1801{ 1802 set_texture_alias NormalMap fxTestNMap.png 1803 set_texture_alias DiffuseMap fxTestDiff.png 1804 set_texture_alias SpecMap fxTestMap.png 1805} 1806``` 1807 1808The textures in both techniques in the child material will automatically get replaced with the new ones we want to use. 1809 1810The 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. 1811 1812You don’t have to supply all the textures in the copied material.<br> 1813 1814```cpp 1815material fxTest2 : fxTest 1816{ 1817 set_texture_alias DiffuseMap fxTest2Diff.png 1818 set_texture_alias SpecMap fxTest2Map.png 1819} 1820``` 1821 1822Material fxTest2 only changes the diffuse and spec maps of material fxTest and uses the same normal map. 1823 1824Another example: 1825 1826```cpp 1827material fxTest3 : TSNormalSpecMapping 1828{ 1829 set_texture_alias DiffuseMap fxTest2Diff.png 1830} 1831``` 1832 1833fxTest3 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. 1834