Options

DreamShader » DreamShaderLang » Options

The section of a VirtualFunction block that names the existing UMaterialFunction asset the declaration stands for.

In 2.0 the same declaration is an extern prototype with /// @asset — see DreamShaderLang 2.0; dsc migrate rewrites a VirtualFunction that way.

Synopsis

{ Options | Settings } [=]
{
    Asset = <asset-reference> ;
    [ <key> = <value> ; ]…
}

asset-reference := Path( <root> , "<relative-path>" )
                 | Path( "<absolute-object-path>" )
                 | "<absolute-object-path>"
                 | <absolute-object-path>

Options and Settings are accepted interchangeably as the section keyword; both read into the same list. Section names are matched case-insensitively, the = before { … } is optional (since 1.5.0), and a repeated section merges into the same list.

Keys

[!NOTE] The VirtualFunction sync service writes a Description key alongside Asset when it generates or refreshes a declaration.

Precedence

The block attribute wins over the section:

VirtualFunction(Name="BufferWriter", Asset=Path(Game, "MaterialFunctions/F_BufferWriter"))
{
    Options = { Asset = Path(Game, "Ignored"); }   // not consulted — the attribute was present
    Outputs = { float3 Result; }
}

Options.Asset is read only when the Asset attribute is absent or empty after trimming.

Statement grammar

Identical to the Settings grammar.

The asset reference is trimmed before it is used, so Asset = " /Game/MF/F_X "; and Asset = /Game/MF/F_X; name the same asset.

String escapes recognized in a quoted value are \n, \r, \t, \", \\ and \0; any other \X is DSH2104 (since 2.0.0; 1.x yielded the literal X).

Asset reference resolution

The front end keeps the reference as written, and the compiler resolves it when a Graph call to the VirtualFunction is built, using the general asset-reference resolver — not the texture-default resolver. Accepted root spellings:

A Path( … ) call takes either 1 argument (an absolute /… object path) or 2 arguments (root plus a relative path). A bare or quoted value that is not a Path( … ) call is used directly and must be an absolute object path. The full grammar, both resolvers and every root diagnostic are on Path(...).

[!WARNING] An unresolvable Asset is not diagnosed when the file is read or bound — only when a Graph call to the function is built: DSH8270 for a reference that does not resolve, DSH8219 for an asset that does not load. A VirtualFunction that nothing calls compiles with a broken Asset and produces no message.

Post-parse rules

Sections accepted alongside Options

Notes

• A VirtualFunction's Inputs and Outputs describe the existing asset's interface. They are what a Graph call is checked against; they do not create pins. Getting them out of step with the asset produces errors where the call is built — DSH8220 for an input the asset does not have, DSH8221 for an output — not declaration errors.
• .dsh files may contain VirtualFunction blocks and nothing else that generates assets. A .dsm or .dsf whose only blocks are VirtualFunctions builds no asset.

Diagnostics

Every diagnostic carries the line and column of the statement it is about.

The complete list is in the diagnostics index.

Example

VirtualFunction(Name="BufferWriter")
{
    Options = {
        Asset = Path(Game, "MaterialFunctions/F_BufferWriter");
        Description = "Existing material function declared for Graph calls.";
    }

    Inputs = {
        float3 Color;
        float  Alpha;
    }

    Outputs = {
        float3 Result;
    }
}

Calling it from a Shader in the same file, or in a file that imports it:

Graph = {
    float3 Written = BufferWriter(Color = Tint, Alpha = A);
}

Resolved reference:

Asset  Path(Game, "MaterialFunctions/F_BufferWriter")
    -> /Game/MaterialFunctions/F_BufferWriter.F_BufferWriter

See also

• VirtualFunction — the block Options belongs to
• Inputs / Outputs / Results — the interface sections of a VirtualFunction
• Settings — the identical statement grammar
• Path(...) — every root spelling and both resolvers
• Calls — calling a VirtualFunction from Graph
• VirtualFunction tools — the editor actions and the sync service
• Source files — which block kinds .dsh / .dsf / .dsm may hold
• DreamShaderLang 2.0 — /// @asset and extern, the .dss spelling
• Diagnostics index — every code