Constructors

DreamShader » Graph » Constructors

Call-syntax expressions named after a scalar or vector type that build a value of that width from their arguments.

Synopsis

<constructor-call> := <constructor-name> ( <expression> [ , <expression> ] … )

Named arguments are rejected. A brace initializer is exactly a constructor call: vec3 rgb = {r, g, b}; is rewritten as vec3(r, g, b) and obeys every rule on this page.

The parser reads a constructor name as a type (since 2.0.0): the call never reaches the function lookup, and the binder checks it as it checks a .dss constructor.

Constructor names

34 names, all matched case-insensitively (FLOAT3(…) works). The component count is the number at the end of the name; a name without one, or with 1, is a scalar.

(since 2.0.0) the parser takes every spelling the HLSL type grammar has, in any case, so a few more names are constructors:

Names that do not exist

Every name above lexes as an ordinary identifier and, because it is not a type, falls through to the function lookup — DSH4208 unless a function of that name is declared.

MaterialAttributes, Substrate, the texture types and SamplerState are type names too, but no value of them can be constructed: Texture2D(…) is DSH4223.

[!WARNING] Constructor names shadow everything. A constructor name is read as a type while the call is parsed — before UE.* builtins, Substrate.* builtins, math builtins, parameters, and all user definitions are looked at. A Function, GraphFunction, ShaderFunction or VirtualFunction named float3, int, bool4, vec2 (or any other name in the tables) can be declared without a diagnostic but can never be called — every call site builds a constructor instead. See Name resolution.

Integer constructors

The integer names are int, int1..4, ivec2..4, uint, uint1..4 and uvec2..4. Their result is an int or uint value to the compiler.

The kind does exactly one thing: / is refused when both operands are integer constructor calls (DSH4243), as in 1.x. It performs no truncation, no rounding, and no range clamping — an integer constructor produces the same float-valued graph as its float counterpart, and int(7.9) is 7.9. See Integer division.

The kind comes from the constructor's own name, so wrapping in a non-integer constructor clears it: float(int(7)) is a float.

Argument rules

The call and its arguments are checked first; every check that fails is reported.

Then, with N the constructor's component count:

Component packing

Rule 6 is a straight left-to-right concatenation of channels — arguments of mixed widths are legal as long as the total is exact.

[!NOTE] A constructor never narrows, in a 1.x source either. float3(rgba) is an error, not a truncation; write rgba.rgb. Narrowing happens only at conversion sites — see Conversions. Widening happens only from a scalar (rule 5); float3(uv) will not zero-fill.

Constant folding

When every argument is a constant, the whole call is one constant node instead of N Constant nodes plus AppendVector nodes: a Constant / Constant2Vector / Constant3Vector / Constant4Vector holding the values. A constant is a numeric literal, a negated one, a const property, a variable that holds one, or any arithmetic on constants: the folding pass folds operators, constructors and swizzles whose operands are all constants (since 2.0.0).

Every value has the width of its type; a folded constructor has no width of its own that would override a declaration (since 2.0.0). See Conversions.

Equal constants are one node: vec3(0.5) written five times yields one Constant3Vector. See Node reuse.

Notes

• Rule 4 creates no node. float3(SomeFloat3) is a no-op wrapper; float3(SomeInt3) only changes the kind to float.
• A constructor call is an ordinary postfix expression and can be swizzled: vec4(uv, 0, 1).xy.
• A brace initializer with an empty body (float3 v = {};) does not reach a constructor at all — it produces the type's zero value. See Declarations.
• Nested brace initializers are not supported: float4 m = {{1,2},{3,4}}; is rewritten to float4({1,2},{3,4}), and a brace list as an argument is DSH2214.
• An output selector (Output=, OutputIndex=) on a constructor is DSH5253.

Diagnostics

Example

Shader(Name="Docs/M_Constructors", Root="Game")
{
    Properties { ScalarParameter K = 0.5; }
    Settings   { Domain = "Surface"; ShadingModel = "Unlit"; BlendMode = "Opaque"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }

    Graph {
        float  a    = frac(K * 3.0);
        vec3   grey = vec3(a);              // rule 5: scalar broadcast, no node
        vec3   tint = vec3(0.2, 0.4, 0.8);  // constant-folded to Constant3Vector
        vec2   uv   = float2(a, 1.0);       // rule 6: 1 + 1 packing
        Color = tint * grey + float3(uv, 0.0);   // rule 6: 2 + 1 packing
    }
}

Generated nodes:

ScalarParameter K
Constant(3.0), Multiply, Frac                      -> a
(no node)                                          -> vec3(a): `a` is wired where grey is read
Constant3Vector(0.2, 0.4, 0.8)                     -> tint               (folded, 1 node)
Multiply                                           -> tint * grey
Constant(1.0), AppendVector                        -> float2(a, 1.0)     (1 node)
Constant(0.0), AppendVector                        -> float3(uv, 0.0)
Add                                                -> Base.EmissiveColor

See also

• Expressions — operators, precedence, and the integer-division rule
• Literals — what counts as a constant for folding
• Conversions — narrowing, widening and the width of a value
• Swizzle — the correct way to narrow a value
• Declarations — brace initializers and declared type tokens
• Name resolution — the call-resolution order constructors sit at the top of
• Types — the complete type-token catalogue and removed aliases
• UE.TransformVector / UE.TransformPosition — the only matrix-like operations
• Node reuse — constant deduplication