Substrate.*

DreamShader » 内置节点 » Substrate.*

与 UE.* 并列的调用命名空间，装着 Unreal 的 Substrate BSDF、组合与工具 材质节点。（自 2.0.0 起）它是内置目录的 Substrate 命名空间：运行中引擎拥有的每一个 Substrate 类， 按名字调用。

可用性

绑定器里没有任何按版本编译进或编译出的东西 (自 2.0.0 起)：目录列出运行中引擎的 Substrate 类，而 UE 5.4 之前的引擎一个都没有。

[!NOTE] 项目还必须启用 Substrate（Project Settings ▸ Engine ▸ Rendering ▸ Substrate），Substrate 图才能在引擎里编译。DreamShader 会读这个设置 (自 2.0.0 起)：Shader 的 Substrate 设置 —— Legacy、Bridge 或 Native —— 说明 材质在开或不开它时的工程里怎么建，而 Native 在 Substrate 关闭时驱动 FrontMaterial 会报 DSH4382。见 一份源码，两种工程。

[!NOTE] 编辑器工具链跟随引擎。UE 5.4 以下，Bridge 清单 Saved/DreamShader/Bridge/substrate-builtins.json 被写成空条目数组、 supported: false 和一个 unsupportedReason —— 所以编辑器扩展的补全里 什么都没有。参见 Bridge。

语法概要

Substrate . <Name> ( [ <argument-name> = <expression> ]
                     [ , <argument-name> = <expression> ] …
                     [ , { Output | OutputName } = "<pin-name>" ]
                     [ , OutputIndex = <integer> ] )

Substrate 和 . 是字面量；[ … ]、{ a | b } 和 … 是元记号。

在 1.x 源码里前缀不区分大小写匹配 —— Substrate 是 1.x 的类型拼写， 类型拼写都忽略大小写读取 —— 只在忽略大小写时匹配的 <Name> 也接受，给出 警告 DSH5276：SUBSTRATE.UNLIT(…) 能解析。参数名 同样匹配 —— 精确匹配，或忽略大小写并给出 DSH5276 —— 此外是精确的：不 去掉任何分隔符。

参数模型

Substrate.* 调用和任何反射节点调用（UE.Expression）一样， 对名字选中的类绑定。

由反射驱动的绑定

对每个剩余参数，绑定器按顺序尝试：

1. 输入 pin —— 类的 pin 名，或其别名：pin 的显示名写成标识符形式 （Diffuse_Albedo），属性的显示名去掉空格也算。
2. 属性 —— 类的可编辑反射属性名或别名；bool 属性还可以去掉开头的 b， 所以 UseParameterBlending 能触达 bUseParameterBlending。
3. 虚拟参数 —— 在有这些 pin 的 BSDF 上，BaseColor / Metallic / Specular、 Haziness、Transmittance / Thickness 和 IOR 会变成那些 pin 前面一个转换节点的输入 (自 2.0.0 起)。见 Slab 上的旧参数。
4. 在 1.x 源码里，以上都不是、但带着值的名字以 DSH5291 保留，建节点时按名字连接 （节点没有这个 pin 时 DSH8212）。
5. 都不匹配 → DSH5213。

pin 名匹配优先于同名属性。值按 pin 的类型检查：Substrate pin 上的 数值、数值 pin 上的 Substrate 值、以及 MaterialAttributes pin 上任何不是 material 的值， 都报 DSH5214。

[!NOTE] 名字带空格的引擎 pin 能触达 (自 2.0.0 起)：显示为 Diffuse Albedo 的 pin 写作 Diffuse_Albedo，它的属性名 —— DiffuseAlbedo，也就是下面各表 列出的名字 —— 照旧可用。

[!NOTE] 可接受的参数名跟随引擎，而不是插件。 目录读自运行中 引擎的 UMaterialExpressionSubstrate* 类，所以引擎版本增删的某个输入 会随之出现或消失，插件不需要改动。下面各表列出这些类暴露的输入； 补全列标记的是 DreamShader 发布到编辑器补全和 Bridge 清单的精选子集，那个子集是插件固定的。同一个类上任何可编辑的非输入属性 —— 枚举、浮点、布尔 —— 即使这里没有列出，也同样可以作为字面量参数设置。

选择输出

Output= / OutputName= 按目录列出的输出名精确匹配，包括带空格的名字； 在 1.x 源码里只差大小写的匹配也接受，给出 DSH5276。没有这个输出报 DSH5201。OutputIndex= 取 0 起始的索引 （超过最后一个报 DSH5282）。只有下面的工具节点有多个输出。

目录

Substrate 输出标记输出是 Substrate 材质值、可绑定到 Base.FrontMaterial 的类；标为否的四个是工具节点，返回普通数值。

两对别名是完全的重复：同一个类、同样的输入、同样的输出类型，两种写法都没有被弃用。自 2.0.0 起又多了两个短名 —— Mix 即 HorizontalMix、Layer 即 VerticalLayer —— 而且每个类都能用目录短名（SubstrateSlabBSDF）调用， 也能用类名去掉前面的 MaterialExpressionSubstrate 和后面的 BSDF 调用；这就是调用本表没有列出的类的方式：UE 5.8 的 UMaterialExpressionSubstrateToonBSDF 是 Substrate.Toon。

输出类型

目录按引擎给每个输出定类型：BSDF 或组合节点产出 Substrate 值；工具节点产出数值，宽度按引擎给每个输出的类型 —— 引擎 没给类型时，和它被读入的位置一样宽。多输出的节点要指名读取一个输出。

一个 Substrate 值可以：

• 赋给 Substrate 类型的 Graph 变量或 Outputs 声明；
• 传给另一个 Substrate.* 节点或 UE.Expression 节点的 Substrate 类型输入；
• 用 +（Substrate.Add）组合、用 * <scalar>（Substrate.Weight）加权、用 lerp(A, B, t)（Substrate.HorizontalMix）混合 (自 2.0.0 起) —— 见 运算符与 lerp；
• 由静态开关选择，或由运行时 if 选择 —— 后者变成 Substrate.Select (自 2.0.0 起) —— 见 Substrate 值上的 if；
• 绑定到 Base.FrontMaterial。

Substrate 值上的其他运算符 —— -、/、A * B、复合赋值 —— 以及 Substrate 值 与数值之间的 lerp 报 DSH5293；把 Substrate 值传给其他数学内置报 DSH4226。HLSL Custom 节点 —— 一个 Function —— 既不能接收也不能返回 Substrate 值（DSH6253）。

[!NOTE] 主材质靠「两个 closure 上的静态开关」从静态参数里选着色变体：UMaterialExpressionStaticSwitchParameter 在引擎构建材质 拓扑树时就决出布尔值、只下降到选中的分支，所以翻译器看到的仍是一个拓扑。 UE.StaticSwitchParameter 不比较两条分支， 所以一边是 Substrate 值、一边是数值时 DreamShader 不会报错。

节点参考

Substrate.ShadingModels

用 Substrate 材质表达的传统着色模型表面。

输出：Substrate 值。编辑器补全不为这个包装节点提供任何参数。

Substrate.Slab

通用的 Substrate BSDF slab。

输出：Substrate 值。

Substrate.SimpleClearCoat

带固定第二层 clear coat 波瓣的 slab。

输出：Substrate 值。

Substrate.VolumetricFogCloud

用于体积雾和云材质的参与介质 BSDF。

输出：Substrate 值。

Substrate.Unlit

仅自发光 BSDF。最小的完整 Substrate 表面。

输出：Substrate 值。

Substrate.Hair

头发 BSDF。

输出：Substrate 值。

Substrate.Eye

眼睛 BSDF。

输出：Substrate 值。

Substrate.SingleLayerWater

单层水 BSDF。

输出：Substrate 值。

Substrate.LightFunction

用于光照函数材质的 Substrate 输出节点。

输出：Substrate 值。

Substrate.PostProcess

用于后处理材质的 Substrate 输出节点。

输出：Substrate 值。

Substrate.UI

用于 UI 域材质的 Substrate 输出节点。

输出：Substrate 值。

Substrate.ConvertMaterialAttributes

把一个 MaterialAttributes 值转换成 Substrate 材质。

输出：Substrate 值。

MaterialAttributes 是反射属性名，Attributes 是引擎给同一个输入起的 pin 名；两者都绑定 input 0。传数值进去是 DSH5214。参见 MaterialAttributes。

Substrate.ConvertToDecal

把 Substrate 材质转换成贴花材质。

输出：Substrate 值。

Substrate.HorizontalMix

在屏幕空间水平混合两个 Substrate 材质。也可以写成 Substrate.HorizontalMixing —— 两个名字可以互换。

输出：Substrate 值。

Substrate.VerticalLayer

把一个 Substrate 材质叠在另一个之上。也可以写成 Substrate.VerticalLayering —— 两个 名字可以互换。

输出：Substrate 值。

Substrate.Add

相加两个 Substrate 材质。

输出：Substrate 值。

Substrate.Weight

缩放一个 Substrate 材质的贡献。

输出：Substrate 值。

Substrate.Select

在两个 Substrate 材质之间做静态选择。

输出：Substrate 值。

Substrate.TransmittanceToMFP

工具。把透射颜色和厚度转换成平均自由程参数化。

输出 —— 数值，可用 Output= 或 OutputIndex= 选择：

Substrate.MetalnessToDiffuseAlbedoF0

工具。把传统的 base color / metallic / specular 三元组转换成 slab 参数化。

输出 —— 数值：

Substrate.HazinessToSecondaryRoughness

工具。把 haziness 控制量转换成第二粗糙度波瓣。

输出 —— 数值：

Substrate.ThinFilm

工具。计算薄膜干涉的高光颜色。

输出 —— 数值：

绑定 Substrate 值到 Base.FrontMaterial

Substrate 材质经由 Base.FrontMaterial 输出绑定进入生成的 UMaterial。

Outputs = {
    Substrate Surface;              // declared-type token; case-insensitive, no other spelling
    Base.FrontMaterial = Surface;
}
Graph = {
    Surface = Substrate.Unlit(EmissiveColor = Color);
}

[!NOTE] Strata 是改名前的拼写。它被接受为 Settings = { ShadingModel = … } 值 （同一着色模型的别名），但永远不能作为类型 token，也不能作为调用命名空间。 参见枚举取值。

说明

• 每个 Substrate 类都是一个名字。 在目录中没有行的类，按派生的名字调用 —— UE 5.8 上为 Substrate.Toon —— 或通过 UE.Expression(Class = "SubstrateToonBSDF", …) 按其类调用，后者可解析 SubstrateToonBSDF、 MaterialExpressionSubstrateToonBSDF、UMaterialExpressionSubstrateToonBSDF 以及完整的 /Script/Engine.… 路径 （自 2.0.0 起）。参见 UE.Expression。
• UE.* 名称在此命名空间内不适用。 Substrate.TexCoord(…) 并不存在；该命名空间 没有的名字属于 DSH5210。
• Substrate 节点参与节点复用：两个参数值完全相同的 Substrate.Slab(…) 调用是同一个节点。参见节点复用。
• GraphFunction 体内的 Substrate. 调用不会被提升为 节点输入，因为没有 Custom 节点输入承载 Substrate 值；它留在 HLSL 文本中，并给出警告 DSH6316。
• 反编译器能把现有 Substrate 图导出回源码， 并根据每条连接的写掩码推导通道 swizzle （自 1.5.0 起），且按源码使用的名字写出每个节点 —— 参见反编译。
• Substrate.* 接口导出给编辑器工具，以 Saved/DreamShader/Bridge/substrate-builtins.json （schema DreamShader.SubstrateBuiltins，版本 1），每个名字一条，含其 qualifiedName、className、outputType、 isSubstrateOutput 和精选的 parameters。参见 Bridge。

诊断

每个代码及其消息和完整说明都列在 诊断中的各自页面上。

调用点

管线其他环节中的 Substrate 值

示例

Shader(Name="Docs/M_Substrate")
{
    Properties = {
        vec3  BaseColor = vec3(0.6, 0.1, 0.1);
        float Metallic  = 0.0;
        float Specular  = 0.5;
        float Rough     = 0.3;
        vec3  Glow      = vec3(0.1, 0.6, 1.0);
    }

    Outputs = {
        Substrate Surface;
        Base.FrontMaterial = Surface;
    }

    Graph = {
        // Utility node: two numeric outputs, selected by name.
        vec3 Albedo = Substrate.MetalnessToDiffuseAlbedoF0(
            BaseColor = BaseColor, Metallic = Metallic, Specular = Specular,
            Output = "DiffuseAlbedo");
        vec3 F0 = Substrate.MetalnessToDiffuseAlbedoF0(
            BaseColor = BaseColor, Metallic = Metallic, Specular = Specular,
            Output = "F0");

        Substrate Body = Substrate.Slab(
            DiffuseAlbedo = Albedo,
            F0            = F0,
            Roughness     = Rough);

        Substrate Emissive = Substrate.Unlit(EmissiveColor = Glow);

        Surface = Substrate.Add(A = Body, B = Emissive);
    }
}

生成的节点：

SubstrateMetalnessToDiffuseAlbedoF0   -> output "DiffuseAlbedo"  -> Albedo
                                      -> output "F0"             -> F0
                                         (one node, read for both)
SubstrateSlabBSDF                     -> Body                    (Substrate value)
SubstrateUnlitBSDF                    -> Emissive                (Substrate value)
SubstrateAdd                          -> Surface                 (Substrate value)

自 2.0.0 起，同一张图可写为 Surface = Substrate.Slab(BaseColor = BaseColor, Metallic = Metallic, Specular = Specular, Roughness = Rough) + Substrate.Unlit(EmissiveColor = Glow); —— 虚拟参数把转换节点放在 slab 前面，+ 就是 Substrate.Add。

另请参见

• 内置 — Graph 内可用的调用接口
• UE.* 目录 — 同级的命名空间
• UE.Expression — 每次节点调用共用的绑定规则
• Substrate 语法糖 — 运算符、lerp、分支、虚拟参数、构建器、Substrate =
• OutputType 值 — 在这个命名空间上被舍弃
• 数学内置 — 无前缀的数值调用接口
• 变换内置 — UE.TransformVector / UE.TransformPosition
• 输出绑定 — Base.FrontMaterial 与完整的绑定目标列表
• MaterialAttributes — ConvertMaterialAttributes 消费的值类型
• 类型 — Substrate 声明类型 token
• 枚举值 — ShadingModel = "Substrate" / "Strata"
• 调用 — 命名参数语法
• 节点复用 — 相同的调用与节点
• Bridge — substrate-builtins.json 与编辑器补全清单
• 反编译器 — 把已有的 Substrate 图导回源码
• 诊断索引 — 每一种代码