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-09-27 09:33]
Carsten Clarified the texture options, added references to the OpenGL Red Book
@@ 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:
-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.
+FIXME  This list will be detailed soon!
+==== The SkyDomes 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.
+==== The Terrains Shader ====
-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.
+==== The Solid Shader ====
-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.
-  * **''AmbientShader MyFavouriteAmbientShader''** specifies that the shader with name "MyFavouriteAmbientShader" should be used for rendering the ambient part of this material.
-  * **''LightShader MyFavouriteLightShader''** specifies that the shader with name "MyFavouriteLightShader" should be used for rendering the per-lightsource contribution of this material.
-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:
-If we had a way to override the automatic shader-selection by manually specifying the desired shader, our custom shader
-In the Ca3DE Material System, a //Shader// is a module of compiled C++ code.
-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.
-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.
-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 and specular highlights) of that material.
-Here is the crucial point:
-The material scripts described so far do only allow you to define a 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,
-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
-''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:
-<code>
-    Textures/Kai/barrel_rst
-    {
-        diffusemap    Textures/Kai/barrel_rst_diff.png
-        normalmap     Textures/Kai/barrel_rst_norm.png
-        specularmap   Textures/Kai/barrel_rst_spec.png
-        lightmap      $lightmap
-        ambientShader myCarMetallicBlue_ambient
-        lightShader   myCarMetallicBlue_light
-    }
-</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 "none" Shader ====
 ====== Keyword Reference ======
@@ Line 424: / Line 361: @@
 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