内置项

DreamShader » 内置项

DreamShaderLang 自行解析而不在作者声明中查找的名称： UE.* 命名空间、Substrate.* 命名空间、保留的 SampleTexture2D 形式，以及数学 内置函数集。

调用表面

自 2.0.0 起，这些表面共享同一实现。UE. 或 Substrate. 调用会绑定到 内置目录——通过反射读取运行中引擎的材质表达式类 （dsc export-catalog 将其写出）——而数学内置函数是编译器的核心操作之一。 各行的差异仍在于 旧版前端 在绑定器看到 1.x 写法之前对其所做的处理。

表面 3 是一种声明，而非表达式；从它声明的局部变量来看，该调用是普通的 UE. 调用。表面 1、2、4 和 5 是在 Graph 体内求值的表达式。

[!IMPORTANT] 表面 1 和 3 共享内置名称，但不共享参数列表。UE.TexCoord 在 Graph 中保留 Index 并用 DSH5254 丢弃 CoordinateIndex；作为属性声明时两者都接受，因为此处不适用 1.x 过滤器。所有差异均列于 UE.* 目录 § 属性声明形式。

保留的 SampleTexture2D 形式

SampleTexture2D(<texture-object>, <uv>) 不在任何命名空间中，但属于同一集群。它 是一个保留名称，由旧版前端在查找用户属性和函数之前重写为

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

——即整个样本，在需要 float4 的地方使用 RGBA。它是唯一区分大小写匹配的内置调用形式：sampletexture2d(t, uv) 不是它。它恰好接受两个位置参数 （否则会报 DSH5256）。参见 UE.Expression。

Graph 内的分派顺序

调用按以下顺序解析；首个匹配者胜出。完整查找见 名称解析。

在步骤 3 中，前缀之后的名称会在该前缀的命名空间中的目录内查找：

UE.Expression 不命名任何类，因此没有 Class 时它是 DSH5218。

名称与参数匹配

目录给出了参数顺序的类接受位置参数—— TextureCoordinate、Constant … Constant4Vector、Transform、TransformPosition、Panner、 ComponentMask、Time 以及五个 Substrate 合成节点——在其他位置则会被拒绝并产生 DSH5220 (自 2.0.0 起)。在 27 个 1.x 名称上，旧版前端会优先丢弃它们， 但 UE.TransformVector 和 UE.TransformPosition 的位置 0（Input）除外； UE.StaticSwitchParameter 在位置 0 读取 True，在位置 1 读取 False，而 SampleTexture2D 以位置方式接受其两个参数。数学内置项按位置接受参数， 或按节点引脚命名接受参数 (自 2.0.0 起)。

[!WARNING] 在 27 个 1.x 名称上，该名称未读取的参数会被丢弃——现在会给出警告。 旧版 前端保留 1.x 参数列表，并以 DSH5254 丢弃其他任何内容 (自 2.0.0 起；1.x 会无声丢弃)。UE.Time(Bogus = 1) 可以编译并会说明这一点； UE.TexCoord(0) 会产生 UV 通道 0，因为位置参数被丢弃，而 CoordinateIndex 保留其节点默认值。其他所有调用都会根据目录 逐参数绑定，不属于任何引脚或属性的名称会引发 DSH5213—— 或者在 1.x 源中，为已构建节点保留并产生 DSH5291。

页面

说明

• 在任何界面上，相同的调用都只对应一个节点。 IR 会合并具有相同类、 属性和输入的节点 (自 2.0.0 起；1.x 仅为泛型调用和 Substrate.* 调用 以及数学内置项复用节点，从不为 Custom 节点复用)。请参阅节点复用。
• 节点落在画布上的位置由布局处理决定。请参阅 图表布局。
• 在 GraphFunction 主体内编写的 UE.* 调用会被提升出 HLSL，并成为生成的 Custom 节点上的输入引脚。本页上的参数规则 仍然适用于该调用本身。
• Substrate.* 命名空间包含正在运行的引擎的 Substrate 类，在 UE 5.4 之前没有任何此类；在那里调用会引发 DSH5210。请参阅 Substrate。
• 内置项目录是引擎的反射类，包括已加载插件的类。不属于内置项、已声明属性、 Graph 变量或已声明函数的名称属于 未知标识符。
• .dss 写入与 UE.<ClassShortName>(Pin = …, Property = …) 相同的节点；dsc migrate 以这种方式写入 每个 1.x 调用。请参阅 dsc migrate 和 DreamShaderLang 2.0。

示例

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;
    }
}

另请参阅

• UE.* 目录 — 每个 1.x 名称各占一项
• UE.Expression — 按类查找任意节点
• OutputType — 1.x 需要的、2.0 作为提示读取的参数
• Substrate — Substrate.* 的同类命名空间
• Custom Pass 节点 — .dsp 管线材质使用的两个表达式
• 数学内置项 — 标量/向量数学集合
• 调用 — 调用语法、命名参数和输出参数
• 名称解析 — 被调用方经历的名称查找顺序
• 节点复用 — 相同的调用与节点
• 属性 — 声明形式所在的章节
• Path(…) — 资产引用语法
• 诊断索引 — 每个代码