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 [2007-05-27 12:44] Carsten Updated the clip flags description. |
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 94: | Line 94: | ||
| * **''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. | * **''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 101: | 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 $turnoff''** This is very similar to ''ambientMask'', but it only affects the per-lightsource passes. This keyword is currently not used in any Ca3DE material. | + | * **''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. |
| Line 108: | Line 108: | ||
| There are also keywords that define other aspects of the material that are not directly related to their rendering. | There are also keywords that define other aspects of the material that are not directly related to their rendering. | ||
| - | * **''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 CaLight and others perform ray trace tests that in turn are affected by this keyword. \\ ''$c1, $c2, ...'' must be a comma-separated list of at least one of these flags: ''nothing'', ''players'', ''monsters'', ''moveables'', ''ik'', ''radiance'', ''sight'', or ''all''. The default value (i.e. if you do not use this keyword at all), is ''clip all''. When you use it, the value is first cleared and then additively rebuilt from the parameter list. \\ :!: Note that each Ca3DE map file must entirely be sealed by materials with the ''clip all'' property, or else the map has a leak. \\ Here is an explanation of the individual flags: ( FIXME Several of them not yet implemented...) | + | * **''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. | * ''nothing'' means that a surface with this material clips against nothing, it is non-solid. | ||
| - | * ''players'' means that the surface is solid to players, | + | * ''players'' means that the surface is solid to players. |
| - | * ''monsters'' means that the surface is solid to monsters (AI entities), | + | * ''monsters'' means that the surface is solid to monsters (AI entities). |
| - | * ''moveables'' means that the surface is solid to moveable entities, | + | * ''moveables'' means that the surface is solid to moveable entities. |
| - | * ''ik'' means that the surface is solid to IK, | + | * ''ik'' means that the surface is solid to IK. |
| - | * ''projectiles'' means that the surface is solid to the projectiles of weapons, | + | * ''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), | + | * ''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. | + | * ''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), | + | * ''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. | + | * ''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). | ||
| * **''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. | * **''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. | ||
| Line 125: | Line 126: | ||
| ===== Meta Keywords ===== | ===== 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 Cafu map compile tools. |
| These parameters are not directly related to the rendering of the material. | These parameters are not directly related to the rendering of the material. | ||
matsys/cmat_manual/keywordreference.1180262641.txt.gz · Last modified: 2013-01-07 12:07 (external edit)