User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
matsys:cmat_manual [2005-10-09 12:17] Carsten Wrote contents for the special-purpose shaders sections |
matsys:cmat_manual [2005-10-22 15:08] Carsten Revised the Keywords Reference section |
||
|---|---|---|---|
| Line 238: | Line 238: | ||
| 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 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 ==== | ||
| Line 261: | Line 260: | ||
| :!: 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. | :!: 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 textures, it makes sense to also specify **''clampToEdge''** border wrapping for the diffuse texture: | + | 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> | <code> | ||
| diffusemap Textures/Terrains/BPRockB_tx1.png, wrapS clampToEdge, wrapT clampToEdge | diffusemap Textures/Terrains/BPRockB_tx1.png, wrapS clampToEdge, wrapT clampToEdge | ||
| Line 270: | Line 269: | ||
| 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. | 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> | <code> | ||
| - | lumamap Textures/Terrains/CommonDetail1.png // "A_Terrain" takes the Luma-map as Detail-map (optional). | + | lumamap Textures/Terrains/CommonDetail2.png // "A_Terrain" takes the Luma-map as Detail-map (optional). |
| </code> | </code> | ||
| The detail-map is optional, and may be omitted. However, terrains look a lot better with them, and so their use is recommended. | The detail-map is optional, and may be omitted. However, terrains look a lot better with them, and so their use is recommended. | ||
| Line 303: | Line 302: | ||
| diffusemap Textures/Terrains/BPRockB_tx1.png, wrapS clampToEdge, wrapT clampToEdge | diffusemap Textures/Terrains/BPRockB_tx1.png, wrapS clampToEdge, wrapT clampToEdge | ||
| lightmap $lightmap | lightmap $lightmap | ||
| - | lumamap Textures/Terrains/CommonDetail1.png | + | lumamap Textures/Terrains/CommonDetail2.png |
| shaderParamExpr fParam4 // The first eight shader parameters are taken from fParam4 to fParam11 | shaderParamExpr fParam4 // The first eight shader parameters are taken from fParam4 to fParam11 | ||
| Line 333: | Line 332: | ||
| 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. | 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. The keywords are order independent. | + | 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//. | 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 351: | 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 382: | 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. | ||
matsys/cmat_manual.txt · Last modified: 2013-01-07 12:07 (external edit)