Changes between Version 3 and Version 4 of MaterialSystem

Timestamp:

Apr 15, 2012, 5:31:19 PM (12 years ago)

Author:

Philip Taylor

Comment:

effects

MaterialSystem

@@ -34 +34 @@
 Located in [source:ps/trunk/binaries/data/mods/public/art/materials art/materials/]. Example:
 {{{
+#!xml
 <?xml version="1.0" encoding="utf-8"?>
 <material>
@@ -84 +85 @@
  * `USE_TRANSPARENT` - `1` when the texture's alpha channel should be output by the fragment shader.
  * `DISABLE_RECEIVE_SHADOWS` - `1` when shadows should not be cast onto this object.
+
+== Shader effects and techniques ==
+
+Located in [source:ps/trunk/binaries/data/mods/public/shaders/effects shaders/effects/]. Example:
+
+{{{
+#!xml
+<?xml version="1.0" encoding="utf-8"?>
+<effect>
+
+    <technique>
+        <require context="MODE_SHADOWCAST || MODE_SILHOUETTEOCCLUDER"/>
+        <require shaders="arb"/>
+        <pass shader="arb/model_solid"/>
+    </technique>
+
+    <technique>
+        <require context="MODE_SHADOWCAST || MODE_SILHOUETTEOCCLUDER"/>
+        <require shaders="glsl"/>
+        <pass shader="glsl/model_solid"/>
+    </technique>
+
+    <technique>
+        <require context="MODE_SHADOWCAST || MODE_SILHOUETTEOCCLUDER"/>
+        <require shaders="fixed"/>
+        <define name="USE_PLAYERCOLOR" value="0"/>
+        <define name="USE_OBJECTCOLOR" value="0"/>
+        <pass shader="fixed:model_solid"/>
+    </technique>
+
+    ...
+
+    <technique>
+        <require context="ALPHABLEND_PASS_BLEND"/>
+        <require shaders="fixed"/>
+        <sort_by_distance/>
+        <pass shader="fixed:model">
+            <define name="USE_TRANSPARENT" value="1"/>
+            <alpha func="gequal" ref="0.05"/>
+            <blend src="src_alpha" dst="one_minus_src_alpha"/>
+            <depth func="less" mask="false"/>
+        </pass>
+    </technique>
+
+</effect>
+}}}
+
+An `<effect>` contains one or more `<technique>`s. Each technique can have a set of requirements:
+ * `<require context="..."/>` - an arbitrary conditional expression. (This can refer to defines that come from the material, or the current rendering mode, or the global rendering context.)
+ * `<require shaders="glsl"/>` - requires that GLSL shaders are supported and enabled.
+ * `<require shaders="arb"/>` - requires that ARB shaders are supported and enabled.
+ * `<require shaders="fixed"/>` - requires that fixed-function (OpenGL 1.4ish) rendering is supported and enabled.
+Whenever a material tries to use an effect, the most preferred technique whose requirements are satisfied will be used. There must always be at least one usable technique in each effect. Typically, techniques that are defined earliest in the XML file will be preferred over techniques defined later. The exception is if the `preferglsl` config option (or `renderer.preferGLSL` in the console) is true, techniques requiring GLSL will always be more preferred than others; if `preferglsl` is false (the default), then ones requiring GLSL will always be less preferred.
+
+`<technique>` can also contain:
+ * (zero or more) `<define name="..." value="..."/>` - add a new define which may be used by the technique's shader programs.
+ * (rarely used) `<sort_by_distance/>` - required if the technique includes a pass that uses non-commutative alpha-blending. (This causes the engine to sort models from furthest to nearest before rendering, to get correct alpha-blending behaviour.)
+ * (one or more) `<pass shader="...">` - see below.
+
+A '''pass''' is a rendering of a collection of models with a single set of OpenGL state (shader, blending settings, etc). Most techniques only use a single pass, but it's possible to do multi-pass rendering (e.g. do one pass that just writes depth data, and a second pass that writes colour on top of it).
+
+Every pass is rendered with a shader program (via the `shader="..."` attribute). `<pass>` can also contain:
+ * (zero or more) `<define name="..." value="..."/>` - add a new define which may be used by the pass's shader program.
+ * `<alpha func="..." ref="..."/>` - equivalent to `glAlphaFunc(func, ref)`. `ref` is a float. `func` can be one of `never`, `always`, `less`, `lequal`, `equal`, `gequal`, `greater`, `notequal`.
+ * `<blend src="..." dst="..."/>` - equivalent to `glBlendFunc(src, dst)`. `src` and `dst` can be one of `zero`, `one`, `(one_minus_)?(src|dst|constant)_(color|alpha)`, `src_alpha_saturate`.
+ * `<depth func="..."/>` - equivalent to `glDepthFunc(func)`. `func` can be the same values as `<alpha func>`.
+ * `<depth mask="..."/>` - equivalent to `glDepthMask(mask)`. `mask` can be `true` or `false`.