Builtins

DreamShader » Builtins

The names DreamShaderLang resolves itself instead of looking them up among the author's declarations: the UE.* namespace, the Substrate.* namespace, the reserved SampleTexture2D form, and the math builtin set.

The call surfaces

Since 2.0.0 the surfaces share one implementation. A UE. or Substrate. call is bound against the builtin catalog — the material expression classes of the running engine, read by reflection (dsc export-catalog writes it out) — and a math builtin is one of the compiler's core operations. What still differs between the rows is what the legacy front end does to a 1.x spelling before the binder sees it.

Surface 3 is a declaration, not an expression; from the local it declares, the call is an ordinary UE. call. Surfaces 1, 2, 4 and 5 are expressions evaluated inside a Graph body.

[!IMPORTANT] Surfaces 1 and 3 share builtin names but not argument lists. UE.TexCoord in a Graph keeps Index and drops CoordinateIndex with DSH5254; as a property declaration it takes both, since no 1.x filter applies there. Every difference is tabulated in UE.* catalogue § Properties declaration form.

The reserved SampleTexture2D form

SampleTexture2D(<texture-object>, <uv>) is not in a namespace but belongs to the same cluster. It is a reserved name, rewritten by the legacy front end before user properties and functions are looked up, to

UE.Expression(Class = "TextureSample", TextureObject = <arg0>, Coordinates = <arg1>)

— the whole sample, RGBA where a float4 is wanted. It is the only builtin call form matched case-sensitively: sampletexture2d(t, uv) is not it. It takes exactly two positional arguments (DSH5256 otherwise). See UE.Expression.

Dispatch order inside a Graph

A call is resolved in this order; the first match wins. The full lookup is on Name resolution.

Inside step 3 the name after the prefix is looked up in the catalog, in the prefix's namespace:

UE.Expression names no class, so without Class it is DSH5218.

Name and argument matching

Positional arguments are accepted by the classes the catalog gives an argument order — TextureCoordinate, Constant … Constant4Vector, Transform, TransformPosition, Panner, ComponentMask, Time and the five Substrate composition nodes — and refused elsewhere with DSH5220 (since 2.0.0). On the 27 1.x names the legacy front end drops them first, except position 0 (Input) of UE.TransformVector and UE.TransformPosition; UE.StaticSwitchParameter reads True at position 0 and False at position 1, and SampleTexture2D takes both of its arguments positionally. The math builtins take arguments by position, or named after the node's pins (since 2.0.0).

[!WARNING] On the 27 1.x names, an argument the name did not read is dropped — with a warning now. The legacy front end keeps the 1.x argument list and drops anything else with DSH5254 (since 2.0.0; 1.x dropped it without a word). UE.Time(Bogus = 1) compiles and says so; UE.TexCoord(0) produces UV channel 0 because the positional argument is dropped and CoordinateIndex keeps its node default. Every other call is bound argument by argument against the catalog, and a name that is no pin or property is DSH5213 — or, in a 1.x source, kept for the built node with DSH5291.

Pages

Notes

• Identical calls are one node, on every surface. The IR merges nodes with the same class, properties and inputs (since 2.0.0; 1.x reused nodes for the generic and Substrate.* calls and the math builtins only, and never for a Custom node). See Node reuse.
• Where a node lands on the canvas is decided by the layout pass. See Graph layout.
• A UE.* call written inside a GraphFunction body is hoisted out of the HLSL and becomes a generated input pin on the emitted Custom node. The argument rules on this page still apply to the call itself.
• The Substrate.* namespace holds the Substrate classes of the running engine, which has none before UE 5.4; a call there is DSH5210. See Substrate.
• The builtin catalog is the engine's reflected classes, those of loaded plugins included. A name that is not a builtin, a declared property, a Graph variable or a declared function is an unknown identifier.
• A .dss writes the same nodes as UE.<ClassShortName>(Pin = …, Property = …); dsc migrate writes each 1.x call that way. See dsc migrate and DreamShaderLang 2.0.

Example

Shader(Name="Docs/M_Surfaces")
{
    Properties {
        Texture2D BaseTex = Path(Game, "Textures/T_Noise");
        float     Speed   = 0.2;
    }

    Settings { ShadingModel = "Unlit"; }

    Outputs {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph {
        // 1 — 1.x UE.* names
        float2 uv = UE.Panner(Coordinate = UE.TexCoord(Index = 0), Speed = Speed);

        // 2 — any node by its class name; OutputType is optional since 2.0.0
        float pulse = UE.Sine(OutputType = "float1", Input = UE.Time());

        // the reserved two-argument sample form
        float4 tex = SampleTexture2D(BaseTex, uv);

        // 4 — math builtin
        float k = pow(pulse, 2.0);

        Color = tex.rgb * k;
    }
}

See also

• UE.* catalogue — every 1.x name, one entry each
• UE.Expression — any node by its class
• OutputType — the argument 1.x needed and 2.0 reads as a hint
• Substrate — the Substrate.* sibling namespace
• Custom Pass nodes — the two expressions a .dsp pipeline's materials use
• Math builtins — the scalar/vector math set
• Calls — call syntax, named arguments and out arguments
• Name resolution — the lookup order a callee goes through
• Node reuse — identical calls and nodes
• Properties — the section the declaration form lives in
• Path(…) — asset-reference syntax
• Diagnostics index — every code