Differences

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

--- matsys:cmat_manual [2005-09-25 21:54]
Carsten Text review -- UNFINISHED
+++ 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.
 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 =====
@@ Line 133: / Line 132: @@
     * **''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.
-    * **''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.
-  * **''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.
-    * **''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.
-  * **''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:
@@ Line 153: / Line 154: @@
     }
 </code>
 ====== Shader Specifications ======
-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 look. In cases like our example materials above, the MatSys automatically selects shaders from a built-in library for our materials automatically.
+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 look. In cases like our example materials above, the MatSys selects shaders from a built-in library automatically, picking the one that best fits the material.
 But what if you want to change the way how your materials are rendered, either 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 all, so what if you want to have a material with cube-map environment reflections?
-The answer to these questions is two-fold: You have to override the automatic shader selection by assigning a shader manually. But 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 a 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.
+The answer to these questions is two-fold: You have to override the automatic shader selection by assigning a shader manually. But 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 a 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.
-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 a programmer, you 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 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 a programmer, you 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]].
-FIXME The rest of this section is //work-in-progress//.  Please stop reading here.  ;)  I'll fix it asap.
+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: First, the //ambient// part of a material is rendered, that is, everything that is rendered even if no light source is present. The //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 reflections, specular highlights and other effetcs. The per-light-source contributions are controlled by the //light shader// of a material.
-<file>
+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:
-               and it was mentioned that exactly //how// a material like the following is rendered is automatically determined, namely as a variant of the Phong lighting model. The cube-map in this example would be entirely ignored, simply because the built-in Phong lighting does not take it into account.
+  * **''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>
-    Textures/Kai/babtech
+    Textures/Kai/barrel_rst
     {
-        diffusemap  Textures/Kai/babtech_diff.png
+        AmbientShader myCarMetallicBlue_ambient
-        normalmap   Textures/Kai/babtech_norm.png
+        LightShader   myCarMetallicBlue_light
-        cubeMap     Textures/SkyDomes/PK_BrightDay2#.png    // Ignored...
+        diffusemap    Textures/Kai/barrel_rst_diff.png
+        normalmap     flipNMyAxis(Textures/Kai/barrel_rst_norm.png)
+        cubeMap       Textures/SkyDomes/ReflectiveCubeMap#.jpg
     }
 </code>
-Specifying **shaders** is a method to alter the way how materials are rendered.
-Before we start, lets briefly review what shaders are (the [[MatSys::Introduction#Shaders|MatSys Introduction]] also gives an overview about them): Each MatSys [[MatSys::Introduction#Renderer]] has several built-in shaders, and a shader defines how exactly a certain material is rendered. Therefore, when a MatSys renderer is given any material like those in the above examples, it consults its built-in shader library. Each material must be assigned a shader eventually, and the renderer picks the shader that it determined to be the best fit for this material.
-The automatic selection however may be wrong. For example, the automatic selection algorithm only knows Phong lighting, because that is most often used, but nothing about cube-maps. The above material will get a shader assigned that uses the diffuse- and normal-map for Phong lighting, but has no use for the cube-map. This is why it seems that the cube-map is ignored.
+===== Built-in special-purpose Shaders =====
-Now assume we knew that the MatSys renderers had another built-in shader with the name "MyCarMetallicBlueShader". That shader was not covered by the auto-selection algorithm, but it still comes built-in with the renderer. Also assume that we knew that this shader employs a diffuse-map and a normal-map for rendering a great metallic car look, and it also uses the cube-map for adding an interesting environmental reflection effect. Then, if we overrode the automatic shader assignment and instead assigned the "MyCarMetallicBlueShader" shader to our example material above, we had achieved exactly what was desired: We had brought together an entirely new, independent rendering technique (in form of the "MyCarMetallicBlueShader" shader) with a material.
+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]].
-Note that "MyCarMetallicBlueShader" is free to render polygon meshes in any way it likes. It may have no relationship at all to Phong lighting as the other built-in shaders. It may use the cube-map for environmental reflections or anything else it likes. It may use the diffuse- or normal- or any other map for purposes that are similar or entirely different to what one might expect. In fact, in a sense we have to know the programmer of "MyCarMetallicBlueShader" in order to know that deals with the diffuse-, normal- and cube-maps, but not with the specular- or luma-maps.
+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.
-This in turn is a great key to flexibility and rendering power: The non-automatic shaders that are built into the Ca3DE renderers are documented below.
+==== The SkyDome Shader ====
-That means that we need a method to assign a different shader to the material manually, overriding the automatic shader-selection. The good news is that the Material System has not only the Phong lighting shaders built-in that are taken into account for automatic selection. It also has other shaders built-in. These additional shaders might render a material in a much different fashion than the others. As you know, a shader can in fact render a material in an arbitrary way, as it is the shader that defines how exactly a material is rendered.
+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:
-For example, assume that another shader is built into the MatSys that can render the above material with environmental reflections from the cube-map. We would want to specify that instead of the auto-selection.
+<code>
+    Textures/SkyDomes/PK_BrightDay2
+    {
+        // Activate the A_SkyDome shader as the ambient shader
+        AmbientShader A_SkyDome
-Before getting into the details, there is one fact left about materials and shaders: Each material gets not only one shader assigned, but //two//. 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 a different type and renders the per-light-source contribution (diffuse lighting, specular highlights etc.) of that material.
+        // Have no dynamic light affect surfaces with this material.
+        LightShader   none
+        noDynLight
-  * **''AmbientShader MyFavouriteAmbientShader''** specifies that the shader with name "MyFavouriteAmbientShader" should be used for rendering the ambient part of this material.
+        // The '#' in the next line is auto-replaced with the relevant suffixes (_px, _ny, ...).
+        cubeMap Textures/SkyDomes/PK_BrightDay2#.png, wrapS clampToEdge, wrapT clampToEdge
-  * **''LightShader MyFavouriteLightShader''** specifies that the shader with name "MyFavouriteLightShader" should be used for rendering the per-lightsource contribution of this material.
+        // 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
-In order to fix this, we need an own, custom shader. For example, a shader would be useful that also takes the cube-map into account. We might even go a step farther:
+        // This keyword states that this material casts sunlight.
+        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>
-If we had a way to override the automatic shader-selection by manually specifying the desired shader, our custom shader
+The **''AmbientShader A_SkyDome''** line activates the ambient sky dome shader. Note that the far away sky dome is //not// affected by light of any dynamic light source, and therefore we assign the **''none''** shader as the per-lightsource shader in order to make sure that no dynamic light is applied to sky surfaces. The **''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''**.
+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.
-In the Ca3DE Material System, a //Shader// is a module of compiled C++ code.
+==== The Terrain Shader ====
-A shader is responsible for rendering a 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 large, pre-built library of shaders.
+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
-When the MatSys and the current renderer is initialized on program start,
+<code>
-each material gets automatically assigned the best shader from the renderers shader library.
+    AmbientShader A_Terrain
-That is, depending on which texture map specifications you have defined for a material,
+</code>
-the shader that can best handle the given combination is found and assigned to that material.
+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.
-In truth however, not only one but //two// shaders are assigned to the material.
+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:
-This is because one shader is specific to rendering the //ambient// part of the material,
+<code>
-i.e. everything that is rendered even if no light source is present.
+    diffusemap Textures/Terrains/BPRockB_tx1.png, wrapS clampToEdge, wrapT clampToEdge
-The second shader is of a different type and renders the per-light-source contribution
+    lightmap $lightmap
-(diffuse lighting and specular highlights) of that material.
+</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//!
-Here is the crucial point:
+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.
-The material scripts described so far do only allow you to define a limited number of material effects,
+<code>
-namely all those that can be specified by different combinations of the texture map image keywords
+    lumamap    Textures/Terrains/CommonDetail2.png      // "A_Terrain" takes the Luma-map as Detail-map (optional).
-as explained in section [[matsys::cmat_Manual#Texture_Map_Specifications]].
+</code>
-This may seem like a serious limitation. However, not only can probably the big majority of your materials
+The detail-map is optional, and may be omitted. However, terrains look a lot better with them, and so their use is recommended.
-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,
+:?: 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. \\
-and force your own shader to be selected.
+:!: 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!
-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
+Finally, you need this block of statements in the body of your material definition:
-''ambientShader'' and ''lightShader'' keywords that are followed by the name of the custom shader.
+<code>
-Here is an example, where the existence of two custom, self-made shaders is assumed:
+    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>
-    Textures/Kai/barrel_rst
+    Terrains/BPRockB_tx1
     {
-        diffusemap    Textures/Kai/barrel_rst_diff.png
+        AmbientShader A_Terrain
-        normalmap     Textures/Kai/barrel_rst_norm.png
+        LightShader   none
-        specularmap   Textures/Kai/barrel_rst_spec.png
+        noDynLight
-        lightmap      $lightmap
-        ambientShader myCarMetallicBlue_ambient
+        diffusemap Textures/Terrains/BPRockB_tx1.png, wrapS clampToEdge, wrapT clampToEdge
-        lightShader   myCarMetallicBlue_light
+        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>
-As custom shaders are free to do anything they want, they may or may not redefine the meaning of the
-texture map image specification keywords. For example, they may use the normal-map for purposes different
-than just obtaining surface shape information from it, or 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.  </file>
+==== 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 ======
-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 below, or 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//.
-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.)
@@ Line 283: / 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.
-  * **''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).
@@ Line 314: / 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.
+===== Meta Keywords =====
 Finally, here are the meta-parameters that are taken into account by the Ca3DE map compile tools.
@@ Line 424: / Line 532: @@
 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.

User Manual

Differences

About Cafu

About the User Manual

Get Involved

Learn More

User Manual

User Tools

Site Tools

Differences

Page Tools

About Cafu

About the User Manual

Get Involved

Learn More