ShaderFunction

DreamShader » DreamShaderLang » ShaderFunction

A top-level block that declares one reusable Unreal material function: its typed input and output pins, its function-local parameter nodes, and the node graph that connects them.

The legacy front end reads a ShaderFunction as an export function of the 2.0 language: its inputs are parameters, a first output named Result is the return value, and the other outputs are out parameters. dsc migrate writes it that way.

Synopsis

ShaderFunction(Name = "<asset-path>" [, Root = "<root>"])
{
    [Properties            [=] { <property-declaration> ; … }]
    [Inputs                [=] { <parameter-declaration> ; … }]
    { Outputs | Results }  [=] { <parameter-declaration> ; … }
    Graph                  [=] { <graph-statement> … }
    [Settings              [=] { <key> = <value> ; … }]
    [Layout                [=] { { Node( … ) | Comment( … ) } ; … }]
}

A function needs at least one output (DSH4315) and a Graph that assigns its outputs. Sections may appear in any order and may be repeated. The = between a section name and its { … } block is optional sugar (since 1.5.0); a ; after a section's closing } is optional.

The keyword ShaderFunction is matched case-sensitively; section names are matched case-insensitively. See Lexical elements.

Header attributes

Attribute keys are matched case-insensitively (name= works). Values may be quoted or bare; a bare value runs to the next , or ) outside parentheses. A key written twice is a warning (DSH2244) and the later value wins. A trailing comma before ) is accepted, as in 1.x (2.0.0 – 2.1.0 refused it with DSH2243). A missing or empty Name is DSH2242.

Full Name / Root grammar, the accepted root spellings, and the resulting on-disk path are specified in Asset paths.

Sections

The same body parser serves ShaderFunction, ShaderLayer and ShaderLayerBlend; the section table above is identical for all three.

Properties versus Inputs

Both sections put something into the generated function, but they are different grammars producing different nodes.

(since 2.0.0) Both sections are read as words: the type and the name are one word each, whatever whitespace separates them.

A property that the Graph never mentions produces no node in the generated asset (since 1.3.2).

Properties in a ShaderFunction is not the same thing as Properties inside a VirtualFunction, where the keyword is a synonym for Inputs.

Parameter types

Inputs, Outputs and Results accept these type tokens, matched case-insensitively. A type is one word.

The pin type is looked up in the running engine's own list; a type the engine does not have (such as Substrate on an engine without it) is DSH8228.

Input defaults and opt

A default that folds to a constant is written into PreviewValue. Anything else is built as a graph expression and connected to the input's Preview pin — which is how opt Texture2D Tex = PreviewTex; referencing a generated Properties entry works (since 1.2.6). A StaticBool input's default becomes a StaticBool node on the Preview pin, because the engine ignores PreviewValue there. A default whose type does not fit the input is reported as an assignment would be (DSH4226; a wider vector is cut down with DSH5289).

(since 2.0.0) opt, the type and the name are words: a tab between them is as good as a space.

Per-parameter metadata

The trailing [ … ] block is accepted on Inputs, Outputs and Results declarations. Only these keys have an effect; unlike Properties, no other key is reflected onto the generated node.

A malformed block is DSH3255–DSH3257. Full metadata grammar, including the Slider(min, max) shorthand, is in Metadata.

Outputs

The first output, when it is named exactly Result, is the function's return value: it starts at zero and the Graph assigns it. Every other output is an out parameter the Graph has to assign.

A MaterialAttributes output starts as an empty material, so member writes such as Attrs.BaseColor = …; have a target. See MaterialAttributes.

[!NOTE] An initializer on an output declaration (vec3 OutColor = InColor;) is dropped with DSH3273 — a function output is only ever driven by the Graph. This is unlike a Shader's Outputs, where an initializer is meaningful.

Generated asset

Name + Root resolve to a package path exactly as described in Asset paths. The asset created there is a UMaterialFunction and its MaterialFunctionUsage is set to Default.

When an asset already exists at that path it is reused only if its class is exactly UMaterialFunction; a subclass such as UMaterialFunctionMaterialLayer is DSH8110, an unrelated object DSH8111. If the package exists on disk and the object carries no DreamShader provenance metadata, generation refuses to touch it (DSH8112). See Regeneration.

The Settings keys are applied to the asset on every build, so removing a key from the source removes it from the asset:

ExposeToLibrary with a value other than true / false is a warning (DSH3265) and counts as false. Every other key is a warning (DSH3263) and is ignored — there is no generic reflected-property path here, unlike Shader settings. See Function settings.

Input and output identity across regeneration

Before the old graph is cleared, the Id GUID of every FunctionInput and FunctionOutput is cached by pin name and restored onto the newly created node (since 1.3.2). Existing MaterialFunctionCall nodes in hand-authored materials therefore keep their wiring across a regeneration, as long as the pin name is unchanged. Renaming an input or output is equivalent to deleting it and adding a new one: call sites lose that connection.

[!WARNING] A rebuild replaces the function's graph. A function that no longer holds what DreamShader generated into it is not rebuilt (DSH8207), and neither is one open in an asset editor (DSH8206). See Regeneration.

Calling a ShaderFunction

Inside the Graph of another function block of the same file, the callee name is the asset's leaf, as an identifier: F_Tint for Name="Functions/F_Tint". A call that matches it only in case resolves when the match is unique, with DSH5275. When a function the file can call already has that name — a Function from an imported header, say — the block's function is declared under another one (<Leaf>_Asset, with DSH5290), the asset keeps its name, and the call reaches the other function.

A Shader calls a ShaderFunction of its own .dsm by name, like any function of the file; the function's asset is built first. (2.0.0 – 2.1.0 refused the two in one file with DSH6201.) An asset block cannot be imported (DSH2249), so any other file reaches the generated asset through a VirtualFunction.

// ShaderFunction(Name="Functions/F_Tint") declared elsewhere in the same .dsf:
vec3 Tinted = F_Tint(BaseColor, Tint);          // single-output call as a value  (since 1.5.0)
F_Tint(BaseColor, Tint, OutColor, OutLuma);     // statement call: inputs, then one target per output

Argument rules, default arguments and the named-argument form are specified in Calls.

Notes

• One compile of a file builds every asset it declares. A .dsm or .dsf may declare any number of ShaderFunction, ShaderLayer, ShaderLayerBlend, VirtualFunction, Function, GraphFunction and Namespace blocks, and a .dsm one Shader beside them (2.0.0 – 2.1.0 refused a Shader beside a function or layer with DSH6201). A .dss makes a material or function assets, not both, so dsc migrate wants the functions moved to a .dsf first. See Source files.
• The file-kind restriction is a parse, decided per block (since 2.0.0). A .dsh holding a ShaderFunction block is DSH2249; a comment or a string that mentions ShaderFunction( is fine.
• A file that declares only functions needs no Shader block; each built function adds a Generated <Kind> <AssetPath> from <SourceFile>. line to the compile output (<Kind> is MaterialFunction here).
• Regeneration is skipped when the source hash is unchanged and the asset's MaterialFunctionUsage already matches the block kind; the compile output then says Skipped <AssetPath> from <SourceFile>; … for it, as for a material. See Caching.
• Layout is accepted and applies to the function's own graph.
• The Code section is rejected outright (DSH2246).

Diagnostics

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

Parse time

Errors inside Properties, Graph and Layout are listed on Properties, Graph and Layout.

Binding and IR

Emit time

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

Example

ShaderFunction(Name="Functions/F_Tint", Root="Game")
{
    Properties = {
        Group("Tint") {
            float Boost = 1.0 [Slider(0, 4); Description="Extra gain applied after tinting"];
        }
        const float Epsilon = 0.001;
    }

    Inputs = {
        vec3  InColor;
        vec3  InTint                [Description="Multiplied with InColor"];
        opt float Strength = 1.0    [Description="Blend amount"; SortPriority=10];
    }

    Outputs = {
        vec3  OutColor              [Description="Tinted colour"];
        float OutLuma;
    }

    Settings = {
        Description        = "Tint helper";
        ExposeToLibrary    = true;
        LibraryCategories  = "DreamShader, Color";
    }

    Graph = {
        vec3 Tinted = InColor * InTint * Boost;
        OutColor    = lerp(InColor, Tinted, Strength);
        OutLuma     = dot(OutColor, vec3(0.2126, 0.7152, 0.0722)) + Epsilon;
    }
}

Generated asset:

package     /Game/Functions/F_Tint
object path /Game/Functions/F_Tint.F_Tint
class       UMaterialFunction   (usage: Default)
on disk     <Project>/Content/Functions/F_Tint.uasset      (persist mode only)

interface   in  InColor   Vector3
            in  InTint    Vector3
            in  Strength  Scalar     (optional, preview 1.0; SortPriority=10 keeps it last)
            out OutColor  Vector3
            out OutLuma   Scalar
parameters  Boost         ScalarParameter, group "Tint", slider 0..4

See also

• Source files — which block kinds each of .dsm / .dsh / .dsf may contain
• Shader — the UMaterial-producing top-level block
• ShaderLayer / ShaderLayerBlend — the material-layer variants of this block
• VirtualFunction — declaring an existing UMaterialFunction instead of generating one
• Properties — the Properties section grammar, Group(…) scopes and const
• Inputs / Outputs / Results — the typed-parameter grammar in full
• Metadata — the [ … ] block, Slider(…) and reflected passthrough
• Types — the complete type-token catalogue and per-context validity matrix
• Layout — Node / Comment placement directives and #Region
• Graph — the statement/expression language inside Graph
• Calls — calling functions from a Graph, argument forms, default
• Function settings — the keys a material-function Settings honours
• Asset paths — Name= + Root= → package path
• Regeneration — what survives a rebuild and what does not
• Caching — the source-hash skip
• Diagnostics index — every code, by stage