Name resolution

DreamShader » Graph » Name resolution

How a bare identifier and a call target are looked up inside a Graph block, in the fixed order the compiler tries them, and what each surface shadows.

A name is looked up in two stages (since 2.0.0). The legacy front end reads a few 1.x spellings while it parses — the boolean literals, type names, N::F, the 1.x call shorthands and the properties that become nodes — and the 2.0 binder resolves everything else, the same way it does for a .dss. The binder compares names case-sensitively; a 1.x source still builds when a name matches only in another case, through legacy rule L19, which says so with a warning.

Synopsis

Two distinct ladders exist. Which one runs depends purely on whether the name is followed by (.

<identifier>                 // bare-identifier ladder
<identifier> ( … )           // call-name ladder
<identifier> :: <identifier> ( … )   // call-name ladder, qualified callee

Common::ApplyTint is read as the single identifier Common_ApplyTint, the name a namespaced function is declared under. UE.TexCoord and Substrate.Slab are node calls. A callee that is none of these — a call on a parenthesized expression, say — is DSH4208.

Bare identifiers

Steps 1–3 run before any variable is known, so they win over a variable of the same name. A property read at step 6 is the parameter node each time; equal nodes are one node after the dedupe pass. Step 7 needs a unique match: when two declarations match ignoring case, neither is chosen and the name is DSH4200.

[!NOTE] A StaticSwitchParameter property deliberately does not resolve as a bare identifier — it needs its two branches. Reading one by name fails with DSH4200. Use the call form Switch(True = …, False = …); see Calls.

Call names

Probed strictly in this order. The first surface that claims the name wins; later surfaces are never consulted.

The binder compares the UE in front of a node exactly (since 2.0.0): ue.TexCoord() reads ue as an undeclared name, DSH4200.

A builtin claims its name outright. A malformed clamp(x) is the builtin's arity error, DSH4224; there is no user function of that name to fall through to, because declaring one is DSH6206.

There is no ambiguity to resolve at step 11: one name declares one thing, and the second declaration of a name is DSH4210 where it is declared (since 2.0.0).

How each declaration kind is matched

The generated HLSL symbol DreamShaderFn_<name> is no longer a name a call can use (since 2.0.0).

There is no overload resolution: names are not scoped by arity or by parameter type. An imported header is declared into the file, not pasted into it as text, and a name it declares may not be declared again: DSH4210 names both files. Names are compared case-sensitively here too, so Foo and foo are two functions (since 2.0.0; 1.x reported them as declared twice), and N::F and a function named N_F are one name, DSH4210.

Namespaced functions are reachable only by N::F or by its reading N_F. There is no using-style import and no unqualified fallback.

Shadowing

Because the ladders are strictly ordered, "shadowing" always runs one way: an earlier surface hides a later one, never the reverse.

[!WARNING] Shadowing a constructor is silent. Function vec3(in float x, out float3 r) parses, is declared, and is simply never invoked from a Graph block — every vec3(…) call builds a constructor. Rename the function.

Identifier case

[!NOTE] A name written in another case than its declaration is that declaration, with DSH5275. float3 Color = …; followed by color = …; writes Color (since 2.0.0; 1.x created a second entry named color). Only a name that matches nothing in any case is declared by an assignment (legacy rule L26, info DSH5292). dsc migrate respells every such name the way it is declared.

Named-argument matching

Argument names are compared exactly. A function's parameter names fall back to a unique case-insensitive match with DSH5275, a node's pin and property names with DSH5276; a builtin's argument names have no fallback. The 1.x pseudo-arguments listed above are matched ignoring case. Positional arguments come first and fill the parameters in order; a positional argument after a named one is DSH2158 (since 2.0.0).

Which callees accept named arguments at all is documented in Calls.

Diagnostics

Example

import "Helpers.dsh";

Shader(Name="Docs/M_Resolution")
{
    Properties {
        vec3                  Tint    = vec3(1.0, 0.5, 0.2);
        StaticSwitchParameter UseTint = true;
    }

    Settings { Domain = "UI"; ShadingModel = "Unlit"; }

    Outputs {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph {
        // 'Tint' is the file-scope property: a VectorParameter node.
        vec3 Base1 = Tint;

        // 'TINT' matches 'Tint' only ignoring case: the same parameter, warning DSH5275.
        vec3 Base2 = TINT;

        // 'lerp' is the builtin; a function of that name in Helpers.dsh would be DSH6206.
        vec3 Mixed = lerp(Base1, Base2, 0.5);

        // A namespaced Function needs its full name.
        vec3 Lit = Common::ApplyTint(Mixed, Tint);

        // 'UseTint' is a StaticSwitchParameter: callable, not readable.
        Color = UseTint(True = Lit, False = Mixed);
    }
}

Resolution trace:

Tint                  -> bare 6   file-scope property               -> VectorParameter node
TINT                  -> bare 7   'Tint', ignoring case (DSH5275)   -> the same node
lerp(...)             -> call 9   math builtin                      -> LinearInterpolate node
Common::ApplyTint(..) -> call 3   read as Common_ApplyTint
                         call 11  Function (namespaced)             -> Custom node
UseTint(True=,False=) -> call 4   StaticSwitchParameter             -> StaticSwitchParameter node
UseTint               -> (bare read) ERROR: DSH4200

See also

• Calls — the call forms each surface accepts, and every call diagnostic
• Expressions — where identifiers and callees appear in the grammar
• Declarations — how a Graph variable is declared
• Constructors — the reserved constructor spellings
• Math builtins — the reserved builtin spellings
• UE builtins — the UE.* surface claimed by prefix
• Substrate builtins — the Substrate.* surface
• Parameters in Graph — reading parameters and the pin call form
• Namespace — declaring Namespace::Name and the no-nesting rule
• Lexical elements — the full case-sensitivity matrix for the declaration grammar
• Node reuse — how equal nodes are merged
• dsc migrate — the .dss spelling of every legacy rule on this page