Statements

DreamShader » Graph » Statements

The complete set of statement forms a Graph body may contain, the rules that terminate them, and how the parser decides which form a given statement is.

Synopsis

graph-statement :=
      <type> <name> [ = <expression> ] ;                          // declaration
    | <type> <name> [ = <init> ] , <name> [ = <init> ] … ;        // comma declarators
    | <type> <name> = { <expression> , … } ;                      // brace initializer
    | <name> = <expression> ;                                     // assignment
    | <name> . <member> = <expression> ;                          // member write
    | <call-expression> ;                                         // statement-form call
    | if ( <condition> ) { <graph-statement> … }
      [ else { <graph-statement> … } | else if ( … ) { … } … ]

Form table

Form 8 expands to one variable per declarator; all of them share the type token of the first declarator, and each reports its own source line and column.

Termination and splitting

A Graph body is read by the 2.0 statement parser, token by token (since 2.0.0); it is no longer split as text at ;.

Graph = {
    float a = 1.0;;;             // the empty statements are dropped
    if (a > 0.5) { a = 0.0; }    // no ; after the }
    float b = a * 2.0;           // the final statement needs its ; (DSH2154 without it)
}

A statement that fails to parse is skipped up to the next ; at its own nesting level, and the parser carries on with the next statement; every error of the body is reported in one build.

Classification order

The parser decides a statement's form from its first tokens. The first rule that matches wins.

[!WARNING] Keywords are case-sensitive. If (x) { … } is not an if statement: If is a name, If (x) a call, and the { where the call statement's ; belongs is DSH2154. See Unsupported constructs.

[!NOTE] A declared name is one identifier. float3 A.B = x; is DSH2154 at the . (since 2.0.0); 1.x declared a variable literally named A.B. Member writes have no type in front: Attrs.BaseColor = x;.

Assignment

Forms 4 and 6. The target is a name or name.member; anything else — a swizzle of a member, an index, a call — is DSH2206.

<target> = <expression> ;

The target is resolved in this order:

A name is looked up exactly first, then ignoring case; a unique match in another case is taken with the warning DSH5275. See Name resolution.

Rule 4 means an undeclared name on the left of = is not an error:

Graph = {
    vec3 Boost = Tint * 2.0;
    Scratch    = Boost;      // DSH5292: declares 'Scratch' as a float3
    Color      = Scratch;    // 'Color' is an Outputs declaration -> converted to its type
}

The conversion at rule 2 takes the leading components of a wider value, with the info DSH5289 (legacy rule L22), and spreads a scalar across a wider target. It never widens a 2-component value to 3: that, and any other value that does not fit, is DSH4228. See Conversions.

Brace-initializer assignment

A brace list is read only as the initializer of a declaration. On the right of an assignment or a member write it is DSH2162 (since 2.0.0); write the constructor instead: Color = float3(r, g, b);. The declaration form and its rules are on Declarations; the constructor rules are on Constructors.

Expression statements

Form 9. A statement that is neither a declaration nor an assignment must be a call; any other expression is DSH2211.

In statement form a function's outputs are received by the trailing arguments, one plain variable name per output, in declaration order. Full argument rules, out-target constraints and the value-call form are on Calls.

Statement-form multi-output ShaderFunction / VirtualFunction calls are available (since 1.3.5); single-output Function / GraphFunction value calls (since 1.3.1).

Synthesized statements

Every Outputs declaration of a Shader becomes a variable declared at the top of the material's body, before the first statement of the Graph (since 2.0.0). It is initialized with its own initializer when it has one, and otherwise with a zero of its type (an empty attribute set for MaterialAttributes); a texture or Substrate output without an initializer starts without a value. These declarations carry the position of the Outputs line they came from.

A top-level Graph declaration of an output's name (same case) does not declare a second variable: with an initializer it becomes an assignment to the output, and without one it is dropped.

A Shader whose Outputs section declares or binds anything needs no Graph section; one with neither is DSH2255. See Shader.

Diagnostics

Every diagnostic is reported as <file>(<line>,<column>): DSHnnnn: <message>, at the construct itself, including inside an if body.

Parse time

Bind and build time

The complete cross-stage list lives in the diagnostics index.

Example

Every accepted statement form in one body:

ShaderFunction(Name="Functions/F_AllForms")
{
    Properties = { vec3 Tint = vec3(1.0, 0.4, 0.1); float K = 2.0; }
    Inputs     = { vec2 UV; }
    Outputs    = { MaterialAttributes Attrs; vec3 Debug; }

    Graph = {
        MaterialAttributes Attrs;              //    names the output: no second variable
        float3 c;                              // 1  declaration, no initializer
        float3 scaled = Tint * K;              // 2  declaration + expression
        vec4   packed = {scaled, 1.0};         // 3  declaration + brace initializer
        c = packed.rgb;                        // 4  assignment
        Debug = float3(0.0, 0.0, 0.0);         //    (form 5 is refused: write the constructor)
        Attrs.BaseColor = c;                   // 6  member write
        Attrs.Roughness = 0.35;                //    (form 7 is refused: write the value)
        float a = 1, b, d = 3;                 // 8  comma declarators

        if (K > 1.0) {                         // 10 if / else
            Debug = c * a;
        } else {
            Debug = c * b;
        }
    }
}

See also

• Graph — the evaluation model and the section grammar
• Declarations — type tokens, defaults, comma declarators, brace initializers, scope
• Expressions — operators, precedence, associativity
• if / else — the condition, the truth table, branch merging
• Calls — value-form and statement-form calls, out targets, named arguments
• MaterialAttributes — member reads and writes
• Conversions — what "converted to the declared type" does
• Name resolution — how a bare identifier is looked up
• Unsupported constructs — for, while, return, +=, ternary, and their codes
• Node reuse — why two identical statements can produce one node
• Output bindings — Outputs declarations and their initializers
• Diagnostics index — every code, by stage