4.12.1.3 Shader Conditions and Processing Instructions Reference

General Syntax

Shader conditions and processing instructions are specified via XML processing instructions, that is <?...?>. Some instructions only consist of a single instruction, others consist of a pair and enclose a block of XML. All tags opened in such a block must be properly closed according to the node hierarchy, and all closing tags must be matched by an opening tag inside such a block.

In an instruction string, `<' can be replaced with `<' and `>' can be replaced with `>'.

Shader Processing Instructions

Shader processing instructions are evaluated at parse time; notably, a shader condition as described below does not influence whether a processing instruction is processed or not. In order to visually distinguish the parse-time evaluated processing instructions from the run-time evaluated conditions, all processing instructions start with an uppercase letter by convention.

Templates

Syntax for template definition:

<?Template [TemplateName] {ParameterName} {ParameterName} ...?>
{XML}
<?Endtemplate?>

Syntax for template invokation:

<?[TemplateName] {Parameter} {Parameter} ...?>

A template is available for invokation after the closing Endtemplate.

If a template is defined with a name of an already existing definition, the new definition overrides the old definition after the closing Endtemplate.

If a template definition is parsed. template invokations inside template definitions are immediately expanded. However, note that nested template definitions are not parsed unless the containing template is invoked. This means that nested template invokations are not immediately expanded.

Templates support parameters. Each parameter has a name, and placeholders in the template contents block are substituted with the parameter's values. A placeholder has the form `$Parameter$' or `$"Parameter$'. The first form substitutes the placeholders with the verbatim parameter value. The second form substitutes the placeholders with a "quoted" string: it is formatted such that it can be passed as a parameter to a template invokation, preserving contained spaces (see below). To specify a single dollar sign in the contents block use `$$'.

The parameter values specified in the template invokation are associated with the definition's parameter names by position. Parameter values are space-separated. To specify a parameter that contains spaces, the string must be surrounded by quotes. A quote character in such a quoted string is represented as `\"', a backslash character as `\\'.

Syntax for weak template definition:

<?TemplateWeak [TemplateName] {ParameterName} {ParameterName} ...?>
{XML}
<?Endtemplate?>

Weak templates behave the same way as "normal" templates, except in the case of a definition with the name as an already existing definition: the new definition is ignored.

Generators

Syntax for generation:

<?Generate [Variable] [Start] [End] {Step} ?>
{XML}
<?Endgenerate?>

`Generate' instructions let internally run an integer counter, starting at `Start', adding `Step' on each iteration, until the counter is greater (for a positive `Step') respectively smaller (for a negative `Step') than `End'. Each iteration replicates the contents block.

If `Step' is not specified, it defaults to 1 if `Start' <= `End' or to -1 if `Start' > `End'. `Step' = 0, `Step' > 0 and `Start' > `End', `Step' < 0 and `Start' <= `End' result in an error.

Certain placeholders in the contents block, in the same form as placeholders for a `Template' parameter with the name of `Variable' will be replaced with the counter value of an iteration.

(Semantically, using a `Generate' instruction is equivalent to defining a template with a single parameter named `Variable', with the same contents as the `Generate' instruction, and invoking it once for each value of the counter, iterating as described above.)

Inclusions

Syntax for inclusion:

<?Include [Filename] ?>

`Filename' is the VFS path to the file to be included. The file needs to be an XML file with a node include at the root. All contents of this include node will treated as if appearing in the including document at the point of the `Include' processing instruction. Shader processing instructions and shader conditions will be handled normally.

Static Conditions

Syntax for a symbol definition:

<?Define [Symbol] ?>

Syntax for a symbol undefinition:

<?Undef [Symbol] ?>

`Define' adds `Symbol' to a global symbol table. `Undef' removes `Symbol' from that table. The presence of a symbol in that table can be tested with the statements below.

Syntax for symbol testing:

<?SIfDef|SIfNDef [Symbol] ?>
{XML}
{<?SElsIfDef|SElsIfNDef [Symbol] ?>}
{XML}
{<?SElsIfDef|SElsIfNDef [Symbol] ?>}
{XML}
...
{<?SElse ?>}
{XML}
<?SEndIf ?>

`SIfDef' tests for the presence of a symbol in the global symbol table, `SIfNDef' for the absence. If the test succeeds, the contents of the block up to the next `SElsIfDef', `SElsIfNDef', `SElse' or `SEndIf' are used in the document. If the test does not succeed, the behaviour depends on the instruction that follows: if it is the `SEndIf', nothing will be used in the document. If it is the `SElse', the contents of the block from `SElse' to `SEndIf' will be used. If the next instruction is `SElsIfDef' or `SElsIfNDef', the `Symbol' specified there will be tested for presence or absence again; which block is used in the document depends on the result of the test and the following instruction in the same way as for `SIfDef' or `SIfNDef'.

Every `SIfDef' or `SIfNDef' is matched by one `SEndIf'. An `SElse' instruction is optional and must only be followed by the `SEndIf'.

Shader Conditions

Shader conditions are evaluated at run time. They can be treated as if re-evaluated every time a shader is used. In order to visually distinguish the run-time evaluated conditions from the parse-time evaluated processing instructions, all conditions start with a lowercase letter by convention.

Syntax for conditons:

<?if [Expression] ?>
{XML}
{<?elsif [Expression] ?>}
{XML}
{<?elsif [Expression] ?>}
{XML}
...
{<?else ?>}
{XML}
<?endif ?>

`if' tests whether `Expression' evaluates to the boolean value true. `Expression' not evaluating to a boolean value results in an error. (Expressions can evaluate to different types, see below.) If the test succeeds, the contents of the block up to the next `elsif', `else', or `endif' are used in the document. If the test does not succeed, the behaviour depends on the instruction that follows: if it is the `endif', nothing will be used in the shader. If it is the `else', the contents of the block from `else' to `endif' will be used. If the next instruction is `elsif', the `Expression' specified there will be evaluated and tested the same way as it would for an `if'; which block is used in the document depends on the result of the test and the following instruction in the same way as for `if'.

Every `ifdef' is matched by one `endif'. An `else' instruction is optional and must only be followed by the `endif'.

Expression Syntax

      expr ::= (expr) | expr op expr | '!' expr | identifier | number
        op ::= '||' | '&&' | '==' | '!=' | '<' | '>' | '<=' | '>='
identifier ::= ident-string | ident-string '.' identifier

`ident-string' can be an arbitrary character string. To specify a string with spaces double quotes must be put around the string.

`number' can be an integer or float number.

Expression Operators

Lower priority means higher precedence.

Both operands must have types compatible to each others. The type `boolean' is only compatible to `boolean' itself. `integer', `float' are compatible to each other. If one operand is a `float' but the other is not, this other operand gets converted to `float' before evaluation of the operation.

Expression Identifiers

`identifier' identifies a built-in constant or shader variable.

Identifiers are build of names separated by dots, forming a hierarchy. The leftmost name is the top-level name. Subsequent names are also called "members" of the name left of them.

Top-level names are:

consts

Constants. Available members are the boolean constants `true' and `false', as well as integer constants consisting of the enumerants of the csLightType enum, the csLightAttenuationMode enum and the csFogMode enum.

vars

Shader variables. Members are all possible names of shader variables. Each such member will evaluate to a boolean value, which is true if a shader variable of the specified name exists in the set of shader variables used for rendering, or false if not.

Furthermore, shader variable names have members themselves:

int

The integer value of the shader variable, or 0 if the variable doesn't exist.

float

The float value of the shader variable, or 0.0 if the variable doesn't exist.

x

The `x' component of the vector value of the shader variable, or 0.0 the variable doesn't exist.

y

The `y' component of the vector value of the shader variable, or 0.0 the variable doesn't exist.

z

The `z' component of the vector value of the shader variable, or 0.0 the variable doesn't exist.

w

The `w' component of the vector value of the shader variable, or 0.0 the variable doesn't exist.

buffer

A boolean value indicating whether the variable contains a buffer, or false if the variable doesn't exist.

texture

A boolean value indicating whether the variable contains a buffer, or false if the variable doesn't exist.

This document was generated using texi2html 1.76.