HLSL Overview

HLSL is the shading language Unreal's material Custom node speaks. DreamShaderLang is not an HLSL compiler, but HLSL is not decoration here either: the body of a /// @custom function in a .dss, and of a 1.x Function / GraphFunction, is HLSL, written almost verbatim into the generated Custom node and compiled by Unreal. The rest of a .dss looks like HLSL but is lowered to a material node graph.

This page is for readers arriving from HLSL: which habits carry over, which do not, and where the line is.

Where HLSL runs, and where it does not

since 2.0.0 An HLSL body is written into the Custom node's own code; the other functions it calls are embedded as DreamShaderFn_* members of a generated wrapper struct. No per-source .ush include is generated any more. See Pipeline.

So: arithmetic that is awkward as a node graph goes in HLSL; engine inputs, parameters and bindings stay in graph code. The two meet at a function call.

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

// .dss — the same helper, as one Custom node
/// @custom
float3 ApplyTint(float3 color, float3 tint)
{
    return color * tint;
}

// 1.x — the same helper
Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
    result = color * tint;
}

In 1.x a declared return type is legal too and lowers to a single output, so Function float3 ApplyTint(in vec3 color, in vec3 tint) { return color * tint; } is the HLSL-style spelling of the same helper.

Types

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

A few tokens HLSL does not know: the .dss material (a material attribute set), and the 1.x MaterialAttributes, StaticBool and Substrate. As a function result, MaterialAttributes is written as FMaterialAttributes and StaticBool as bool since 2.0.0; as a Custom node input, MaterialAttributes is DSH6210 and Substrate is DSH6253 in any position — a Custom node has no pins of either kind. Write such pipelines as ordinary graph code, a ShaderFunction or a GraphFunction. The full validity matrix is on Types and Values.

Matrices

A graph has no matrix values. float2x2 / float3x3 / float4x4 — and mat2 / mat3 / mat4, which 1.x normalizes to them — are DSH3252 in Properties and DSH4361 anywhere else they would become a node or a pin. A 1.x Function signature does accept mat3 lexically, so the declaration parses and the call fails:

Function float3 Rotate(in mat3 basis, in vec3 v) { return mul(basis, v); }
// parses; a Graph call that passes a matrix to 'basis' is DSH4361

Matrix work belongs inside a /// @custom / Function body, as locals, or goes through the transform builtins — UE.TransformVector and UE.TransformPosition, see UE.* Nodes.

Signatures

HLSL function signatures and DreamShaderLang function signatures look alike, but the rules differ in places.

A 1.x function must produce something: at least one out parameter, or a return type. Neither is DSH6305.

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;
}

since 2.0.0 return is kept as written: the body now is the body of the HLSL function that returns the node's first output, so return expr; at any brace depth returns what HLSL says it does (1.x rewrote only the depth-0 returns, and a nested one bypassed __return). What is still checked: a top-level bare return; under a return type (DSH6308), a return; anywhere in a function without one (DSH6256), and a return type with no return at all (the warning DSH6257; the output is 0).

Textures and samplers

A texture-typed input is one pin carrying the texture object, and the engine declares SamplerState <ParamName>Sampler beside it. Sample with that name inside the body:

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;
}

since 2.0.0 tex.Sample(uv) works too — as do SampleLevel, SampleBias and SampleGrad with one argument fewer than HLSL's own form — and is rewritten to the engine's Texture2DSample(tex, texSampler, uv) family. An embedded helper's signature gains SamplerState <Name>Sampler after each texture parameter, and a call to it from another body passes the matching argument; such a call must pass every argument (DSH6262), with a plain name as the texture argument (DSH6263). SamplerState is not in the set that triggers this expansion.

Control flow

Intrinsics

since 2.0.0 distance, exp, exp2, log, log2, log10, tan, sign, round, trunc, ddx, ddy, fwidth, rcp, rsqrt and more are builtins now. Still absent: sinh / cosh / tanh (no material node — write them in a @custom body) and matrices.

The Sine / Cosine nodes that graph sin / cos build take cycles (Period = 1); only sin / cos in an HLSL body take radians. round rounds half to even, as HLSL does since 2.1.2.

What happens to your body text

Every 1.x Function and GraphFunction body goes through an identifier-level rewrite before it is stored; the scan is comment- and string-aware. A .dss /// @custom body is kept verbatim, without this pass.

An #include at the top of a body (only whitespace and comments before it) is not part of the function: it is blanked out of the body (with spaces, so lines and columns still match) and put on the include list of every Custom node whose code holds the body, which the engine includes at file scope. An #include after a statement stays in the body. The full two-way alias table is on GLSL Overview.

DreamShaderBuiltins.ush

The plugin ships an HLSL header that defines DS_* macros and functions mirroring 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 that virtual directory is already mapped. 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 /DreamShaderGenerated, where since 2.0.0 no compile writes any more.

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 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 respectively) with no compile error.
• The include guard makes repeated inclusion in one translation unit harmless.
• The 1.x GLSL-alias rewrite skips string literals, so the path in #include "…" is never rewritten.

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, all valid inside a /// @custom or Function body. The In DreamShaderLang column marks what is understood outside a body.

Where to next