HLSL Overview

HLSL is the shader language Unreal's material Custom nodes are written in. DreamShaderLang is not an HLSL compiler, but HLSL is not decorative here either: the body of a Function or GraphFunction is HLSL, emitted more or less verbatim into a generated include and compiled by Unreal.

This page is for readers arriving from HLSL. It says which HLSL knowledge transfers, which does not, and where the boundary sits.

Where HLSL runs, and where it does not

So: reach for HLSL when you want arithmetic the node graph makes tedious, and stay in Graph when you want engine inputs, parameters and bindings. The two meet at the function call.

// plain HLSL
float3 ApplyTint(float3 color, float3 tint)
{
    return color * tint;
}

// the DreamShaderLang declaration of the same helper
Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
    result = color * tint;
}

Both forms exist. A declared return type is legal and lowers to a single output, so Function float3 ApplyTint(in vec3 color, in vec3 tint) { return color * tint; } is the same helper written the HLSL way.

Types

DreamShaderLang has a closed set of type tokens. The HLSL spellings it accepts are these:

Two tokens exist that HLSL does not know at all: MaterialAttributes and StaticBool. They resolve for DreamShaderLang, but the token is emitted into the generated signature verbatim, so a Function using either produces a helper Unreal cannot compile. Use a ShaderFunction or a GraphFunction for that plumbing. The full validity matrix is on Types and Values.

Matrices

There are no matrix types. float2x2 / float3x3 / float4x4 — and therefore mat2 / mat3 / mat4, which normalize to them — are rejected by every declaration position. mat3 is nevertheless accepted lexically in a Function signature, because the signature normalizer rewrites it before validation runs; the declaration parses and the call fails:

Function float3 Rotate(in mat3 basis, in vec3 v) { return mul(basis, v); }
// parses; a call fails with:
//   DreamShader Function 'Rotate' input 'basis' uses unsupported type 'float3x3'.

Matrix-shaped work is reachable through the transform builtins — UE.TransformVector and UE.TransformPosition, on UE.* Nodes.

Signatures

An HLSL function signature and a Function signature look alike, but the rules differ in several places.

A function must produce something: at least one out parameter, or a return type. Neither gives Function '{Name}' must declare at least one out parameter.

Function float Luma(in vec3 color) {
    return dot(color, float3(0.299, 0.587, 0.114));      // one result, HLSL style
}

Function SplitChannels(in vec4 src, out vec3 rgb, out float alpha) {
    rgb   = src.rgb;                                      // two results, out style
    alpha = src.a;
}

Under a declared return type, every return at brace depth 0 is rewritten to an assignment to a synthetic __return variable. A bare return; at depth 0 is a hard error. A return nested inside an if { … } stays a real HLSL return — legal, but it bypasses __return.

Textures and samplers

A texture-typed in parameter gains a companion SamplerState <ParamName>Sampler immediately after it in the generated signature, and every call site passes the matching argument. Use that name to sample:

Function SampleTinted(in Texture2D tex, in vec2 uv, in vec3 tint, out vec3 rgb, out float alpha)
{
    float4 texel = Texture2DSample(tex, texSampler, uv);
    rgb   = texel.rgb * tint;
    alpha = texel.a;
}

SamplerState is not in the set that triggers this expansion. A parameter declared SamplerState S emits SamplerState S into the signature and receives a texture object at the call site.

Control flow

Inside a Function body, HLSL's own control flow applies in full — if, else, for, while, do, switch, break, continue, discard. The body is passed through, so what compiles in a Custom node compiles here.

Inside a Graph block the vocabulary is much smaller: if / else only, with a parenthesised condition and braced bodies. There are no loops.

Intrinsics

The Graph surface is abs, ceil, clamp, cos, dot, floor, fmod, frac, fract, lerp, max, min, mix, mod, normalize, pow, saturate, sin, sqrt. Notably absent: step, smoothstep, length, cross, reflect, refract, exp, log, and every inverse trigonometric function. Reach them through UE.Expression(Class = …), or write them in a Function body.

What happens to your body text

Every Function and GraphFunction body — and nothing else in the language — is passed through an identifier-level rewrite before it is stored. The scan is comment- and string-aware.

The full alias list, in both directions, is on GLSL Overview.

DreamShaderBuiltins.ush

The plugin ships one HLSL header of its own. It defines DS_* macros and functions that mirror the HLSL the material translator emits for the corresponding UE.* nodes.

#include "/Plugin/DreamShader/DreamShaderBuiltins.ush"

At module startup DreamShader registers a shader source directory mapping from the virtual directory /Plugin/DreamShader to the plugin's Shaders folder, unless a mapping for that virtual directory already exists. The mapping is unconditional — it does not depend on any project setting, backend choice or engine version — so the path above always resolves for the engine's shader preprocessor. It is a separate mapping from the one used for generated per-source helper includes.

Symbols

Parameters is the material parameter struct in scope at the include site; Tex is a texture parameter identifier, from which the sampler name is derived by token pasting (Tex##Sampler).

The WSDemote calls lower the engine's large-world-coordinate vectors to float3. The translated (camera-relative) position form is already float3 and keeps precision near the camera.

Using it safely

• The remaining reads are side-effect free. Every field and Get*(Parameters) helper they touch is populated unconditionally at pixel entry, so they compile in any opaque Surface pixel evaluation with no usage flag or interpolator request.
• DS_PerInstanceRandom and DS_PerInstanceFadeAmount are meaningful only for instanced or GPU-culled draws. On a plain mesh they read back safe constants (0 and 1) with no compile error.
• The include guard makes repeated inclusion in one translation unit harmless.
• The GLSL-alias rewrite skips string literals, so the path inside #include "…" is never touched.

Function vec2 Wobble(in vec2 uv, in float speed)
{
    #include "/Plugin/DreamShader/DreamShaderBuiltins.ush"
    float t = DS_TIME * speed;
    return uv + float2(sin(t), cos(t)) * 0.02;
}

The node-based equivalent needs no include and no HLSL helper at all:

GraphFunction vec2 Wobble(in vec2 uv, in float speed)
{
    float t = UE.Time() * speed;
    return uv + vec2(sin(t), cos(t)) * 0.02;
}

Common HLSL keywords

For reference — this is HLSL's own vocabulary, valid inside a Function body. The Also in DreamShaderLang column marks what the declaration grammar recognises outside a body.

Where to next