User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
matsys:cmat_manual:keywordreference [2005-10-23 20:12] Carsten Content revision |
matsys:cmat_manual:keywordreference [2007-09-26 15:40] Carsten Added "trigger" and new param to "clip" keyword |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Keyword Reference ====== | ||
| - | |||
| - | This section lists all keywords that are allowed in the body of a materials definition. | ||
| - | |||
| - | 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::ShaderSpecifications#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)''**. | ||
| - | |||
| - | |||
| - | ===== Shader Specifications ===== | ||
| - | |||
| - | * **''AmbientShader $name''** | ||
| - | * **''LightShader $name''** | ||
| - | |||
| - | These keywords are used to override the automatic shader selection. | ||
| - | They are explained in detail in section [[matsys:cmat_manual::ShaderSpecifications]]. | ||
| - | |||
| - | //The precise meaning of all other keywords is "vague", that is, they depends on the implementation by the selected shader// :!: | ||
| - | |||
| - | |||
| - | ===== 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::TextureMapSpecifications]]. | ||
| - | |||
| - | 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. | ||
| - | |||
| - | |||
| - | ===== 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::ShaderSpecifications#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 (Universal) ===== | ||
| - | |||
| - | The following material parameters are //global rendering parameters//. | ||
| - | They affect the entire material, but only how it is rendered, that is, its "looks". | ||
| - | 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.) | ||
| - | |||
| - | * **''noShadows''** This material never casts shadows. Note that shadow-casting can also be controlled on a per-model and per-lightsource basis. | ||
| - | |||
| - | * **''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. | ||
| - | |||
| - | * **''depthOffset''** | ||
| - | |||
| - | * **''polygonMode''** filled, wireframe, points | ||
| - | |||
| - | |||
| - | ===== Rendering Options (Ambient only) ===== | ||
| - | |||
| - | The following parameters do only affect the ambient contribution of a material (as implemented by the Material Systems ambient default shaders). | ||
| - | The map compile tools never look at these parameters. | ||
| - | Some of these parameters take expressions as their arguments, which are denoted by ''$expr''. | ||
| - | Expressions can be simple numbers or more complex constructs, they are discussed in greater detail in subsection [[#Expressions]]. | ||
| - | |||
| - | * **''alphaTest $expr''** Activates the alpha test with the result of ''$expr'' as the reference value. The alpha test passes if and only if the alpha value of the ambient contribution (which normally comes from the diffuse-map) is greater than the reference value. Note that the reference value can be specified as an expression, that is, it can be //varying over time//. This can produce interesting effects (i.e. materials that appear to grow or shrink) if the diffuse-map comes with an appropriate alpha channel. Negative values turn the alpha test off. The test is off by default. | ||
| - | |||
| - | * **''blendFunc $src_factor $dst_factor''** This parameter determines the blend function for the ambient contribution of the material. ''$src_factor'' and ''$dst_factor'' must be one of ''zero'', ''one'', ''dst_color'', ''src_color'', ''one_minus_dst_color'', ''one_minus_src_color'', ''dst_alpha'', ''src_alpha'', ''one_minus_dst_alpha'', or ''one_minus_src_alpha''. Note that not all combinations make sense. Using ''blendFunc'' will be documented in greater detail in future releases of this text. Per default, blending is turned off. | ||
| - | |||
| - | * **''red $expr''** | ||
| - | * **''green $expr''** | ||
| - | * **''blue $expr''** | ||
| - | * **''alpha $expr''** | ||
| - | * **''rgb $expr''** | ||
| - | * **''rgba $expr''** These parameters all define expressions for (channels of) the color with which the ambient contribution is modulated. I have defined the default ambient shaders such that for materials that have luma-maps, only the luma-map is modulated. Materials that have no luma-map get the entire ambient contribution modulated. This allows to create effects such as panels that have flickering LEDs, glowing lights etc. Note that you can specify different expressions for different color channels. That is, if you have a luma-map for a computer panel that has both red and green LEDs, you can for example have the red LEDs morse SOS, while the green LEDs change gradually by a sinus function. The default expression for all color channels is 1.0 (identity). | ||
| - | |||
| - | * **''ambientMask''** | ||
| - | |||
| - | * **''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. | ||
| - | |||
| - | |||
| - | ===== Rendering Options (Light only) ===== | ||
| - | |||
| - | * **''noDynLight''** If specified, this material does not receive any light from dynamic light sources, only the ambient contribution is rendered. (Technically, the material does not even get a per-light-source shader assigned.) Useful e.g. for sky domes, additive effects like particles, translucent surfaces like water and glass etc. | ||
| - | |||
| - | * **''lightMask''** | ||
| - | |||
| - | |||
| - | ===== Meta Keywords ===== | ||
| - | |||
| - | Finally, here are the meta-parameters that are taken into account by the Ca3DE map compile tools. | ||
| - | These parameters are not directly related to the rendering of the material. | ||
| - | |||
| - | * **''meta_radiantExitance''** Radiant Exitance RGB values plus intensity (scale). Used by CaLight. | ||
| - | |||
| - | * **''meta_radiantExitance_byImage''** Radiant Exitance RGB values from image file. Used by CaLight, plus Radiant Exitance intensity (scale) for the RGB values from image file. Used by CaLight. | ||
| - | |||
| - | * **''meta_sunlight ($r $g $b) ($x $y $z)''** | ||
| - | |||
| - | * **''meta_alphaModulatesRadiosityLight''** Makes CaLight handle the DiffMapComps alpha channel and the RGBAGens properly. For fences, grates, glass, water, etc. | ||
| - | |||
| - | * **''meta_noLightMap''** Makes the compile tools not cover this material with a lightmap. | ||
| - | |||
| - | |||
| - | ===== Expressions ===== | ||
| - | |||
| - | Some of the above keywords cannot only take numbers as their arguments, but entire mathematical **expressions**. | ||
| - | An expression is a combination of numbers, mathematical operations, symbols, and table look-ups. | ||
| - | Here is an example for such an expression: | ||
| - | <code> | ||
| - | (1 + sinTable[ time*0.25 + 3 ]) / 2 | ||
| - | </code> | ||
| - | Unfortunately, there are also bad news: The current parser of the Ca3DE MatSys is not yet powerful enough to | ||
| - | parse expressions that use operator infix notation like the one above. | ||
| - | Instead of ''+'', ''-'', ''*'', ... we therefore have to use explicit prefix notation, | ||
| - | which is much easier to parse. The prefix notation is explained below. | ||
| - | Here is the above example in prefix notation that we have to use until I can improve the parser to support infix notation: | ||
| - | <code> | ||
| - | div(add(1, sinTable[ add(mul(time, 0.25), 3) ]), 2) | ||
| - | </code> | ||
| - | |||
| - | Expressions are defined recursively as follows: | ||
| - | |||
| - | * **''$num''** A number. | ||
| - | |||
| - | * **''$var''** A variable. Please see below for a list of all valid variables. | ||
| - | |||
| - | * **''$table[ $expr ]''** A table look-up. The value of the table at position ''$expr'' is returned. The details of the look-up depend on the tables definition. The default tables ''sinTable'' and ''cosTable'' are always predefined. Custom tables can be defined as described in subsection [[#Tables]]. Note that table look-ups are normalized. That is, all table elements are accessed by indices between 0.0 and 1.0, that is, the fractional part of ''$expr''. | ||
| - | |||
| - | * **''add($expr1, $expr2)''** Adds the results of ''$expr1'' and ''$expr2''. | ||
| - | |||
| - | * **''sub($expr1, $expr2)''** Subtracts the results of ''$expr1'' and ''$expr2''. | ||
| - | |||
| - | * **''mul($expr1, $expr2)''** Multiplies the results of ''$expr1'' and ''$expr2''. | ||
| - | |||
| - | * **''div($expr1, $expr2)''** Divides the results of ''$expr1'' and ''$expr2'' if ''$expr2'' is not 0. Otherwise, this evaluates to 0. | ||
| - | |||
| - | |||
| - | The following variables are defined: | ||
| - | |||
| - | * **''time''** The current system time in seconds, starting from zero. | ||
| - | |||
| - | Tables and table look-ups are described in subsection [[#Tables]]. | ||
| - | |||
| - | |||
| - | ===== Tables ===== | ||
| - | |||
| - | Another type of object that you can define in material scripts are **tables**. | ||
| - | Tables are a very powerful means to express arbitrary functions for use in expressions. | ||
| - | Expressions are explained in detail above in subsection [[#Expressions]]. | ||
| - | |||
| - | Table definitions start with the keyword ''table'', followed by the name of the table. | ||
| - | Then come two ''{''s, the table data values separated by commas, and then the closing two ''}''s. | ||
| - | Here is an example of a table definition: | ||
| - | <code> | ||
| - | table myFlickerTable { { 0.5, 1, 0, 0.2, 0.0, 0.8, 0.1, 0.7 } } | ||
| - | </code> | ||
| - | |||
| - | The elements of tables can be accessed from expressions as explained in subsection [[#Expressions]]. | ||
| - | It is important to note that the indices for table access are treated as //normalized// indices. | ||
| - | That means that all values of a table are accessed with numbers that are greater or equal to 0.0 and less than 1.0. | ||
| - | In the above table, which has eight elements, you'd get 0.5 for ''myFlickerTable[0.0]'', 1 for ''myFlickerTable[0.125]'', | ||
| - | 0.2 for ''myFlickerTable[0.375]'' and so on. | ||
| - | |||
| - | As tables normally wrap, that is, start over when you read over their end, you will get 0.5 also for ''myFlickerTable[1.0]'' | ||
| - | (but 0.7 for ''myFlickerTable[0.9999]''). | ||
| - | You may want to think of this as only the fractional part of the index being taken for the look-up, while the integer part is ignored. | ||
| - | That means that for example the expression | ||
| - | <code> | ||
| - | rgb myFlickerTable[time] | ||
| - | </code> | ||
| - | runs through the entire table exactly once per second, //no matter how many elements the table actually has//. | ||
| - | |||
| - | Between the two opening ''{'', one or both of the keywords ''snap'' and ''clamp'' are allowed. | ||
| - | ''snap'' defines that there is no linear interpolation between the table values. | ||
| - | For example, we just said that ''myFlickerTable[0.0]'' yields 0.5 and ''myFlickerTable[0.125]'' yields 1.0. | ||
| - | But what does ''myFlickerTable[0.0625]'' (the middle between 0.0 and 0.125) yield? | ||
| - | If ''snap'' has not been specified, the value will automatically be interpolated between the table elements, | ||
| - | and the result would be 0.75. If however ''snap'' has been defined, the result would be "snapped" to the next lower table element, | ||
| - | and the result would be 0.5. | ||
| - | Figure TODO demonstrates plots of two tables that differ in the use of the ''snap'' keyword but are identical otherwise. | ||
| - | Interpolation is useful whenever you want to have a table to encode functions that have "smooth transitions". | ||
| - | Snapping is useful whenever you want to have a table to encode functions that have "hard transitions". | ||
| - | For example, in order to have LEDs flicker the SOS morse code, you'd use this table: | ||
| - | <code> | ||
| - | table sosTable { snap { 1, 0, 1, 0, 1, 0, 1, 1, 0, 1, 1, 0, | ||
| - | 1, 1, 0, 1, 0, 1, 0, 1, 0, 0, 0 } } | ||
| - | </code> | ||
| - | |||
| - | The ''clamp'' keywords defines what happens if a table is accessed at indices outside of the normalized range 0.0 to 1.0. | ||
| - | Without ''clamp'', the default behaviour is to wrap. | ||
| - | With clamping enabled, the indices are clamped to yield the smallest or greatest table element. | ||
| - | Figure FIXME TODO demonstrates plots of two tables that differ in the use of the ''clamp'' keyword but are identical otherwise. | ||
| - | |||
| - | Tables must be defined before their first use. | ||
| - | As an exception, the two tables ''sinTable'' and ''cosTable'' are implicitly predefined and can always be used without | ||
| - | prior declaration. | ||
| - | 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. | ||
matsys/cmat_manual/keywordreference.txt ยท Last modified: 2013-01-07 12:07 (external edit)