User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
matsys:cmat_manual [2005-09-25 11:24]
Carsten Revised the text
matsys:cmat_manual [2005-10-22 15:08]
Carsten Revised the Keywords Reference section
Line 74: Line 74:
 You can specify arbitrary combinations of these keywords in one material, as only the ''​diffusemap''​ keyword is mandatory. You can specify arbitrary combinations of these keywords in one material, as only the ''​diffusemap''​ keyword is mandatory.
 However, if you use the same keyword more than once, only the last occurrence is considered. The order of the keywords occurrences is not relevant. However, if you use the same keyword more than once, only the last occurrence is considered. The order of the keywords occurrences is not relevant.
- 
  
 ===== Map Compositions ===== ===== Map Compositions =====
Line 121: Line 120:
  
 Finally, you can specify several comma-separated options for the map composition:​ Finally, you can specify several comma-separated options for the map composition:​
-  * **''​minFilter''​** This controls MipMap usage and the filter that is used for texture minification. ​It must be followed by one of+  * **''​minFilter''​** This controls MipMap usage and the filter that is used for texture minification. ​While the default setting usually looks best and also yields the best performance on modern graphics hardware, sometimes it is desireable to turn filtering off and accept some aliasing, as for example for font textures. The ''​minFilter''​ keyword ​must be followed by one of the filter methods
     * **''​nearest''​** or **''​point''​**     * **''​nearest''​** or **''​point''​**
     * **''​linear''​** or **''​bilinear''​**     * **''​linear''​** or **''​bilinear''​**
Line 130: Line 129:
  
   * **''​magFilter''​** This controls the filter that is used for texture magnification and must be followed by one of   * **''​magFilter''​** This controls the filter that is used for texture magnification and must be followed by one of
-    * **''​nearest''​** or **''​point''​** +    * **''​nearest''​** or **''​point''​** ​(There is almost never a reason to use this, except for very rare and special purposes, like some kinds of debugging.) 
-    * **''​linear''​** or **''​bilinear''​** (This is the default.)+    * **''​linear''​** or **''​bilinear''​** (This is the default ​and gives best results.)
  
-  * **''​wrapS''​** This controls horizontal texture wrapping and must be followed by one of+  * **''​wrapS''​** This controls horizontal texture ​coordinate ​wrapping and must be followed by one of
     * **''​repeat''​** for repeating the texture in horizontal direction. This is the default.     * **''​repeat''​** for repeating the texture in horizontal direction. This is the default.
-    * **''​clamp''​** for clamping the texture in horizontal direction.+    * **''​clamp''​** for clamping the texture in horizontal direction, taking the border color into account. As the Ca3DE MatSys never uses or sets the border color, using ''​clamp''​ is rarely ever useful.
     * **''​clampToEdge''​** for clamping the texture in horizontal direction to its edge color. Often useful with cube-map images.     * **''​clampToEdge''​** for clamping the texture in horizontal direction to its edge color. Often useful with cube-map images.
  
-  * **''​wrapT''​** This controls vertical texture wrapping and must be followed by one of+  * **''​wrapT''​** This controls vertical texture ​coordinate ​wrapping and must be followed by one of
     * **''​repeat''​** for repeating the texture in vertical direction. This is the default.     * **''​repeat''​** for repeating the texture in vertical direction. This is the default.
-    * **''​clamp''​** for clamping the texture in vertical direction.+    * **''​clamp''​** for clamping the texture in vertical direction, taking the border color into account. As the Ca3DE MatSys never uses or sets the border color, using ''​clamp''​ is rarely ever useful.
     * **''​clampToEdge''​** for clamping the texture in vertical direction to its edge color. Often useful with cube-map images.     * **''​clampToEdge''​** for clamping the texture in vertical direction to its edge color. Often useful with cube-map images.
  
-  * **''​noScaleDown''​** specifies that the texture image is never scaled down, not even if the user selects a medium or low texture detail setting for tuning the graphics performance. Used e.g. for the Ca3DE splash screen logo, which would get blurred otherwise. (Look into ''​Games/​DeathMatch/​Materials/​Splash.cmat''​ if you want to toy around with it  a little :) ).+  * **''​noScaleDown''​** specifies that the texture image is never scaled down, not even if the user selects a medium or low texture detail setting for tuning the graphics performance. Used e.g. for the Ca3DE splash screen logo, which would get blurred otherwise. (Look into ''​Games/​DeathMatch/​Materials/​Splash.cmat''​ if you want to toy around with it  a little :-) ).
  
 +The meaning of the ''​minFilter'',​ ''​magFilter'',​ ''​wrapS''​ and ''​wrapT''​ options is analogous to their respective meanings in the OpenGL and DirectX APIs. The OpenGL Programming Guide (the "Red Book") about OpenGL version 1.2 and higher has a good explanation about these options. Although the text is specific to OpenGL, the same concepts apply to the above mentioned options. The "Red Book" for version 1.1 does not address the ''​clampToEdge''​ option, but its text is available online at [[http://​www.rush3d.com/​reference/​opengl-redbook-1.1/​chapter09.html]].
 +
 +Here is an example from ''​Games/​DeathMatch/​Materials/​Fonts.cmat''​ that demonstrates how the options are used:
 +<​code>​
 +    Fonts/Arial
 +    {
 +        diffusemap ../​../​Fonts/​Arial.png,​ minFilter nearest, magFilter nearest, noScaleDown
 +        // ...
 +    }
 +</​code>​
  
 ====== Shader Specifications ====== ====== Shader Specifications ======
  
-In the Ca3DE Material Systema //Shader// is a module of compiled C++ code. +The examples of material definitions that we have seen so far were only composed of texture map specifications. ​In the [[MatSys::​Introduction|MatSys Introduction]] we have learned that internally"​shaders"​ take materials to finally implement how they are rendered and how they lookIn cases like our example materials above, the MatSys selects shaders from built-in library automatically,​ picking the one that best fits the material.
-A shader is responsible for rendering ​mesh of geometry with a given material ​in exactly ​one way that is specific to that shader.+
  
-Each renderer of the MatSys comes with a largepre-built ​library of shaders+But what if you want to change ​the way how your materials are renderedeither just in the details or radically from ground up? What if you don't want regular Phong lighting? Or you want an entirely different method to render diffuse-maps or a different way to combine them with normal-maps?​ What if the built-in shaders ​don't cover a way of rendering that you prefer? It also happens that the built-in shaders do not take cube-maps into account at allso what if you want to have a material ​with cube-map environment reflections?​
-When the MatSys and the current renderer is initialized on program start, +
-each material gets automatically assigned the best shader from the renderers shader library. +
-That is, depending on which texture map specifications ​you have defined for a material+
-the shader that can best handle the given combination is found and assigned to that material.+
  
-In truth however, not only one but //two// shaders are assigned ​to the material. +The answer to these questions is two-fold: You have to override ​the automatic shader selection by assigning a shader manuallyBut you also have to "​know"​ that shader: You have to know its name, or you cannot assign it to your material. ​You have to know wether it needs diffuse-map or a cube-map or both, or any other combination ​of texture map images, so that you can specify them in your material ​definition. Sometimes you have to know even more details about it.
-This is because one shader ​is specific ​to rendering the //ambient// part of the material+
-i.e. everything that is rendered even if no light source is present. +
-The second shader is of different type and renders the per-light-source contribution +
-(diffuse lighting and specular highlights) ​of that material.+
  
-Here is the crucial point: +The good news is that the MatSys renderers have more shaders built-in than just those that are considered during the automatical selection. They are documented below, inclusive sample ​material ​definitions,​ and you can use them to override the auto-selection. Alternatively,​ if you know or are programmeryou can also make your own shaders. By making own shaders you gain the greatest flexibility ​that you can get, because only shaders eventually define how materials look, and shaders can do everything that the underlying hardware can do! Creating own shaders is documented at [[matsys::Writing_Shaders]].
-The material ​scripts described so far do only allow you to define ​limited number of material effects, +
-namely all those that can be specified by different combinations of the texture map image keywords +
-as explained in section ​[[matsys::cmat_Manual#​Texture_Map_Specifications]]+
-This may seem like a serious limitation. However, not only can probably the big majority of your materials +
-be defined with the simple means as presented above (more material keywords are presented in subsequent subsections),​ +
-but more important is //that these limitations can be overcome//.+
  
-That means that you can actually override the Material Systems default shader assignment to a material+There is another issue that you should know about shaders: Each material ​gets not only one shader ​assigned, but //two//. This is because ​the Ca3DE Material System ​renders materials in two steps: Firstthe //ambient// part of a material ​is rendered, ​that is, everything that is rendered even if no light source is presentThe //​ambient ​shader// of a material is responsible for how this part is rendered. Then, the parts of the material looks that are contributed by each light source are rendered separately, ​as for example diffuse reflectionsspecular highlights ​and other effetcsThe per-light-source contributions are controlled by the //light shader// ​of a material.
-and force your own shader ​to be selected. +
-This is one of the key properties of the Ca3DE Material System, ​which makes it //very// powerful and flexible: +
-Whenever you want to achieve ​a material ​effect ​that is not covered by the built-in shaders, +
-you can specify your custom shader to render the desired effect. +
-Writing your own shader ​gives you the ultimative freedom to employ ​the latest rendering technology ​as your heart desires. +
-This does of course require you or someone you work with to write a new shader in C++, +
-and to compile and link it to the Material System. +
-Writing new custom shaders for the Ca3DE MatSys will be explained for future released ​of the SDK.+
  
-Overriding ​the auto-selected shaders ​and thus installing your custom shaders is achieved ​with the +You set the ambient ​and light shader of a material (and thereby override the automatic selection) ​with the following ​keywords ​in the material definitions body:
-''​ambientShader''​ and ''​lightShader'' ​keywords ​that are followed by the name of the custom shader. +
-Here is an example, where the existence of two custom, self-made shaders is assumed:+
  
 +  * **''​AmbientShader MyAmbientShader''​** assigns the shader with name ''​MyAmbientShader''​ as the ambient shader to this material.
 +
 +  * **''​LightShader MyLightShader''​** assigns the shader with name ''​MyLightShader''​ as the per-light-source shader to this material.
 +
 +Here is an example for how these statements could be used in a material definition:
 <​code>​ <​code>​
     Textures/​Kai/​barrel_rst     Textures/​Kai/​barrel_rst
     {     {
 +        AmbientShader myCarMetallicBlue_ambient
 +        LightShader ​  ​myCarMetallicBlue_light
 +
         diffusemap ​   Textures/​Kai/​barrel_rst_diff.png         diffusemap ​   Textures/​Kai/​barrel_rst_diff.png
-        normalmap ​    ​Textures/​Kai/​barrel_rst_norm.png +        normalmap ​    flipNMyAxis(Textures/​Kai/​barrel_rst_norm.png) 
-        ​specularmap ​  Textures/Kai/barrel_rst_spec.png +        ​cubeMap ​      ​Textures/​SkyDomes/​ReflectiveCubeMap#​.jpg 
-        ​lightmap ​     $lightmap+    } 
 +</​code>​ 
 + 
 + 
 +===== Built-in special-purpose Shaders ===== 
 + 
 +Currently, all MatSys renderers come with several special-purpose shaders built-in (special-purpose means that they are never taken into account for automatic assignment). In most cases, they are actually pairs of shaders, one shader for the ambient and one shader for the per-light contribution of the same effect, but you will find that the exception to this rule is more often true than not. 
 +More built-in shaders are currently in preparation,​ for example for special effects like cube-map environment reflections,​ realistic water surfaces, etc. Note that any programmer can also write his own shaders, allowing him to implement //any// rendering effect that he wants! This makes the MatSys highly flexible, extensible and future-proof,​ and was one of its primary design goals. Writing own shaders is documented at [[matsys::​Writing_Shaders]]. 
 + 
 +The following special-purpose shaders are currently built into all renderers of the MatSys. Please note these shaders and their related examples are pretty advanced, and you might want to skip them until later. It may be convenient to first finish reading the rest of this documentation,​ which will help to fully understand the special-purpose shader examples. 
 + 
 + 
 +==== The SkyDome Shader ==== 
 + 
 +In order to create surfaces that are invisible like fully transparent glass and instead only show the far sky dome beyond them, the ambient shader **''​A_SkyDome''​** exists. It basically only requires a cube-map for the sky to be specified. In fact, it ignores the specification of any other (i.e. diffuse-, normal-, etc.) maps. However, in most cases you'll want to specify additional keywords that further describe the properties of the sky surfaces. Here is an example: 
 + 
 +<​code>​ 
 +    Textures/​SkyDomes/​PK_BrightDay2 
 +    { 
 +        // Activate the A_SkyDome shader as the ambient shader 
 +        AmbientShader A_SkyDome 
 + 
 +        // Have no dynamic light affect surfaces with this material. 
 +        LightShader ​  ​none 
 +        noDynLight 
 + 
 +        // The '#'​ in the next line is auto-replaced with the relevant suffixes (_px, _ny, ...). 
 +        cubeMap ​Textures/SkyDomes/PK_BrightDay2#​.png, wrapS clampToEdge,​ wrapT clampToEdge 
 + 
 + 
 +        // Don't write into the z-Buffer, so that entities (like missiles) outside of the map can still be drawn. 
 +        ambientMask d 
 + 
 +        // This material does not cast dynamic shadows. 
 +        noShadows 
 + 
 +        // Don't create or keep lightmaps for this material, don't participate in Radiosity computations. 
 +        ​meta_noLightMap
  
-        ​ambientShader myCarMetallicBlue_ambient +        ​// This keyword states that this material casts sunlight. 
-        ​lightShader ​  ​myCarMetallicBlue_light+        ​meta_sunlight 
 +            // The irradiance of the sunlight in Watt/m^2 that comes (or shines) through this material. 
 +            // Values like (100  90  80) might work, too. 
 +            (220  180  100) 
 +            // The direction of the incoming sunlight rays. The z-component should be negative. 
 +            // (These values match the actual position of the sun in the cube-maps.) 
 +            (-17 -699 -715)
     }     }
 </​code>​ </​code>​
  
-As custom shaders are free to do anything they want, they may or may not redefine ​the meaning of the +The **''​AmbientShader A_SkyDome''​** line activates ​the ambient sky dome shaderNote that the far away sky dome is //not// affected by light of any dynamic light sourceand therefore we assign ​the **''​none''​** shader as the per-lightsource shader in order to make sure that no dynamic light is applied to sky surfacesThe **''​noDynLight''​** keyword ​does essentially ​the same as **''​LightShader none''​** and will soon be obsoleted. Until then, please use it together with each occurrence of **''​LightShader none''​**.
-texture map image specification keywordsFor example, they may use the normal-map for purposes different +
-than just obtaining surface shape information from itor they may even use the ''​normalmap''​ +
-keyword for specifying a regular color image that is used for arbitrary purposes. +
-Information about what exactly a custom shaders ​does with the specified texture map images can +
-be learned from the shaders author.+
  
 +The **''​cubeMap ...''​** statement specifies the cube-map that is to be used for this sky. If you also specified other texture maps like diffuse-maps or specular-maps,​ they would simply be ignored, as the **''​A_SkyDome''​** shader has no use for them.
 +
 +The remaining keywords further specify important properties of this material. Please refer to section [[#​Keyword_Reference|Keyword Reference]] for a detailed description. Short explanations of their meanings are given in the comments in the above example.
 +
 +==== The Terrain Shader ====
 +
 +The terrain shader exists in order to render the Ca3DE outdoor terrains, which work a bit different than regular, Phong-lit surfaces. You activate the ambient terrain shader by writing
 +<​code>​
 +    AmbientShader A_Terrain
 +</​code>​
 +in the materials body. Normally, you would now to expect to also assign a terrain-specific shader for the per-lightsource contribution to the terrain, as in
 +<​code>​
 +    LightShader L_Terrain
 +</​code>​
 +However, I have not yet written the **''​L_Terrain''​** shader, and so we have to turn off dynamic lighting for terrains:
 +<​code>​
 +    LightShader none
 +    noDynLight
 +</​code>​
 +:?: Why do terrains not account for light by dynamic light sources? Well, there are several reasons:
 +  - Terrain is typically employed by mappers in outdoor areas that are in bright sunlight. The effect of dynamic light sources would barely be visible, if at all (but cost //a lot// of performance instead).
 +  - Dynamic light sources are normally very "​small"​ when being compared to the extends of terrains, and mappers tend to place them inside buildings rather than in the open area. This further limits the per-lightsource contribution on terrain surfaces.
 +  - I simply have not yet had the time to write the **''​L_Terrain''​** shader.
 +:!: But if for example somebody wanted to model an indoor cave with the Ca3DE terrain technique, having a shader that accounts for the light of dynamic light sources even on terrains would make a lot of sense. Good news is that, as indicated above, it is //easy// to write such a shader -- I'll probably do so as soon as I need one.
 +
 +Next, the **''​A_Terrain''​** (and the future **''​L_Terrain''​**) shader requires a diffuse-map to be specified. This diffuse-map will be scaled to match the physical size of the terrain, that is, it will cover the terrain completely. In order to get the edges of the terrain properly textured, it makes sense to also specify **''​clampToEdge''​** border wrapping for the diffuse texture:
 +<​code>​
 +    diffusemap Textures/​Terrains/​BPRockB_tx1.png,​ wrapS clampToEdge,​ wrapT clampToEdge
 +    lightmap $lightmap
 +</​code>​
 +As the Ca3D-Engine map compile tools will also generate a lightmap for the terrain in order to e.g. take sunlight or other radiosity light sources into account, we specify the **''​lightmap''​** keyword with the engine-supplied lightmap. Note that while the lighting of dynamic light-sources is //not// taken into account, the light of radiosity light sources //is//!
 +
 +Next, the **''​A_Terrain''​** shader employs the texture-map that is specified with the **''​lumamap''​** keyword as a //​detail-map//​ for the terrain. This is a good example for how the specification of a custom shader (here **''​A_Terrain''​**) can entirely alter the meaning of a material keyword. We will see below how the coarseness (the repetition-count) of the detail-map is set.
 +<​code>​
 +    lumamap ​   Textures/​Terrains/​CommonDetail2.png ​     // "​A_Terrain"​ takes the Luma-map as Detail-map (optional).
 +</​code>​
 +The detail-map is optional, and may be omitted. However, terrains look a lot better with them, and so their use is recommended.
 +
 +:?: You may be wondering wether multiple detail-maps can be handled, as for example in FarCry, where they have a detail-map for beach sand, one for rocks, one for grass and one for pavement. \\
 +:!: The answer is: The **''​A_Terrain''​** shader can indeed //not// handle such detail maps. But as before, it would actually be easy to write such a shader as soon as one is needed!
 +
 +Finally, you need this block of statements in the body of your material definition:
 +<​code>​
 +    shaderParamExpr fParam4 ​   // The first eight shader parameters are taken from fParam4 to fParam11
 +    shaderParamExpr fParam5 ​   // and specify the coefficients of two planes for automatic tex-coord generation.
 +    shaderParamExpr fParam6
 +    shaderParamExpr fParam7
 +    shaderParamExpr fParam8
 +    shaderParamExpr fParam9
 +    shaderParamExpr fParam10
 +    shaderParamExpr fParam11
 +    shaderParamExpr 21.3       // Scale / repetitions of the Detail-map.
 +</​code>​
 +The only thing that you may change here is the number of repetitions of the detail-map, 21.3 in the above example. The lines above that are required in order to get the terrain properly rendered and cannot reasonbly be altered.
 +
 +For more information on what all the **''​shaderParamExpr fParam*''​** lines do, please refer to section FIXME (TODO).
 +
 +Here is a complete example for a terrain shader:
 +<​code>​
 +    Terrains/​BPRockB_tx1
 +    {
 +        AmbientShader A_Terrain
 +        LightShader ​  none
 +        noDynLight
 +
 +        diffusemap Textures/​Terrains/​BPRockB_tx1.png,​ wrapS clampToEdge,​ wrapT clampToEdge
 +        lightmap ​  ​$lightmap
 +        lumamap ​   Textures/​Terrains/​CommonDetail2.png
 +
 +        shaderParamExpr fParam4 ​    // The first eight shader parameters are taken from fParam4 to fParam11
 +        shaderParamExpr fParam5 ​    // and specify the coefficients of two planes for automatic tex-coord generation.
 +        shaderParamExpr fParam6
 +        shaderParamExpr fParam7
 +        shaderParamExpr fParam8
 +        shaderParamExpr fParam9
 +        shaderParamExpr fParam10
 +        shaderParamExpr fParam11
 +        shaderParamExpr 21.3        // Scale / Repetitions of the Detail-map.
 +
 +        twoSided ​                   // "​twoSided"​ is required for the SOAR terrain algorithm.
 +    }
 +</​code>​
 +
 +
 +==== The WaterCubeReflect Shader ====
 +
 +In order to turn a polygon into a translucent water surface with moving waves and reflected environment with Fresnel effect, employ the **''​A_WaterCubeReflect''​** shader:
 +FIXME (This section is not complete!)
 +
 +
 +==== The "​none"​ Shaders ====
 +
 +You can use the special **''​none''​** shader both as an ambient or a per-lightsource shader in order to have no shader for ambient or per-lightsource contributions at all.
 +
 +As you have seen in the examples above, this makes sense in several situations. Especially materials that are not affected by local, dynamic light sources often have the **''​LightShader none''​** statement, as for example for sky dome. Note that currently, you still have to combine any **''​LightShader none''​** statement with the **''​noDynLight''​** statement in order to take proper effect. The **''​noDynLight''​** will however become obsolete in future releases of the Ca3DE Material System.
 +
 +Using **''​AmbientShader none''​** is much less frequently useful, and almost only ever employed for "​invisible"​ materials. Note that **''​AmbientShader none''​** also implies **''​LightShader none''​**. Also, in order to take proper effect, the **''​noDraw''​** keyword is required with each occurrence of **''​AmbientShader none''​**,​ but that requirement will be removed and **''​noDraw''​** be obsoleted in future versions of the MatSys.
  
 ====== Keyword Reference ====== ====== Keyword Reference ======
  
-Additional ​keywords are available ​in the body of material definitions+This section lists all keywords ​that are allowed ​in the body of a materials definition
-These keywords ​broaden ​the range of applications ​that can be handled by the built-in ​default ​shaders, + 
-and often reduce ​the need to write custom shaders.+Some of the keywords ​influence ​the automatic selection ​of the shader for the material, others just give more control over the shader that is eventually used for the material, for making better use of the features of that shader, increasing its usefulness. 
 + 
 +Note that the built-in shaders ​of all MatSys renderers were written to comply to the documentation of the keywords belowor rather, the documentation was written to reflect the implementation of the built-in shaders. 
 +If you employ a custom shader (e.g. a self-written one) instead, there is no guarantee that this shader interpretes ​and implements ​the keywords in an identical manner, because the shader is flexible and free to do anything that its author made it to. This is where you need a documentation that is specific to that shader, see [[matsys::​cmat_manual#​Built-in_special-purpose_Shaders]] for the built-in ones. 
 + 
 +In general, most keywords should occur only once per material definition. If such a keyword is stated several times, only its last occurrance is taken into account, overriding its previous statements. The order in which such keywords are specified in the body of the material definition is irrelevant, you may state the keywords in any order. 
 + 
 +However, some keywords are allowed to occur several times, for example for enumerating textures or numbers. For such keywords, the order in which they appear //is// important. Keywords with this feature are explicitly mentioned below. \\ FIXME We should get rid of this exception by changing the syntax to e.g. **''​shaderParamExpr ($expr1, $expr2, ..., $exprN)''​**. 
 + 
 + 
 +===== Texture Map Specifications ===== 
 + 
 +  * **''​diffusemap $mc''​** 
 +  * **''​normalmap $mc''​** 
 +  * **''​specularmap $mc''​** 
 +  * **''​lumamap $mc''​** 
 +  * **''​lightmap $mc''​** 
 +  * **''​shlmap $mc''​** 
 +  * **''​cubeMap $mc''​** 
 +  * **''​cubeMap2 $mc''​** 
 +  * **''​shaderParamMapC $mc''​** 
 + 
 +With these keywords you specify texture map compositions **''​$mc''​** for use with this material. The keywords and texture map compositions are explained in detail in section [[matsys:​cmat_manual#​texture_map_specifications]]. 
 + 
 +The **''​shaderParamMapC''​** keyword is special, as it can occur arbitrarily often! You can use it to pass an arbitrary number of texture-maps to the shader. Materials that employ a custom shader that for example combines several diffuse-maps and several normal-maps might use this keyword in order to list all the textures that the shader employs. 
 + 
 + 
 +===== Shader Specifications ===== 
 + 
 +  * **''​AmbientShader''​** 
 +  * **''​LightShader''​** 
 + 
 +These keywords are used to override the automatic shader selection. 
 +They are explained in detail in section [[matsys:​cmat_manual#​shader_specifications]]. 
 + 
 + 
 +===== Custom Data ===== 
 + 
 +  * **''​shaderParamExpr $expr''​** 
 +  * **''​shaderParamMapC $mc''​** 
 + 
 +These two expressions are used to pass additional information ​to custom shaders. 
 +They can occur arbitrarily often in a material definition, so their order is important. \\ 
 +FIXME: This should be **''​shaderParamExpr ($expr1, ...)''​** etc. in order to get rid of the order requirement. 
 + 
 +The meaning of the expressions and map compositions that you pass to the shader with these keywords entirely depends on how the shader interprets them! The [[matsys:​cmat_manual#​the_terrain_shader|Terrain]] shader is a good example that employs these keywords. \\ 
 +FIXME: Provide more details here. \\ 
 +FIXME: The terrain shader should employ **''​shaderParamMapC''​** rather than **''​lumamap''​** for its detail-map... \\ 
 + 
 + 
 +===== Rendering Options =====
  
 The following material parameters are //global rendering parameters//​. The following material parameters are //global rendering parameters//​.
-They affect the entire material, but only how it is rendered. +They affect the entire material, but only how it is rendered, that is, its "​looks"​
-These parameters are never looked at by the map compile tools.+These parameters are never looked at or taken into account ​by the map compile tools.
  
   * **''​noDraw''​** If specified, this material does not render at all, it becomes invisible. This is probably mostly useful for debugging. (For mappers: ''​noDraw''​ does //not// cause CaBSP to remove any faces from the world. If you want faces to be actually removed, you should rather use the ''​meta_XXX_TODO''​ keyword in order to make CaBSP remove them right from the start.)   * **''​noDraw''​** If specified, this material does not render at all, it becomes invisible. This is probably mostly useful for debugging. (For mappers: ''​noDraw''​ does //not// cause CaBSP to remove any faces from the world. If you want faces to be actually removed, you should rather use the ''​meta_XXX_TODO''​ keyword in order to make CaBSP remove them right from the start.)
Line 222: Line 399:
   * **''​twoSided''​** Normally, the back or "​inside"​ faces of materials are not rendered. This renders both sides of the material. Useful for "​indefinitely"​ thin objects like metal grates and fences, spider webs, ... Note that two-sided faces are currently not properly lit by dynamic light when seen from the back side.   * **''​twoSided''​** Normally, the back or "​inside"​ faces of materials are not rendered. This renders both sides of the material. Useful for "​indefinitely"​ thin objects like metal grates and fences, spider webs, ... Note that two-sided faces are currently not properly lit by dynamic light when seen from the back side.
  
-  * **''​noScaleDown''​** Prevents the texture images from being scaled down when the user optimizes the game graphics. Useful for fonts, HUDs, lightmaps, some model textures (see example below), and everything else that must not get mixed up or blurred by image filtering. Not yet implemented -- texture images are currently never scaled down. 
- 
-  * **''​noMipMaps''​** Prevents the creation of mip-maps for all texture images of this material. Often combined with and useful for similar purposes as NoScaleDown. The figures belows show an example for ''​noScaleDown''​ and ''​noMipMaps''​. 
- 
-{{matsys:​example_nomipmaps_1.png}} {{matsys:​example_nomipmaps_2.png}} {{matsys:​example_nomipmaps_3.png}} 
- 
-An example for the ''​noScaleDown''​ and ''​noMipMaps''​ keywords. 
-Notice the small glitch in the center image, which is a result of mipmaps applied to the texture shown in the left figure. 
-Such glitches are even more disturbing and better visible with animated models, e.g. when the head of the model does slightly turn. 
-With the ''​noScaleDown''​ and ''​noMipMaps''​ keywords applied in the material script, the glitch disappears as shown in the right figure. 
-Rather than using ''​noScaleDown''​ and ''​noMipMaps'',​ another possible solution had been to put the textures for the skin and hair into separate texture images. 
  
 +==== Ambient-Only Rendering Options ====
  
 The following parameters do only affect the ambient contribution of a material (as implemented by the Material Systems ambient default shaders). The following parameters do only affect the ambient contribution of a material (as implemented by the Material Systems ambient default shaders).
Line 253: Line 420:
   * **''​useMeshColors''​** Additionally to the above color definitions,​ this will modulate the materials color with the colors that are specified with the vertices of the mesh that is to be rendered. This option does currently only work in a very limited set of shaders, and is mostly useful internally in CaWE, the Ca3DE World Editor, e.g. for rendering wire-frame stuff. You will rarely ever need this in a real-world material script.   * **''​useMeshColors''​** Additionally to the above color definitions,​ this will modulate the materials color with the colors that are specified with the vertices of the mesh that is to be rendered. This option does currently only work in a very limited set of shaders, and is mostly useful internally in CaWE, the Ca3DE World Editor, e.g. for rendering wire-frame stuff. You will rarely ever need this in a real-world material script.
  
 +
 +===== Meta Keywords =====
  
 Finally, here are the meta-parameters that are taken into account by the Ca3DE map compile tools. Finally, here are the meta-parameters that are taken into account by the Ca3DE map compile tools.
Line 363: Line 532:
 The scope of a table begins at its definition and ends at the end of the material script. The scope of a table begins at its definition and ends at the end of the material script.
 Note that although in the above examples only table element values between 0.0 and 1.0 occur, arbitrary numbers are allowed. Note that although in the above examples only table element values between 0.0 and 1.0 occur, arbitrary numbers are allowed.
- 
matsys/cmat_manual.txt · Last modified: 2013-01-07 12:07 (external edit)