Math Builtins

Twenty-nine unprefixed, HLSL-spelled call names are lowered directly to arithmetic UMaterialExpression nodes. They cover 26 operations — three of the names are aliases. Each call produces one node, with two exceptions: reflect and refract, which Unreal has no expression for, expand into a small subgraph.

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 | acos | asin | atan | ceil | cos | floor | frac | fract | length
| normalize | saturate | sin | sqrt } ( <x> )
{ atan2 | cross | dot | fmod | max | min | mod | pow | reflect | step } ( <x> , <y> )
{ clamp | lerp | mix | refract | smoothstep } ( <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)

step

step(edge, x) returns x >= edge ? 1 : 0, as in HLSL. UMaterialExpressionStep names its pins the other way round — Y is the edge and X is the value — so argument 1 wires to Y and argument 2 to X. Writing the node form by hand, the equivalent call is:

UE.Expression(Class = "Step", OutputType = "float1", Y = edge, X = x)

smoothstep

smoothstep(min, max, x), argument order as in HLSL, wired straight to the node's Min, Max and Value pins.

length, cross

The two builtins besides dot with a fixed return width: length is always 1 component and cross always 3, whatever the arguments were. Both widths are authoritative, and they match what the same classes already report when reached through UE.Expression.

asin, acos, atan, atan2

The four inverse-trigonometric nodes. atan2(y, x) takes its arguments in HLSL order and the node's pins are already named Y and X, so the mapping is direct.

reflect, refract

The only two builtins with no node behind them. Unreal has no Reflect or Refract UMaterialExpression, so both are lowered to the arithmetic HLSL defines them as, and the value returned to the caller is the final node of that subgraph.

reflect(i, n) becomes i - 2 * dot(i, n) * n — four nodes (DotProduct, two Multiply, Subtract). The literal 2 rides Multiply's ConstB rather than costing a Constant node.

refract(i, n, eta) becomes the full HLSL definition — fourteen nodes:

k = 1 - eta*eta * (1 - dot(n, i)^2)
k < 0 ? 0 : eta*i - (eta*dot(n, i) + sqrt(k)) * n

The total-internal-reflection test is an If node, so both sides are translated and one is selected; sqrt of a negative k lands only on the discarded side, exactly as in HLSL. k == 0 still satisfies the formula (sqrt(0) == 0) and takes the refracted side. The zero branch is built as i * 0 rather than a constant so that its type always equals i's — If requires its two branches to agree, and the tracked component count cannot always guarantee a hand-picked constant would.

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

Matrices are not here, and are not addable. The Unreal material graph has no matrix value type at all, so mul(M, v) has no Graph spelling regardless of what the DSL does. Space conversions go through UE.Expression(Class = "Transform") or "TransformPosition"; everything else goes in a Function HLSL body.

Still absent but reachable through UE.Expression, each having a node: exponential, logarithmic, tan, sign, round, trunc and distance. For example:

UE.Expression(Class = "Distance", OutputType = "float1", A = u, B = v)

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