Type tokens

DreamShader » DreamShaderLang » Type tokens

The closed set of identifiers that name a value's shape in a declaration, and the per-context rules that decide which of them a given declaration position accepts.

(since 2.0.0) Every type token goes through one table: a 1.x spelling is read as its 2.0 type (vec3 and Float3 as float3, MaterialAttributes as material, StaticBool as bool), with no diagnostic, and a word that is no type is kept as written for the binder to refuse (DSH4201) — in Properties the front end refuses it first (DSH3252). The 2.0 type names are on DreamShaderLang 2.0.

Synopsis

A type token is the first element of every declaration form in the language:

// Properties section
[const] <type> <name> [ = <default> ] [ [ <metadata> ] ] ;

// Inputs / Outputs / Results of a material function
[opt] <type> <name> [ = <default> ] [ [ <metadata> ] ] ;

// Shader Outputs variable declaration
<type> <name> [ = <expression> ] ;

// Function / GraphFunction signature
Function [ <type> ] <name> ( [ { in | out } ] <type> <name> , … ) { … }

// Graph declaration
<type> <name> [ = { <expression> | { <brace-initializer> } } ] ;

Contexts

The six declaration positions do not share one type set. Each row is a column of the validity matrix.

[!NOTE] (since 2.0.0) Prop is checked by the front end while the section is read. The other columns are checked by the binder for the whole file, and by the lowering to the graph where a value of the type would become a pin — a type no pin carries is refused there, at the declaration or call that needs the pin.

Validity matrix

✔ accepted · ✘ rejected. A cell's code is the one a rejection raises.

1. A Texture3D input is a VolumeTexture pin.
2. A texture-typed in parameter of a Function also takes a companion SamplerState <Name>Sampler parameter in the generated HLSL, the one the engine declares beside every texture input of a Custom node. See Function.
3. A variable only: no Base. pin takes a texture, and a Substrate one goes only to Base.FrontMaterial. It has no zero value, so the Graph has to assign it before it is read.
4. Texture, SamplerState and Substrate declarations in a Graph block must carry an initializer — there is no default value for them: DSH2215.
5. A Substrate input is a Substrate pin of the function; Substrate values come from Substrate.* nodes, which the engine has from UE 5.4 on.
6. (since 2.0.0) Read as bool, so StaticBool X = true; in Properties declares a dynamic bool parameter, not a static one; 1.x refused the token there. Write StaticBoolParameter for a static switch parameter.
7. An input of either token is a StaticBool pin of the function.
8. Read as bool.
9. In Properties, StaticBoolParameter is a parameter-node token, not a type token: it generates a UMaterialExpressionStaticBoolParameter and accepts only true / false as its default (DSH3254). See Parameter nodes.

(since 2.0.0) SamplerState is a type of its own; 1.x read it as Texture2D wherever it accepted it. It is refused in Properties (DSH3252), as a material-function input (DSH4364) and as a Function result (DSH6254), and a Graph declaration of one needs an initializer (DSH2215).

Counts at a glance

[!NOTE] There is no vec1, ivec1, uvec1 or bvec1, and no half GLSL vector spelling. The single-component GLSL-style forms simply do not exist; use float or float1.

GLSL aliases

vec / ivec / uvec / bvec spellings are first-class tokens everywhere the corresponding float / int / uint / bool spelling is accepted — in Properties, Inputs, Outputs, Graph declarations and Graph constructors — and are read as that spelling.

GLSL identifier rewrites in Function bodies

A Function / GraphFunction signature reads every type token through the table above, and the body runs every identifier through a superset of the same map. Both are matched on the lower-cased whole identifier, so the rewrite is case-insensitive.

15 signature aliases; 18 body aliases. The rewrite is comment- and string-aware. It is applied to Function and GraphFunction bodies only — a Graph block, a Shader body and a ShaderFunction body are not rewritten. In a Graph block mix, fract and mod call lerp, frac and fmod, with the warning DSH5277 (since 2.0.0) (legacy rule L2). See Math builtins.

[!WARNING] The body rewrite matches the whole identifier, ignoring case. A helper, local variable or struct member named Mix, Mod, Fract, Vec3, Mat4 … inside a Function or GraphFunction body is silently renamed to lerp, fmod, frac, float3, float4x4. There is no diagnostic; the failure surfaces as an HLSL compile error, or as silently different math. Rename the identifier.

Matrices

There are no matrix values in a graph. mat2 / mat3 / mat4 and float2x2 / float3x3 / float4x4 are refused in Properties (DSH3252), and anywhere else a value of a matrix type that would become a node or a pin is DSH4361.

mat2 / mat3 / mat4 are nevertheless accepted lexically in a Function signature, which reads them as float2x2 … float4x4. The declaration therefore 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-shaped work is reachable through the transform builtins — see UE.TransformVector / UE.TransformPosition — or inside an HLSL body.

Whitespace inside a token

(since 2.0.0) A type token is one word. 1.x removed the spaces inside a token in some contexts, so float 3 read as float3 and Material Attributes as MaterialAttributes there; now they are two words, and the declaration does not parse.

Generated HLSL spelling

When a Function is lowered to a generated .ush helper, each declared type is written into the HLSL signature in its 2.0 spelling:

(since 2.0.0) 1.x wrote MaterialAttributes, StaticBool and StaticBoolParameter verbatim, which produced a helper Unreal could not compile.

Component-count derivation

A token's width is its digit suffix: …2 to …4 is a vector of that many components, …1 or no digit a scalar — float1 is HLSL's spelling of a scalar — and …NxM a matrix.

Removed

These names are not special-cased anywhere; they are refused like any word that is no type — DSH3252 in a Properties block, DSH4201 everywhere else.

Diagnostics

The complete list is in the diagnostics index.

Example

One token from each family, each in a context that accepts it:

ShaderFunction(Name="Functions/F_Types")
{
    Properties = {
        float     Strength = 1.0;              // scalar token
        vec3      Tint     = vec3(1, 1, 1);    // GLSL vector spelling
        Texture2D Noise    = Path(Game, "Textures/T_Noise");
    }

    Inputs = {
        vec2                   UV;            // numeric
        opt StaticBool         UseTint;       // a StaticBool pin
        opt MaterialAttributes InAttrs;       // a MaterialAttributes pin
    }

    Outputs = {
        vec3 OutColor;
    }

    Graph = {
        Texture2D Src = Noise;                 // texture declaration needs an initializer
        vec4 Sampled  = SampleTexture2D(Src, UV);
        float3 Base   = Sampled.rgb * Strength;
        OutColor      = Base * Tint;
    }
}

// Function signature tokens are read as their 2.0 spelling, then checked like any declaration.
Function float Luma(in vec3 color)          // vec3 -> float3 in the generated HLSL
{
    return dot(color, float3(0.299, 0.587, 0.114));
}

See also

• Properties — the Properties section grammar and which tokens it accepts
• Inputs / Outputs / Results — typed-parameter sections of material functions
• Output bindings — Shader Outputs declarations and Base.* targets
• Function — signature grammar, in / out, return types, generated HLSL
• GraphFunction — the UE.*-hoisting function form
• Keywords — the complete keyword index and deprecated spellings
• Graph declarations — declaring values inside a Graph block
• Conversions — coercion, widening, silent narrowing
• Constructors — the constructor names
• MaterialAttributes — reading and writing attribute members
• Compact parameter types — which node each compact token generates
• Parameter nodes — the 22 explicit *Parameter tokens
• OutputType / ResultType — the token set accepted by UE.* calls
• Substrate builtins — the UE 5.4+ Substrate.* surface
• DreamShaderLang 2.0 — the type names a .dss writes
• Diagnostics index — every code