Calls

DreamShader » Graph » Calls

Invoking a Function, GraphFunction, ShaderFunction, VirtualFunction or an input-bearing parameter from a Graph block, either as a value expression or as a standalone statement.

A .dsm / .dsf is read by the legacy front end and bound by the 2.0 binder (since 2.0.0). The call spellings on this page build the same nodes they did; where a 1.x call reads differently from a .dss call, a numbered legacy rule applies and says so with its own code. The .dss spelling of each is in dsc migrate.

Synopsis

// value form — the call produces a value
<target> = <callee> ( [ <argument> [ , <argument> ] … ] ) ;

// statement form — the call writes into named out variables
<callee> ( [ <input-argument> , ] … <out-target> [ , <out-target> ] … ) ;

<callee>         := <identifier> | <namespace> :: <identifier>
<argument>       := <expression> | <identifier> = <expression> | default
<out-target>     := <identifier>

( ) , = :: and default are literal DreamShaderLang text. [ … ], { a | b } and … are meta-notation. A positional argument after a named one is DSH2158, in every call (since 2.0.0).

Callable kinds

A ShaderFunction of another file is reached through a VirtualFunction naming its asset: an import brings in a .dsh header only, and a header holds no asset blocks.

UE.*, Substrate.*, math builtins, constructors and SampleTexture2D are also call syntax, but they are resolved before any of the kinds above and are documented separately — see Builtins, Math builtins and Constructors. A function named like a math builtin is DSH6206 (since 2.0.0). The complete dispatch order is in Name resolution.

Callee spellings

There is no overloading. One name declares one thing: a second function, property or struct of a name already declared is DSH4210. The exception is a ShaderFunction block whose leaf name is taken by a function declared before it — typically one from an imported header: the block's function is declared as <Name>_Asset instead, and the asset keeps its name (info DSH5290). Two names that differ only in case are two declarations; a call spelled like neither then has no unique case-insensitive match and is DSH4208.

Value form

float L = Luma(BaseColor);
vec3  C = Common::ApplyTint(BaseColor, Tint);
vec3  N = F_Normal(uv, Output="Normal");

(single-output Function / GraphFunction value calls since 1.3.1)

A GraphFunction call is one Custom node, like a Function call; the UE. calls lifted out of its body become further inputs of that node, lowered with this call's arguments.

Calls with the same callee and the same arguments are one node; see Node reuse.

Statement form

F_PulseTint(BaseColor, Tint, TintedColor, PulseAmount);

(multi-output ShaderFunction / VirtualFunction statement calls since 1.3.5)

A statement that is a call may call anything. A call whose value nothing receives — a builtin, a constructor, a parameter — is accepted, and the node it makes is dropped because nothing reads it (since 2.0.0; 1.x refused such a statement). A statement that is an expression but neither a call nor an assignment is DSH2211 (F(a).Out;, x;); x++; is DSH2207 and break; DSH2208.

How the arguments of a statement call to a function are read:

In the first reading an input not covered must be declared opt or passed default, otherwise DSH4217. Every declared output must receive a target — there is no way to discard one.

Out-target rules

[!NOTE] An out target spelled in another case than a declaration is that declaration, with DSH5275 — not a second variable (since 2.0.0). A name only becomes a new local when nothing is declared under it in any case.

Arguments

Positional and named

Positional arguments come first and named ones after them; the reverse is DSH2158. A parameter given twice — by position and by name, or by name twice — is DSH4215. In a statement call, a named argument switches off the receivers-last reading (see Statement form).

Parameter names are compared exactly, with the DSH5275 fallback above; a pin of a node matches in another case with the warning DSH5276. The names the 1.x front end reads itself — Output, OutputName, OutputIndex, True, False, A, B — are matched ignoring case.

default

(since 1.2.3)

default is a bare identifier that holds the place of an input left out on purpose (legacy rule L25). It is matched case-sensitively (since 2.0.0), and only while no variable of that name is declared.

Omitting a trailing optional input entirely has the same effect as passing default.

Output selection

Output, OutputName and OutputIndex are named arguments the 1.x front end reads itself: it removes them from the call and selects the output instead, as .Name or [k] written after the call. They work on a call of any function kind (since 2.0.0 for Function and GraphFunction) and on UE.* calls.

[!WARNING] A selector makes the call a value. It cannot stand in a statement call: the selected call is an expression nothing receives, which is DSH2211.

UE.Expression(…) accepts the same three selectors; a name the node does not have is DSH5201, an index past its outputs DSH5282. See UE.Expression.

BreakOutFloatNComponents

A call named BreakOutFloat2Components, BreakOutFloat3Components or BreakOutFloat4Components (any case) whose first argument is positional and which carries an output selector is read as a swizzle of that first argument. No MaterialFunctionCall node is made, and no function of that name is looked up (since 2.0.0). The selected output names a channel, its letter in any case:

OutputIndex= selects the same channel by index. The channel has to lie inside the width the name says (0–1 for BreakOutFloat2Components). Otherwise — no selector, a named first argument, a channel past the width — the call is an ordinary call of the function of that name. Both selectors at once are DSH5252.

Calling a parameter

Input-pin wiring

(since 1.4.1)

A declared parameter whose node owns input pins may be "called" to wire those pins. The front end writes each use of such a property — a call or a bare read — as its own UE.Expression(Class = "<type>", ParameterName = "<name>", …) call, with the declaration's default and metadata as arguments and the call's arguments on the pins (since 2.0.0). Uses with the same arguments are one node after the dedupe pass; a bare read and a pin call carry different arguments, so they are two nodes that address the same material parameter. A texture-sample parameter is read through its RGBA output.

Complete list of parameter node types that accept this form:

Pin names are the node's own, as the engine catalog lists them; another case resolves with DSH5276. Every argument must be named (DSH5259), and each value is checked against its pin like any UE. argument (DSH5214).

[!NOTE] Asset slots — the texture, curve or font a sampler parameter points at — are set with [TextureSlot=Path(…)]-style declaration metadata, which becomes a property argument of the node. A call argument that names a property the declaration already sets is DSH4215. A name that is neither a pin nor a property of the node is DSH5213; when its value is a graph value it is the info DSH5291 instead, and the pin is connected by that name once the node exists (DSH8212 if the node shows no such pin).

StaticSwitchParameter

(since 1.2.3)

A StaticSwitchParameter property does not resolve as a bare identifier (DSH4200); it is readable only through the call form, which supplies the two branches.

Both branches must be present (DSH5258); any other argument is dropped with the warning DSH5254. The call becomes a UE.Expression(Class = "StaticSwitchParameter", …) with the branches on its A and B pins, which are checked like the pins of any UE. node (since 2.0.0).

vec3 Albedo = UseDetail(True = DetailColor, False = BaseColor);

Recursion and nesting

Diagnostics

Every diagnostic has a stable code; the code's page has the message and what to do. Messages are reported as <file>(<line>,<col>): DSHnnnn: <message>, at the call or argument they are about.

Resolution and dispatch

Arguments and out targets

Output selection

Function

GraphFunction

Everything under Function, and:

A lifted call is bound like any other expression, so a mistake inside it is reported with that expression's own code.

ShaderFunction family and VirtualFunction

Parameter call forms

Example

import "Helpers.dsh";

Shader(Name="Docs/M_Calls")
{
    Properties {
        vec3                   Tint    = vec3(1.0, 0.4, 0.1);
        TextureSampleParameter2D Albedo = Path(Game, "Textures/T_Albedo");
        StaticSwitchParameter  UseTint = true;
    }

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

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

    Graph {
        vec2 UV  = UE.TexCoord(Index = 0);

        // Parameter pin call: wires the sampler's Coordinates pin, read through RGBA.
        vec4 Tex = Albedo(Coordinates = UV);

        // Value form, Function with a return value, declared in Helpers.dsh.
        float L  = Luma(Tex.rgb);

        // Value form, namespaced Function: the value is its first out parameter.
        vec3 Lit = Common::ApplyTint(Tex.rgb, Tint);

        // Statement form: inputs first, then one out target per output. Neither target is
        // declared, so each becomes a local of its output's type (info DSH5283).
        PulseTint(Lit, Tint, Pulsed, Amount);

        // StaticSwitchParameter call selects between the two.
        Color = UseTint(True = Pulsed, False = vec3(L, L, L));
    }
}

Helpers.dsh:

Function float Luma(in vec3 color) { return dot(color, float3(0.299, 0.587, 0.114)); }

Function PulseTint(in vec3 color, in vec3 tint, out vec3 result, out float amount) {
    amount = 0.5 + 0.5 * sin(color.r * 6.28318);
    result = color * tint * amount;
}

Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

Generated nodes:

TextureCoordinate                      -> UV
TextureSampleParameter2D  Albedo       -> Tex          (Coordinates pin wired to UV)
Custom  "Luma"                         -> L
Custom  "Common::ApplyTint"            -> Lit
Custom  "PulseTint"                    -> Pulsed (output result), Amount (output amount)
AppendVector, AppendVector             -> vec3(L, L, L)
StaticSwitchParameter  UseTint         -> Color

The PulseTint Custom node's outputs are named after the function's out parameters — result is output 0 and amount an additional output — (since 2.0.0; 1.x named the additional outputs after the caller's variables).

See also

• Name resolution — the full dispatch order and the shadowing rules
• Statements — the statement forms, including the standalone call statement
• Expressions — how a call fits into the expression grammar
• Function — declaring Function, Inline / SelfContained, return types
• GraphFunction — the UE.* hoisting rule and its restrictions
• ShaderFunction — the reusable material-function block
• ShaderLayer / ShaderLayerBlend — layer function blocks and arity
• VirtualFunction — declaring an existing UMaterialFunction
• Namespace — :: qualified names and the no-nesting rule
• Inputs / Outputs / Results — in / out / opt and declared defaults
• Parameters in Graph — reading parameters and the pin call form
• UE.Expression — the generic node builtin and its output selectors
• Node reuse — which call nodes are deduplicated
• dsc migrate — the .dss spelling of every legacy rule on this page
• Diagnostics index — every code, by stage