Parameters

DreamShader » Parameters

A parameter is a Properties declaration that becomes a named UMaterialExpression node in the generated asset — a material parameter an instance can override, a constant, or a builtin input node.

Synopsis

[const] <type-token> <name> [ = <default-value> ] [ [ <metadata-entry> { ; | , } … ] ] ;

The outer [ … ] of the metadata block is literal DreamShaderLang punctuation; the [ … ] around = <default-value> and around the whole metadata block is the "optional" meta-bracket. In other words, a declaration with metadata is written float A = 1.0 [Group="X"];.

The enclosing section grammar — where Properties may appear, the optional = before {, repetition, Group("Name") { … } scopes and the ordering rules — is specified in Properties (section). This section documents only what may stand in the <type-token>, <default-value> and <metadata-entry> slots.

Since 2.0.0 a 1.x source is read by the legacy front end, which turns each property into what the 2.0 language writes for it: a uniform, a static const, or a parameter node built where it is read. The .dss spelling is in The 2.0 language; dsc migrate writes it for you (Migrate).

The four kinds of type token

Every token is matched case-insensitively. A token that matches none of the above is DSH3252; one of the seven parameter node types that have no 2.0 spelling is DSH3253 (since 2.0.0).

Which form to use

[!NOTE] const is legal with the 39 compact tokens and, (since 2.0.0), with ScalarParameter, VectorParameter and TextureObjectParameter, which then build the same constant as const float, const float4 and const Texture2D. On any other *Parameter token it is DSH3253. On a UE.* declaration the const is ignored (since 2.0.0).

Pages

Notes

• A default value is optional for every type. With no = <default>, a scalar is 0, a vector is 0 in every channel (alpha 1 for a 2- or 3-component token), and a texture is the engine's default texture of its dimension (since 2.0.0; 1.x left a vector at the node's own default). A Texture2DArray has no engine default: its node keeps the class's 2D default texture, with no diagnostic (since 2.0.0). Assign an array asset.
• A property name is an identifier (since 2.0.0). float 1Bad = 0; is DSH2105 (a malformed number) and DSH3250.
• A property that becomes a declaration is declared at file scope (since 2.0.0). Two properties of one name — in one block, or in two blocks of the same file — are DSH4210. Names are compared exactly. The 1.x rule that a function's property may not share a name with one of its inputs has no 2.0 check.
• Declaration order does not constrain reads. A Graph may read a property declared further down the block. The exception is a UE.* property: it is a local declared at the head of each body that reads it, in Properties order, so an argument naming another UE.* property needs that one earlier in the list and read by the same body; otherwise the name is not declared (DSH4200).
• Properties means something else inside a VirtualFunction: there it is a synonym for Inputs and takes the typed-parameter grammar, not this one. See VirtualFunction.
• The parameter name written into the material is the declared name unless [ParameterName="…"] overrides it. See Metadata.

Diagnostics

Metadata, default-value and asset-reference diagnostics are on Metadata, Compact type tokens and Path(…). The complete list lives in the diagnostics index.

Example

Shader(Name="Docs/M_Parameters")
{
    Properties = {
        const float DebugScale = 1.0;                     // Constant, not overridable

        Group("Surface") {
            vec3  Tint      = vec3(1.0, 0.5, 0.2);        // VectorParameter, reads RGB
            float Roughness = 0.4 [Slider(0, 1)];         // ScalarParameter with a UI range
        }

        TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_White") [
            SamplerType  = "LinearColor";
            MipValueMode = "None";
        ];

        StaticSwitchParameter UseDetail = true;

        UE.TexCoord(Index = 0) UV;                        // MaterialExpressionTextureCoordinate
    }

    Settings = { Domain = "Surface"; ShadingModel = "DefaultLit"; BlendMode = "Opaque"; }

    Outputs = {
        vec3  Color;
        float Rough;

        Base.BaseColor  = Color;
        Base.Roughness  = Rough;
    }

    Graph = {
        vec4 Sample = BaseTex(Coordinates = UV);
        vec3 Lit    = Sample.rgb * Tint * DebugScale;
        Color = UseDetail(True = Lit, False = Tint);
        Rough = Roughness;
    }
}

Generated nodes:

Constant              DebugScale        (const -> not a parameter)
VectorParameter       Tint              Group="Surface" SortPriority=0
ScalarParameter       Roughness         Group="Surface" SortPriority=10 SliderMin=0 SliderMax=1
TextureSampleParameter2D BaseTex        SamplerType=LinearColor
StaticSwitchParameter UseDetail
TextureCoordinate     UV                CoordinateIndex=0

See also

• Properties (section) — the section grammar, const, and Group(…) scopes
• Type tokens — the per-context validity matrix for every type token
• Inputs / Outputs / Results — the other parameter grammar, used by functions
• Shader — the block a Properties section lives in
• ShaderFunction — function-local properties
• UE builtins — the complete UE.* catalogue
• UE.Expression — generic reflected node construction
• Graph — the language that consumes these parameters
• The 2.0 language — uniform, static const and /// directives
• Diagnostics index — every code