名称解析

DreamShader » Graph » 名称解析

在 Graph 块内，裸标识符和调用目标是如何被查找的，按照编译器尝试它们的固定顺序，以及每个层面会遮蔽什么。

名称的查找分为两个阶段 (自 2.0.0 起)。旧版前端在解析时会读取若干 1.x 写法——布尔字面量、类型名称、N::F、1.x 调用简写以及会变成节点的属性——而 2.0 绑定器会以与处理 .dss 相同的方式解析其余所有内容。绑定器以区分大小写的方式比较名称；当名称仅在大小写上不同但仍匹配时，1.x 源码仍会通过旧版规则 L19 构建成功，并会就此发出警告。

概要

存在两个不同的阶梯。运行哪一个完全取决于名称后面是否跟着 (。

<identifier>                 // bare-identifier ladder
<identifier> ( … )           // call-name ladder
<identifier> :: <identifier> ( … )   // call-name ladder, qualified callee

Common::ApplyTint 被读取为单个标识符 Common_ApplyTint，即命名空间函数声明时所用的名称。UE.TexCoord 和 Substrate.Slab 是节点调用。不属于以上任何一种的被调方——比如对括号表达式调用——是 DSH4208。

裸标识符

步骤 1–3 在任何变量已知之前运行，因此它们会胜过同名的变量。在步骤 6 读取的属性每次都是参数节点；在去重过程之后，相等的节点为一个节点。步骤 7 需要唯一匹配：当两个声明在忽略大小写时匹配，则二者都不会被选中，该名称为 DSH4200。

[!NOTE] StaticSwitchParameter 属性故意不会作为裸标识符解析——它需要它的两个分支。按名称读取它会失败并给出 DSH4200。请使用调用形式 Switch(True = …, False = …)；参见调用。

调用名称

严格按照此顺序探测。第一个认领该名称的层面胜出；后续层面永远不会被查询。

绑定器精确比较节点前的 UE (自 2.0.0 起)：ue.TexCoord() 会把 ue 读取为未声明名称 DSH4200。

内置函数直接认领其名称。格式错误的 clamp(x) 是该内置函数的参数数量错误 DSH4224；不存在同名的用户函数可供回退，因为声明一个用户函数是 DSH6206。

在步骤 11 没有需要解决的歧义：一个名称声明一个事物，而某个名称的第二次声明在声明处就是 DSH4210 (自 2.0.0 起)。

每种声明类型如何被匹配

生成的 HLSL 符号 DreamShaderFn_<name> 不再是调用可使用的名称 (自 2.0.0 起)。

这里是没有重载解析：名称不会按元数或参数类型划分作用域。导入的标头被声明进文件中，而不是作为文本粘贴进去，且它声明的名称不可以被再次声明：DSH4210 同时命名两个文件。此处名称同样区分大小写比较，因此 Foo 和 foo 是两个函数*（自 2.0.0 起；1.x 曾将它们报告为声明了两次）*，而 N::F 与一个名为 N_F 的函数是同一个名称，DSH4210。

带命名空间的函数只能通过 N::F 或其读取形式 N_F 访问。这里没有 using 风格的导入，也没有无限定的回退。

遮蔽

因为层级是严格有序的，"遮蔽"总是单向进行：靠前的表层隐藏靠后的表层，绝不会反过来。

[!WARNING] 遮蔽构造函数是静默的。Function vec3(in float x, out float3 r) 会被解析、被声明，并且 在 Graph 块中根本不会被调用 —— 每次 vec3(…) 调用都会构建一个构造函数。请重命名该 函数。

标识符大小写

[!NOTE] 以与声明不同的大小写写出的名称就是该声明，并带有 DSH5275。 float3 Color = …; 后跟 color = …; 写出 Color（自 2.0.0 起；1.x 曾创建名为 color 的第二个条目）。只有在任何大小写下都不匹配任何内容的名称才会由赋值声明（旧 规则 L26，信息 DSH5292）。dsc migrate 会按照每个此类 名称被声明的方式重新拼写它。

命名参数匹配

参数名称会精确比较。函数的参数名称会以 DSH5275 回退到唯一的不区分大小写匹配，节点的引脚和 属性名称会以 DSH5276 回退；内置函数的参数名称没有回退。上述 1.x 伪参数在匹配时忽略大小写。 位置参数在前面并按顺序填充参数；位于命名参数之后的位置参数是 DSH2158（自 2.0.0 起）。

哪些被调用者接受命名参数已记录于 调用。

诊断

示例

import "Helpers.dsh";

Shader(Name="Docs/M_Resolution")
{
    Properties {
        vec3                  Tint    = vec3(1.0, 0.5, 0.2);
        StaticSwitchParameter UseTint = true;
    }

    Settings { Domain = "UI"; ShadingModel = "Unlit"; }

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

    Graph {
        // 'Tint' is the file-scope property: a VectorParameter node.
        vec3 Base1 = Tint;

        // 'TINT' matches 'Tint' only ignoring case: the same parameter, warning DSH5275.
        vec3 Base2 = TINT;

        // 'lerp' is the builtin; a function of that name in Helpers.dsh would be DSH6206.
        vec3 Mixed = lerp(Base1, Base2, 0.5);

        // A namespaced Function needs its full name.
        vec3 Lit = Common::ApplyTint(Mixed, Tint);

        // 'UseTint' is a StaticSwitchParameter: callable, not readable.
        Color = UseTint(True = Lit, False = Mixed);
    }
}

解析轨迹：

Tint                  -> bare 6   file-scope property               -> VectorParameter node
TINT                  -> bare 7   'Tint', ignoring case (DSH5275)   -> the same node
lerp(...)             -> call 9   math builtin                      -> LinearInterpolate node
Common::ApplyTint(..) -> call 3   read as Common_ApplyTint
                         call 11  Function (namespaced)             -> Custom node
UseTint(True=,False=) -> call 4   StaticSwitchParameter             -> StaticSwitchParameter node
UseTint               -> (bare read) ERROR: DSH4200

另请参阅

• 调用 — 每个表面接受的调用形式，以及所有调用诊断
• 表达式 — 标识符和被调用者在语法中出现的位置
• 声明 — Graph 变量如何声明
• 构造函数 — 保留的构造函数拼写
• 数学内置项 — 保留的内置项拼写
• UE 内置项 — 按前缀声明的 UE.* 表面
• Substrate 内置项 — Substrate.* 表面
• Graph 中的参数 — 读取参数和引脚调用形式
• Namespace — 声明 Namespace::Name 以及禁止嵌套规则
• 词法元素 — 声明语法的完整大小写敏感性矩阵
• 节点复用 — 相等节点如何合并
• dsc migrate — 本页每条旧规则的 .dss 拼写