Inputs, Outputs and Results

DreamShader » DreamShaderLang » Inputs / Outputs / Results

The sections that declare a block's typed parameters — the input and output pins of a generated UMaterialFunction, or the declared output variables of a Shader.

Synopsis

Inputs  [=] { <parameter-declaration>… }
Outputs [=] { <parameter-declaration>… }
Results [=] { <parameter-declaration>… }

parameter-declaration := [ opt ] <type> <name> [ = <default-expression> ] [ [ <metadata> ] ] ;

The innermost [ … ] pair around <metadata> is literal DreamShaderLang punctuation; the outer pair is the meta-syntax for "optional". The ; may be left off the last declaration before }.

Inside a Shader, Outputs uses a different grammar that also carries binding statements:

Outputs [=]
{
    <output-declaration>…
    <output-binding>…
}

output-declaration := <type> <name> [ = <expression> ] ;

Output bindings are specified on Output bindings.

Section keywords per block

Results is a pure synonym: it appends into the same list as Outputs. Section names are matched case-insensitively, may appear in any order, and a repeated section appends to the previous one. The = before the { … } block is optional (since 1.5.0).

[!WARNING] Inside a VirtualFunction, Properties is an alias for Inputs and therefore gets the grammar on this page, not the Properties declaration grammar. Reading Properties as "parameter nodes" there is the single most common source of confusion in the section grammar.

Declaration members

Parse order

(since 2.0.0) The section is read as words, one declaration at a time:

Anything else is DSH3271, and the parser resumes at the next ;. A default with nothing after the = is DSH3271 too.

opt

opt is matched case-insensitively. It is what marks a pin optional, and (since 2.0.0) a default does too (legacy rule L7): <type> <name> = <expr>; is an optional input, where 1.x left it required with only a preview value. opt on an output means nothing and is a warning (DSH3272).

Whitespace

(since 2.0.0) Whitespace only separates words, in these sections as in Properties: a tab between opt, the type and the name is as good as a space. What 1.x split at the last literal space — so that a tab made the type token opt\tfloat — no longer exists. The type and the name are one word each: Material Attributes X; or float 4 Colour; is DSH3271.

[!NOTE] in and out are not qualifiers in these sections. They exist only on the HLSL Function / GraphFunction signature form, which is a different grammar. Writing Inputs = { in float X; } is DSH3271: in is a keyword, not a type.

Accepted types

Resolved when the file is bound. Tokens are matched case-insensitively.

A word that names no type is DSH4201. SamplerState is a type, but no function pin carries a sampler: DSH4364 (since 2.0.0; 1.x made it a Texture2D input). The pin type is looked up in the running engine's own list; one the engine does not have is DSH8228.

Two inputs or outputs of one name are DSH4214.

Input defaults

A default on an input is the value the pin takes when the caller leaves it unconnected; it makes the input optional (since 2.0.0).

The graph-expression path is what lets a default reference a node the block itself generates, including a const or parameter node declared in Properties (since 1.2.6):

ShaderFunction(Name="Functions/F_Sample")
{
    Properties = {
        const Texture2D PreviewTex = Path(Engine, "EngineResources/DefaultTexture");
    }
    Inputs = {
        opt Texture2D Tex = PreviewTex;      // preview graph, not a literal
        opt float     Mix = 0.5;             // constant → PreviewValue
    }
    Outputs = { vec4 OutColor; }
    Graph   = { OutColor = Tex(Coordinates = UE.TexCoord(Index = 0)) * Mix; }
}

A default is converted to the input's type as an assignment would be: a value that does not fit is DSH4226, and a wider vector is cut down to its leading components with DSH5289.

[!NOTE] (since 1.6.0) true and false are graph literals. A StaticBool input's default becomes a StaticBool node on the Preview pin — the engine ignores PreviewValue for static-bool inputs — so opt StaticBool Flag = false; generates the node Unreal requires.

Output defaults

[!WARNING] = <expression> on an entry of a material function's Outputs / Results is dropped, with a warning (DSH3273). Write the value in the Graph instead. This does not apply to a Shader's Outputs, where an initializer is meaningful (since 1.3.4).

Every declared output other than a first one named Result must be assigned somewhere in Graph (DSH6211); a first Result is the function's return value and starts at zero. An assigned value that does not fit is DSH4226 (a wider vector: DSH5289).

A material function must declare at least one output (DSH4315); a VirtualFunction must too (DSH6313).

Per-parameter metadata

The trailing [ … ] block on an input or output is read by the same code as Properties metadata, but only these keys are consumed:

[!WARNING] Metadata keys other than the ones above are accepted by the parser and dropped without a diagnostic. [SamplerType="LinearColor"] on an Inputs entry does nothing; that key only has an effect on a Properties declaration.

A malformed block — no ], a key without = or value — is DSH3255; a key written twice is DSH3256.

Pin GUIDs are cached by name across regeneration, which is why regenerating a ShaderFunction does not break existing call sites.

MaterialAttributes outputs

A MaterialAttributes output starts as an empty material, so member writes such as Attrs.BaseColor = … have a target. A layer's output starts as the material that came in instead; see ShaderLayer / ShaderLayerBlend. The same holds for a Shader's MaterialAttributes output declarations. See MaterialAttributes.

Layer and blend rules

ShaderLayer and ShaderLayerBlend constrain these sections further:

Layer controls belong in Properties, not in Inputs. Full rules and their codes — including BlendInputRelevance name matching (since UE 5.7) — are on ShaderLayer / ShaderLayerBlend.

Outputs in a Shader

A Shader's Outputs section fills two lists from one body: output-variable declarations and output bindings. Each statement is classified by its first words:

The declaration grammar is the typed-declaration form above, without opt and without metadata. A [ … ] block on a Shader Outputs statement is DSH3266. An = with nothing after it is DSH3270.

Shader-only rules:

• return is a keyword (since 2.0.0): it cannot name an output declaration (DSH3266) and is not a binding source. See Output bindings.
• An output name declared twice is DSH4220; a type that is not a type is DSH4201.
• When a Shader needs a Graph, and what a Shader with no Outputs section does, is on Shader.

The complete binding catalogue, the validation rules and every binding diagnostic are on Output bindings.

Notes

• Comments are skipped wherever whitespace may stand.
• Options and Settings are the VirtualFunction counterparts to these sections; see Options.
• A VirtualFunction declares an existing asset and never generates pins itself — its Inputs / Outputs describe the asset's interface so Graph calls can be type-checked. See VirtualFunction.

Diagnostics

Each code carries the line and column of the declaration; the code's page has the message.

Parse time

Binding and IR

Emit time

The complete cross-stage list is in the diagnostics index.

Example

ShaderFunction(Name="Functions/F_Opt")
{
    Inputs = {
        vec3 InColor;
        opt float Strength = 1.0 [
            Description="Preview strength";
            SortPriority=10;
        ];
    }

    Results = {                       // alias for Outputs
        vec3 OutColor [Description="Tinted result"];
    }

    Settings = {
        Description     = "Strength helper";
    }

    Graph = {
        OutColor = InColor * Strength;
    }
}

Generated asset interface:

UMaterialFunction  /Game/Functions/F_Opt.F_Opt
  FunctionInput   InColor    Vector3   required, SortPriority 0
  FunctionInput   Strength   Scalar    optional, PreviewValue 1.0, SortPriority 1
  FunctionOutput  OutColor   Vector3   SortPriority 0

See also

• Properties — the parameter/const declaration section
• ShaderFunction — the block these sections describe
• ShaderLayer / ShaderLayerBlend — the constraints on these sections
• VirtualFunction — where Properties aliases Inputs
• Options — the VirtualFunction Asset section
• Output bindings — the Base.* and Expression(…).Pin[i] binding catalogue
• Shader — the block whose Outputs carry bindings
• Types — the full type-token catalogue and per-context validity matrix
• Metadata — the [ … ] block grammar
• Calls — calling a ShaderFunction or VirtualFunction from Graph
• MaterialAttributes — member writes and Substrate interop
• Function settings — the keys a function's Settings honours
• Diagnostics index — every code, by stage