参数节点标记

DreamShader » 参数 » 参数节点标记

这 22 个类型标记直接指定 Unreal 参数表达式类的名称，因此一个 Properties 声明会生成该精确节点，而不是紧凑的标量 / 向量 / 纹理对象节点。

概要

<parameter-node-token> <name> [ = <default> ] [ [ <metadata> ] ] ;

标记按不区分大小写方式匹配。该集合是封闭的：恰好为下面这 22 个标记。 const 仅对 ScalarParameter、VectorParameter 和 TextureObjectParameter 合法 (自 2.0.0 起)；用于任何其他标记时属于 DSH3253。

这 22 个标记

(自 2.0.0 起) 每个标记采用三种 2.0 形式之一：

• 声明 — ScalarParameter、StaticBoolParameter、VectorParameter 和 TextureObjectParameter 是紧凑标记会生成的 uniform（float、一个 /// @static bool、float4、Texture2D），无论读取多少次都只有一个参数节点；
• 每次使用展开 — 其余构建时不作为声明的十一个标记：对属性的每次读取或调用都是一次反射 UE.Expression(Class = "<Token>", ParameterName = …, …) 调用， 携带默认值和元数据，相同的使用共享一个节点；
• 无 2.0 写法 — 有七个标记为 DSH3253。请将此类材质迁移到 .dss，并使用 UE.Expression 构建节点。

展开标记的类会在引擎的节点目录中查找；此引擎没有的类属于 DSH5212。Graph 使用情况在此概述； 引脚表位于在 Graph 中使用参数。

类型特定的元数据槽

每个标记还接受通用元数据键（Group、Description、SortPriority、 Slider(min, max)、ParameterName）以及其类的任何反射 UPROPERTY。实际中重要的 类特定槽：

布尔 UPROPERTY 匹配时开头的 b 可选，因此 [bBlend=true] 和 [Blend=true] 都会绑定 bBlend。类不具有的键如何报告取决于形式：声明上为警告， 展开标记上为错误 — 参见元数据。

标记使用哪种默认解析器

[!WARNING] RuntimeVirtualTextureSampleParameter 或 SparseVolumeTextureSampleParameter 默认值会被 忽略。 对任一标记使用 = Path(…) 不会触及该节点的任何属性，而且不会有任何提示。请改为 通过元数据绑定资产 — [VirtualTexture = Path(…)]、[SparseVolumeTexture = Path(…)]。

默认值写入到何处

纹理维度推断

纹理采样标记通过 TextureSampleParameter 之后的后缀确定维度：

(自 2.0.0 起) 后缀按整体比较，因此 TextureSampleParameterCubeArray 不再被视为立方体贴图。维度只用于一件事：判断 Class'…' 默认值所指定的类。

TextureObjectParameter 声明没有维度：它采用其默认值所加载资产的维度 — 立方体贴图、2D 数组或体积纹理，否则为 Texture2D — 因此它可以接受其中任意一种 (自 1.6.0 起)。

维度验证的不对称性

[!WARNING] 通过其普通对象路径被赋予普通 2D 纹理的 TextureSampleParameterCube 在生成时不会产生 DreamShader 诊断；只有 Texture2D'…' shell 才会暴露这种不匹配 (DSH1044)。否则，这种不匹配会在之后作为材质上的 Unreal 着色器编译错误出现。 请赋予正确的维度。

说明

• 对于每个具有 2.0 形式的标记，默认值都是可选的。 测试 DreamShader.Lang.ParameterExpressions.ParseAll 覆盖全部 15 个标记，覆盖带内联默认值和不带内联默认值的 ScalarParameter、 VectorParameter 与 TextureObjectParameter，并检查 其余七个标记均为 DSH3253。
• 没有纹理的采样器参数仍然可以编译。 当展开节点派生自 UMaterialExpressionTextureBase 且其 Texture 为空时，会为 UMaterialExpressionTextureSampleParameter 子类调用 SetDefaultTexture()。否则，没有默认值的采样器参数 会以 Missing input Texture 失败。运行时虚拟纹理和稀疏体积节点并非 此类子类，仍然需要绑定其资产。
• 显式 SamplerType 始终优先。 AutoSetSampleType() 仅在源 未提供 SamplerType 的节点上运行。参见 SamplerType。
• StaticSwitchParameter 不能作为值读取。裸引用不是已声明的名称 (DSH4200)；它必须被调用。参见 在 Graph 中使用参数。
• Group(…) 作用域不会为展开标记盖章 (自 2.0.0 起)：此类成员不会从该作用域获得 分组，也不会自动获得 SortPriority，并且不会占用计数器槽位。请在其自身的元数据块中写入 Group / SortPriority。参见 元数据。
• 反编译器 在每次导出时都会显式输出 SamplerType 和纹理采样元数据键， 即使它们处于默认值，因此反编译 → 重新编译的往返过程是稳定的。

诊断

完整列表位于诊断索引。

示例

Shader(Name="Docs/M_ParameterNodes")
{
    Properties = {
        Group("Surface") {
            TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_White") [
                SamplerType  = "LinearColor";
                SamplerSource = "FromTextureAsset";
                MipValueMode = "None";
                AutomaticViewMipBias = true;
            ];
            ScalarParameter Roughness = 0.55 [Slider(0, 1)];
            VectorParameter Tint      = float4(1.0, 0.8, 0.6, 1.0);
        }

        Group("Masks") {
            ChannelMaskParameter         Pick = float4(1, 0, 0, 0) [MaskChannel = "Red"];
            StaticComponentMaskParameter Keep = float4(1, 1, 0, 0);
        }

        StaticSwitchParameter UseDetail = true [Group="Switches"];
    }

    Settings = { Domain = "Surface"; ShadingModel = "DefaultLit"; BlendMode = "Opaque"; }

    Outputs = {
        vec3  Color;
        float Rough;

        Base.BaseColor = Color;
        Base.Roughness = Rough;
    }

    Graph = {
        vec2  UV     = UE.TexCoord(Index = 0);
        vec4  Sample = BaseTex(Coordinates = UV);
        vec4  Masked = Keep(Input = Sample);
        float Chan   = Pick(Input = Sample);

        Color = UseDetail(True = Masked.rgb, False = Tint.rgb);
        Rough = Roughness * Chan;
    }
}

生成的节点：

TextureSampleParameter2D      BaseTex    SamplerType=LinearColor
ScalarParameter               Roughness  Group="Surface" SortPriority=0  SliderMin=0 SliderMax=1
VectorParameter               Tint       Group="Surface" SortPriority=10
ChannelMaskParameter          Pick       MaskChannel=Red
StaticComponentMaskParameter  Keep
StaticSwitchParameter         UseDetail  Group="Switches"
TextureCoordinate             UV         CoordinateIndex=0

BaseTex、Pick 和 Keep 是展开标记，因此它们的 Group(…) 作用域不会为其盖章， Roughness 占用计数器槽位 0。Keep 的 float4 默认值会随 DSH5288 被丢弃：请为该遮罩写入 [DefaultR = true; DefaultG = true]。

另请参见

• 参数 — 中心页面与决策表
• 紧凑类型标记 — 39 个内置标记及其所受检查
• 元数据块 — [MaskChannel=…] 及所有其他键的写入方式
• SamplerType — 每个采样器类型值，以及 SamplerSource
• Path(…) — 这些默认值所使用的资产引用语法
• 在 Graph 中使用参数 — 读取、引脚调用形式，以及 StaticSwitchParameter
• 属性（章节） — 外层章节语法
• UE.Expression — 没有标记的类的通用反射形式
• 反编译器 — UMaterial 导出会生成这些标记中的哪些
• 测试 — 固定此表的参数矩阵夹具