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 [2013-01-07 12:07] (current) |
||
|---|---|---|---|
| Line 6: | Line 6: | ||
| 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. | 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. | + | If you employ a custom shader (e.g. a self-written one) instead, there is no guarantee that this shader interprets 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. | + | In general, most keywords should occur only once per material definition. If such a keyword is stated several times, only its last occurrence 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)''**. | 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)''**. | ||
| Line 67: | Line 67: | ||
| * **''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. | ||
| - | * **''depthOffset''** | + | * **''depthOffset $num''** This sets the polygonal depth offset. Z-buffer values of meshes that are rendered with this material are slightly offset as defined by $num, which should normally be a negative number. Materials that employ ''depthOffset -1.0'' are for example used internally by CaWE, in order to render the highlighting of selected objects. |
| - | + | ||
| - | * **''polygonMode''** filled, wireframe, points | + | |
| + | * **''polygonMode $pm''** This sets the polygon mode of a mesh. CaWE employs this keyword for rendering the objects in the 3D wire-frame mode. ''$pm'' must be one of | ||
| + | * **''filled''** | ||
| + | * **''wireframe''** | ||
| + | * **''points''** | ||
| ===== Rendering Options (Ambient only) ===== | ===== Rendering Options (Ambient only) ===== | ||
| Line 90: | Line 92: | ||
| * **''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). | * **''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''** | + | * **''ambientMask $turnoff''** This specifies into which framebuffer channel should //not// be written when rendering the ambient pass. ''$turnoff'' must be a combination of the characters ''r'', ''g'', ''b'', ''a'' and ''d'', where ''r'' refers to the red color channel, ''g'', ''b'' and ''a'' refer to the green, blue and alpha color channels respectively, and ''d'' refers to the depth buffer value. \\ For example, ''ambientMask d'' is used with many particle (sprites) material definitions, in order to avoid that particles change the contents of the depth buffer, in order to meet the fact that particles are often rendered in an unsorted, additive manner. ''ambientMask d'' is also used for sky-dome material defs, so that we are able to render e.g. far away missiles or other objects in the sky that would otherwise be rejected by the depth test against the (nearer) sky dome polygons. \\ Note that employing ''ambientMask d'', that is, //not// writing into the depth buffer during the ambient pass, also makes dynamic lighting of such affected meshes impossible. Therefore, ''ambientMask d'' should always be combined with ''LightShader none'' and ''noDynLight''. FIXME: The MatSys should issue a warning if that is not the case. \\ Another example for employing this keyword is ''ambientMask gb'', which makes sure that nothing gets rendered into the green and blue color channels, leaving only red (and alpha and depth). This yields an effect similar to Doom3, when you see only red while the player has a foreboding vision. |
| - | * **''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 Cafu World Editor, e.g. for rendering wire-frame stuff. You will rarely ever need this in a real-world material script. |
| Line 99: | Line 101: | ||
| * **''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. | * **''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''** | + | * **''lightMask $turnoff''** This is very similar to ''ambientMask'', but it only affects the per-lightsource passes. This keyword is currently not used in any Cafu material. |
| - | ===== Meta Keywords ===== | + | ===== Other Keywords ===== |
| - | Finally, here are the meta-parameters that are taken into account by the Ca3DE map compile tools. | + | There are also keywords that define other aspects of the material that are not directly related to their rendering. |
| - | These parameters are not directly related to the rendering of the material. | + | |
| - | * **''meta_radiantExitance''** Radiant Exitance RGB values plus intensity (scale). Used by CaLight. | + | * **''clip $c1, $c2, ...''** Defines for whom or for which purposes the material is considered solid in clipping (collision detection) computations. This is mostly interesting in game related settings (e.g. with player or monster clip brushes), but also programs like CaBSP and CaLight perform clip and ray trace tests that in turn are affected by this keyword. \\ ''$c1, $c2, ...'' must be a comma-separated list of at least one of the flags below. The default setting (i.e. if you do not use the ''clip'' keyword at all), is ''clip all''. When you use ''clip'', the value is first cleared (reset to ''nothing'') and then additively rebuilt from the parameter list. \\ Here is an explanation of the individual flags: |
| + | * ''nothing'' means that a surface with this material clips against nothing, it is non-solid. | ||
| + | * ''players'' means that the surface is solid to players. | ||
| + | * ''monsters'' means that the surface is solid to monsters (AI entities). | ||
| + | * ''moveables'' means that the surface is solid to moveable entities. | ||
| + | * ''ik'' means that the surface is solid to IK. | ||
| + | * ''projectiles'' means that the surface is solid to the projectiles of weapons (e.g. water surfaces, but not sky). | ||
| + | * ''sight'' means that the surface blocks line-of-sight tests (used e.g. for AI). | ||
| + | * ''bspPortals'' means that the surface clips portals, that is, it is solid to the flood-fill operation of CaBSP. \\ :!: Note that each Cafu map must //entirely be sealed// by materials with the ''bspPortals'' property, or else CaBSP will not be able to flood-fill it properly and report that the map has a leak. \\ Developers, note that this means that maps can be made where objects can fall out of the map (e.g. through the floor). Considering the clip-world only, this can be desirable e.g. for rockets that are fired into the sky, even though Cafu has to treat them specially for drawing (render objects in non-PVS "outer" leaves). CaBSP issues a warning if it ever finds a material that has ''bspPortals'', but not both ''players'' and ''monsters'' set, in order to make you aware that in such places, players or monsters could fall out of the map. | ||
| + | * ''radiance'' means that the surface blocks the transfer of light energy in the Radiosity computations of CaLight (most walls do, but for example glass and decals usually don't). | ||
| + | * ''all'' means that the surface is solid to all of the above (but not the ''trigger'' flag below). | ||
| + | * ''trigger'' means that the surface is part of a trigger volume. Entities that have trigger volumes can detect when something enters their volume and then take special actions. For example, a player that walks into a trigger volume can cause a script function to be run that in turn opens a door and spawns some monsters. The ''trigger'' flag is normally not combined with any of the other flags, but for special cases it is still possible to write e.g. ''clip monsters, trigger'' to define a material that is solid only to monsters and a trigger to everything else (e.g. players). | ||
| - | * **''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. | + | * **''surfaceType $st''** Defines the type of the surface. ''$st'' must be one of ''none'', ''stone'', ''metal'', ''sand'', ''wood'', ''liquid'', ''glass'', or ''plastic''. The meaning of the surface types is solely defined by the game code, it will usually use them to play footstep sounds, ricochet effects, etc. |
| - | * **''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 Keywords ===== |
| - | * **''meta_noLightMap''** Makes the compile tools not cover this material with a lightmap. | + | Finally, here are the meta-parameters that are taken into account by the Cafu map compile tools. |
| - | + | These parameters are not directly related to the rendering of the material. | |
| - | + | ||
| - | ===== 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]'' | + | * **''meta_radiantExitance $r $g $b $scale''** Radiant exitance RGB values plus intensity (scale). Used whenever a material should also be a source of radiosity light, as computed by CaLight. The radiant exitance is defined by ''$r'', ''$g'' and ''$b'', scaled by ''$scale''. |
| - | (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. | + | * **''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, but not yet implemented. |
| - | ''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. | + | * **''meta_sunlight ($r $g $b) ($x $y $z)''** This keyword states that the materials casts (radiosity) sunlight. The first three numbers define the irradiance of the sunlight in Watt/m^2 for the red, green and blue wavelengths. As the light actually comes from a very far away lightsource (the sun, moon, etc.), it is not cast by the materials itself, but rather //through// them, like sunlight shining through a window. The second triple of numbers specify the directional vector of the incoming light rays. The ''$z'' number should always be negative, so that the light appears to come from above. \\ In the file ''Games/DeathMatch/Materials/SkyDomes.cmat'' you can see exemplary use of this keyword. |
| - | 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. | + | * **''meta_alphaModulatesRadiosityLight''** Makes CaLight handle the ''diffusemap'' alpha channel and the $alpha and $rgba keywords properly. For fences, grates, glass, water, etc. Not yet implemented. |
| - | 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.1130091128.txt.gz · Last modified: 2013-01-07 12:07 (external edit)