Compact type tokens

DreamShader » Parameters » Compact type tokens

The 39 built-in type tokens a Properties declaration may use without naming an Unreal expression class: 7 scalar spellings, 27 vector spellings and 5 texture spellings.

Synopsis

[const] { <scalar-token> | <vector-token> | <texture-token> } <name> [ = <default> ] [ [ <metadata> ] ] ;

All tokens are compared case-insensitively: FLOAT3, Float3 and float3 are the same token. A compact property is a uniform of the 2.0 type of that name (vec3 is float3), or a static const with const.

Scalar tokens

Seven spellings, all identical in every observable respect.

int1, uint1 and bool1 are scalar tokens too (since 2.0.0): the token is read as the 2.0 type of that name, and HLSL spells a scalar that way.

[!NOTE] int, uint, bool and half carry no integer, boolean or precision semantics at the node level. The generated node is a float ScalarParameter in every case, and the material graph performs no truncation. The only place an integer marker exists at all is a direct integer constructor call in Graph — see Conversions.

Scalar default grammar

float A = 0.5;      float B = -2;      float C = 2.5f;      float D = true;

The value is a number — an optional sign, digits with at most one ., an optional exponent (1e3, 2.5E-1), an optional trailing f — or true / false (any case), which are 1.0 and 0.0. Anything else is DSH3254 (2.0.0 – 2.1.0 refused an exponent too, which 1.x read). A number glued to letters, such as 1abc, is not even one token: it is DSH2105 (since 2.0.0; 1.x read it as 1.0).

With no = <default> the default is 0.

Vector tokens

27 spellings. Every one produces a UMaterialExpressionVectorParameter whose DefaultValue is a full FLinearColor; only the declared component count differs, and it is what decides which node output a Graph read targets.

The count is the digit the token ends in.

A const declaration with component count 3 forces A = 1.0 on the generated Constant3Vector.

Vector default grammar

<anything> ( <part> [ , <part> ] … )

The declaration keeps the first N of those four values, N being its component count, and the parameter node's DefaultValue is those N with the missing channels 0 and alpha 1: float2 T = float2(4, 4) is (4, 4, 0, 1) (since 2.0.0; 1.x wrote (4, 4, 0, 0)).

With no = <default> the default is (0, 0, 0, 1) for a 2- or 3-component token and (0, 0, 0, 0) for a 4-component one (since 2.0.0).

[!WARNING] The declared component count is never checked against the literal's arity. float2 P = float4(1, 2, 3, 4); and float4 P = vec2(1, 2); both parse, with no diagnostic. The literal fills four values by the table above and the declared count keeps the leading ones — so float4 P = vec2(1, 2) yields (1, 2, 0, 0) read as RGBA, and float2 P = float4(1, 2, 3, 4) yields (1, 2). Write the literal with the same arity as the declared token.

[!WARNING] The token before ( is not validated either, so a typo such as flaot3(1, 0, 0) is accepted silently as a vector literal. Only the declaration's type token is checked.

Texture tokens

Five spellings, four distinct dimensions.

Texture3D and VolumeTexture are exact synonyms.

A compact texture declaration produces a texture object parameter — not a sample node. To sample it, call it from Graph through a TextureSample builtin, or declare a TextureSampleParameter2D instead.

Texture default grammar

Texture2D A = Path(Game, "Textures/T_X");
Texture2D B = Path("/Game/Textures/T_X");
Texture2D C = "/Game/Textures/T_X";            // bare quoted absolute path (since 1.5.0)

The full grammar and every root spelling are in Path(…). The default is resolved when the material is built: a reference that does not resolve is DSH8271, whose message quotes the resolver's own code, and one that resolves to nothing loadable is DSH8218. A const texture's default is written to its TextureObject node's Texture property instead, where an asset that does not load is written as nothing, with no diagnostic — see Metadata.

Defaults when no asset is assigned

[!WARNING] Texture2DArray has no engine fallback. A Texture2DArray declared without = Path(…) keeps the node's 2D default texture, which is not an array, and the compiler says nothing (since 2.0.0; 1.x refused the declaration). Assign an explicit array asset.

Dimension validation

(since 2.0.0) The asset a default loads is not checked against the declared dimension. What is checked, before anything loads, is the class a Content Browser reference names in its Class'…' shell: a texture class of another dimension is DSH1044, and a class DreamShader knows is not a texture (MaterialFunction, CurveLinearColor, Font, …) is DSH1043. See Path(…).

After the asset is assigned, AutoSetSampleType() runs unless the declaration says SamplerType, so the sampler type follows the asset — see SamplerType.

[!NOTE] The texture-sample tokens get the same shell check, and TextureObjectParameter only its "not a texture" half. See Parameter node tokens.

Tokens that are not valid in Properties

These are real DreamShaderLang type tokens in other contexts. In a Properties declaration each of them is DSH3252, except StaticBool.

The Inputs / Outputs token set is documented in Inputs / Outputs / Results and the full cross-context matrix in Type tokens.

Notes

• vec*, ivec*, uvec* and bvec* are GLSL-flavoured spellings only; they behave exactly like float*, int*, uint* and bool* respectively.
• There is no compact token for a 1-component vector: float1 and half1 are scalar tokens.
• A compact texture property is a texture value in Graph, read from output 0 of its node.
• A const vector with a component count other than 2 or 3 uses the Constant4Vector branch; since every accepted vector token is 2, 3 or 4 components, that arm is only ever reached by 4.
• A const property keeps only what a constant node has (since 2.0.0). Description and SamplerType reach a const texture's TextureObject node. On a const scalar or vector the description is dropped, and Group, SortPriority and Slider — written, or inherited from a Group(…) scope — are DSH7224 warnings.
• A const vector read from Graph is the whole value of its constant node, not a named R / RG / RGB component output. See Using parameters in Graph.

Diagnostics

Example

Shader(Name="Docs/M_CompactTypes")
{
    Properties = {
        const float Gamma = 2.2;                       // Constant

        float  Strength = 1.0;                         // ScalarParameter, reads R
        float2 Tiling   = float2(4.0, 4.0);            // VectorParameter, reads RG
        vec3   Tint     = vec3(1.0, 0.5, 0.2);         // VectorParameter, reads RGB
        vec4   Overlay  = vec4(0.0, 0.0, 0.0, 1.0);    // VectorParameter, reads RGBA

        // A texture *object* parameter: it carries the asset, it does not sample it.
        Texture2D BaseTex = Path(Game, "Textures/T_White");
    }

    Settings = { Domain = "Surface"; ShadingModel = "Unlit"; BlendMode = "Opaque"; }
    Outputs  = { vec3 Color; Base.EmissiveColor = Color; }

    Graph = {
        vec2 UV = UE.TexCoord(Index = 0) * Tiling;
        Color = Tint * Strength * Gamma + Overlay.rgb + vec3(UV.x, UV.y, 0.0);
    }
}

Generated nodes:

Constant(2.2)                        Gamma
ScalarParameter                      Strength    DefaultValue = 1.0
VectorParameter                      Tiling      DefaultValue = (4, 4, 0, 1)     read through RG
VectorParameter                      Tint        DefaultValue = (1, 0.5, 0.2, 1) read through RGB
VectorParameter                      Overlay     DefaultValue = (0, 0, 0, 1)     read through RGBA
TextureCoordinate                    UV          CoordinateIndex = 0

BaseTex generates nothing here: a property nothing reads makes no node, and the build says so (DSH4390, info). A texture object parameter has to be consumed by something — a sample node, or a Texture2D input of a ShaderFunction. To declare a texture that samples itself, use TextureSampleParameter2D.

See also

• Parameters — the hub and the decision table
• Parameter node tokens — the 22 explicit *Parameter tokens
• Metadata block — [ … ] entries, Slider(min, max), reflected properties
• Path(…) — texture default asset references
• SamplerType — sampler type inference and override
• Using parameters in Graph — which node output a declared component count reads
• Properties (section) — the enclosing section grammar
• Type tokens — the full cross-context token matrix
• Constructors — the Graph-side constructor forms these literals resemble
• Conversions — component-count rules in Graph