Function settings

DreamShader » Settings » Function settings

The Settings section of a ShaderFunction, ShaderLayer or ShaderLayerBlend block: four keys that describe the generated UMaterialFunction to the Material Function Library.

Synopsis

ShaderFunction(Name = "<asset-path>")
{
    Settings [=] {
        [Description       = <text>;]
        [UserExposedCaption = <text>;]
        [ExposeToLibrary   = { true | false };]
        [LibraryCategories = "<category>[, <category>]…";]
    }
}

The same section is accepted, with the same four keys, in ShaderLayer, ShaderLayerBlend and their deprecated MaterialLayer / MaterialLayerBlend spellings. In 2.0 the keys are the /// @desc and /// @library directives of the exported function — see The 2.0 language.

Keys

Keys are matched ignoring case, so description, Description and DESCRIPTION are the same key. Underscores are not folded here — Expose_To_Library is not ExposeToLibrary.

(since 2.0.0) ExposeToLibrary and LibraryCategories act as one setting, the 2.0 /// @library <categories>: the function is exposed, under those categories, when ExposeToLibrary is true and LibraryCategories is not empty. ExposeToLibrary = true; alone leaves the function out of the library, and LibraryCategories without ExposeToLibrary = true; is dropped.

LibraryCategories clears the list before parsing, so the setting always replaces the asset's categories rather than appending to them. LibraryCategories = "A,, B ,"; yields exactly A and B.

Quotes are optional on every value, as everywhere in a Settings block: Description = Tint helper; and Description = "Tint helper"; are identical.

[!NOTE] Every key here is reset when the key is absent. Omitting ExposeToLibrary sets it to false; omitting Description empties it. A property edited by hand on the generated asset is discarded on the next regeneration — except the caption, which 2.0 does not write at all. See Regeneration.

[!WARNING] Any other key is ignored, with a DSH3263 warning (since 2.0.0; 1.x said nothing). Only these four names are looked up: Backend, Domain, ShadingModel, BlendMode, TwoSided and every other Shader setting do nothing in a ShaderFunction block, and a misspelling of one of the four — Descriptions, Expose_To_Library, LibraryCategory — is the same warning.

[!WARNING] The decompiler does not emit a Settings block when exporting a UMaterialFunction to .dsf. Description, UserExposedCaption, ExposeToLibrary and LibraryCategories are lost on that round trip and must be re-added by hand.

Related validation

These checks are the diagnostics a Settings mistake is most often confused with.

The generated asset's usage follows the block kind: ShaderFunction produces an ordinary material function, ShaderLayer a material-layer function, ShaderLayerBlend a layer-blend function.

Notes

• A VirtualFunction block also accepts a section named Settings, but it is a synonym for Options and takes an entirely different key set — Asset and Description. See Options.
• Function and GraphFunction blocks have no Settings section at all; their only sections are Inputs / Properties, Outputs / Results and Code / Graph.
• Multiple Settings sections in one block merge, last key wins, with a DSH3262 warning, exactly as in a Shader block. See Settings.
• ExposeToLibrary = true; with a LibraryCategories is what makes the function appear in the Material palette's function library; the categories decide where in that palette it sits.

Diagnostics

Description and LibraryCategories have no failure mode: any text is accepted.

Example

ShaderFunction(Name="Functions/F_Tint", Root="Game")
{
    Inputs = {
        vec3 InColor;
        vec3 InTint;
    }

    Outputs = {
        vec3 OutColor;
    }

    Settings = {
        Description        = "Multiplies a colour by a tint.";
        UserExposedCaption = "Tint";
        ExposeToLibrary    = true;
        LibraryCategories  = "DreamShader, Color";
    }

    Graph = {
        OutColor = InColor * InTint;
    }
}

Generated asset:

package  /Game/Functions/F_Tint                     UMaterialFunction
  Description           = "Multiplies a colour by a tint."
  bExposeToLibrary      = true
  LibraryCategoriesText = ["DreamShader", "Color"]

UserExposedCaption is reported with DSH3264 and not applied.

See also

• Settings — the block grammar and key normalization shared by every block kind
• Shader settings — the very different key surface of a Shader block
• ShaderFunction — the enclosing block
• ShaderLayer / ShaderLayerBlend — the layer block kinds and their arity rules
• VirtualFunction — declaring an existing UMaterialFunction
• Options — the VirtualFunction key set
• Inputs / Outputs / Results — the parameter sections a function declares
• Decompiler — the material-function round-trip gap
• Regeneration — what a rebuild resets
• Diagnostics index — every code