Calls

Anything in a Graph body written as Name(...) is a call. Six declaration kinds and two kinds of parameter are callable, plus the builtins and constructors that are resolved first. Which form a call may take, whether it can be used as a value, and whether it accepts named arguments all depend on the kind of thing being called.

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>

Callable kinds

UE.*, Substrate.*, math builtins, constructors and SampleTexture2D also use call syntax, but they are resolved before any of the kinds above. See UE.* Nodes and Math Builtins.

Dispatch order

A call name is probed strictly in this order. The first surface that claims the name wins; later surfaces are never consulted.

Step 5 has one subtlety: the math-builtin handler distinguishes "this is not a math builtin" from "this is one and the call is malformed". Only the second aborts, so clamp(x) reports Math function 'clamp' expects exactly 3 arguments. rather than falling through to a user function.

At step 9, if more than one declaration kind matches, the call fails with Graph call '{Name}' is ambiguous because multiple definitions use that name: {Kinds}. When exactly one matched, dispatch precedence is material function → VirtualFunction → GraphFunction, with Function reached through step 10.

Callee spellings

There is no overload resolution. Names are not distinguished by argument count or type; the first declaration whose name matches wins.

Value form

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

A call result is an ordinary postfix expression, so it can be swizzled directly: SampleTexture2D(Albedo, uv).rgb.

Statement form

F_PulseTint(BaseColor, Tint, TintedColor, PulseAmount);

Multi-output ShaderFunction / VirtualFunction statement calls are available since 1.3.5.

Arguments are inputs first, then one out target per output, in declaration order. Every declared output must receive a target — there is no way to discard one.

Out-target rules

An out target does not need to exist beforehand and does not need to be declared. Each target is bound in the current scope to the call's output with that output's declared shape, replacing any previous value of that name without a type check. Declare the variable first if a specific width matters.

Arguments

Positional and named

Argument names are normalised before comparison: trimmed, then lower-cased. Coordinates=, coordinates= and COORDINATES = are the same argument. Positional arguments are indexed among the unnamed arguments only, so a positional index skips over any named argument that precedes it.

The no-mixing rule is per call, not per argument: if any argument is named, no positional argument may appear. A named argument matching no declared input fails with {Kind} '{Name}' does not have an input named '{Argument}'.; too many positional arguments fail with {Kind} '{Name}' received {Got} positional input argument(s), but only {Declared} input(s) are declared.

Every input argument is coerced to the input's declared type, with the usual silent narrowing — see Conversions.

default

since 1.2.3 default is a bare identifier, matched case-insensitively, that explicitly requests an optional input's declared default instead of supplying a value.

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

float3 tinted = F_Tint(BaseColor, default, Output="OutColor");

Output selection

Output, OutputName and OutputIndex are reserved named arguments on the value form of ShaderFunction, ShaderLayer, ShaderLayerBlend and VirtualFunction calls. They are removed from the input argument list before inputs are bound.

float value = F_MultiOutput(Input=Mask, Output="Height");
float other = F_MultiOutput(Input=Mask, OutputIndex=1);

UE.Expression(…) accepts the same three selectors with the same rules; see UE.Expression.

BreakOutFloatNComponents

A VirtualFunction call whose declared name is BreakOutFloat2Components, BreakOutFloat3Components or BreakOutFloat4Components (case-insensitive) is inlined as a swizzle instead of generating a MaterialFunctionCall node, provided it has a usable first input argument and an output selector:

OutputIndex= selects the same channel by index. If any precondition is unmet — a default first argument, both selectors given, no selector at all — the call falls through to the ordinary MaterialFunctionCall path.

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 call materialises the parameter node exactly as a bare reference does and connects each named argument to the input pin of the same name. The node is cached under the parameter's name, so a later bare reference shares the configured node.

The complete list of parameter node types that accept this form:

Pin names use the same normalisation as argument names. Every argument must be named, and every value must be numeric.

Properties = {
    TextureSampleParameter2D Albedo = Path(Game, "Textures/T_Albedo");
}

Graph = {
    vec2 UV  = UE.TexCoord(Index = 0);
    vec4 Tex = Albedo(Coordinates = UV);
}

StaticSwitchParameter

since 1.2.3 A StaticSwitchParameter property does not resolve as a bare identifier — it needs its two branches, so it is readable only through the call form.

Both branches must be present, must not be texture objects or Substrate values, must agree on the MaterialAttributes flag, and must have the same component count.

Properties = {
    StaticSwitchParameter UseDetail = true [
        Group="Switches";
        SortPriority=30;
    ];
}

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

Because the switch is resolved at shader-permutation time rather than per pixel, this is the cheap alternative to an if when the choice is a material setting rather than a computed value.

Recursion and nesting

Which calls are reused

Because positional arguments are keyed by index, F_Tint(a, b) and F_Tint(b, a) are different keys; because argument names are normalised, F_Tint(Color = a) and F_Tint(color = a) are the same. If any argument produces no key token, the whole call is not cached and the node is always created.

Diagnostics

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

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.
        vec4 Tex = Albedo(Coordinates = UV);

        // Value form, single-output Function declared in Helpers.dsh.
        float L  = Luma(Tex.rgb);

        // Value form, namespaced Function.
        vec3 Lit = Common::ApplyTint(Tex.rgb, Tint);

        // Statement form: two out targets, inputs first. The targets need no declaration.
        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;
    }
}

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

The two additional output pins on the PulseTint Custom node are named after the caller's out variables, not after the declared result names.

See also

• Functions — declaring Function, GraphFunction and Namespace
• Imports and Namespaces — where :: names come from
• Property Types — which parameters own input pins
• Statements — the statement-form call as a statement
• Expressions and Conversions — how a call fits into the expression grammar
• UE.Expression — the generic node builtin and its output selectors