Math Builtins

Nineteen unprefixed, HLSL-spelled call names are lowered directly to arithmetic UMaterialExpression nodes. They cover 16 operations — three of the names are aliases.

float s     = sin(X);
float sa    = saturate(X);
vec3  mixed = lerp(A, B, sa);
vec3  unit  = normalize(mixed);
float d     = dot(unit, A);

These are called bare — saturate(x), not UE.saturate(x) — and they are the one builtin surface whose arguments are positional. They may be written inside a Graph body, in an Outputs binding expression, or in an Outputs declaration initializer.

Every name is matched case-insensitively: SATURATE(x), Lerp(a, b, t) and Sin(x) all resolve.

Synopsis

{ abs | ceil | cos | floor | frac | fract | normalize | saturate | sin | sqrt } ( <x> )
{ dot | fmod | max | min | mod | pow } ( <x> , <y> )
{ clamp | lerp | mix } ( <x> , <y> , <z> )

Catalogue

One row per accepted spelling. Return width is the component count the generator assigns to the result; Authoritative is whether that width counts for the widening rules in Expressions and conversions.

Aliases

Three alias pairs. The two spellings in each pair are interchangeable and produce identical nodes — neither is deprecated.

Inside a Function HLSL body the identifier mod is rewritten to fmod by the GLSL-alias pass. In a Graph block both spellings are accepted directly, with no rewrite.

Argument rules

These apply identically to every builtin above.

Named arguments

Every arity guard is evaluated as "argument count is wrong or an argument is named", and both outcomes emit the arity message.

Name resolution

Math-builtin names are resolved before any user-declared name. The Graph call dispatcher tests, in order:

Per-builtin notes

clamp

clamp(Input, Min, Max) wires all three arguments and leaves the node's ClampMode at its default, CMODE_Clamp. For CMODE_ClampMin or CMODE_ClampMax, go through the generic form:

UE.Expression(Class = "Clamp", OutputType = "float1", Input = x, Min = a, ClampMode = "CMODE_ClampMin")

dot

The only builtin with a fixed return width. dot always produces a 1-component, authoritative result regardless of the argument widths, so float d = dot(A, B); needs no swizzle.

fmod, mod

Argument 1 is the dividend and argument 2 the divisor; they are wired to the node's A and B pins respectively. The result takes the dividend's width.

lerp, mix

The result width is max of arguments 1 and 2 — the Alpha argument does not participate. A scalar Alpha blending two vec3 values yields a vec3.

min, max

The two names share one implementation and differ only in the node class selected. Both take the max of the two argument widths.

normalize

The only builtin whose input pin is not named Input. Inputs on this path are bound by reflected property name, and UMaterialExpressionNormalize names its pin VectorInput. The difference is invisible at the call site — normalize(N) — but it does appear in the two could not bind input / failed to access input diagnostics.

sin, cos

Both leave the node's Period property at its default. For a non-default period:

UE.Expression(Class = "Sine", OutputType = "float1", Input = x, Period = 2.0)

Node reuse

Results are common-subexpression cached. Two textually identical calls over identical operand values — sin(X) written twice — produce one Sine node, not two. The cache key covers the builtin name, the node class and every argument value.

Math builtins share this behaviour with the generic UE.Expression path and the Substrate.* wrappers. The registered UE.* builtins are the exception: they create a fresh node per call.

Every math node is created at editor X coordinate 360, with Y taken from the generator's running layout counter.

What is not here

There is no matrix, inverse-trigonometric, exponential, logarithmic, step, smoothstep, reflect, refract, cross or length builtin on this surface. Two ways out:

• reach the UMaterialExpression directly, for example UE.Expression(Class = "CrossProduct", OutputType = "float3", A = u, B = v);
• write the operation in a Function HLSL body, where the full HLSL intrinsic set is available.

Inside a Function HLSL body these names are not handled by this dispatcher at all — the body is emitted verbatim and HLSL's own intrinsics apply.

Diagnostics

{Name} is the spelling as the author wrote it, so its casing is preserved. {Index} is 1-based.

The complete list lives in the diagnostics index.

Example

Shader(Name="Docs/M_MathBuiltins")
{
    Properties = {
        float X = 0.5;
        vec3  A = vec3(1.0, 0.0, 0.0);
        vec3  B = vec3(0.0, 1.0, 0.0);
    }
    Settings = { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs  = { vec3 Color; Base.EmissiveColor = Color; }
    Graph = {
        float s     = sin(X);
        float c     = cos(X);
        float cl    = clamp(X, 0.0, 1.0);
        float sa    = saturate(X);
        vec3  mixed = lerp(A, B, sa);
        vec3  unit  = normalize(mixed);
        float d     = dot(unit, A);
        Color = mixed * (s + c + cl) + unit * d;
    }
}

Generated nodes:

Sine(X)                       -> s
Cosine(X)                     -> c
Clamp(X, 0.0, 1.0)            -> cl
Saturate(X)                   -> sa
LinearInterpolate(A, B, sa)   -> mixed     (3 components: max(3, 3))
Normalize(mixed)              -> unit      (3 components)
DotProduct(unit, A)           -> d         (1 component, always)
Add / Multiply chain          -> Color

Where to next