DreamShaderLang

DreamShader » C++ API » DreamShaderLang

DreamShaderLang 是前端也是中端：文本输入，输出的是降低后的图——反过来也一样。词法分析器、预处理器、两个解析器（2.0 和 1.x 旧版前端）、AST、打印器、绑定器、带各遍处理的图 IR、验证器和比较器、把 IR 变回源码的写出器、1.x → 2.0 迁移器，以及诊断类型都在这里——除此之外再无他物。它是为 2.0 从 DreamShader 中拆分出来的，这样语言就可以在没有编辑器的情况下被演练、被语言服务复用，并作为一门语言而非一个插件来被推演。

该模块不跨越的那条线是引擎：一个 FIRModule 不指名任何 UObject、任何资产，也不指名任何表达式类对象。引擎知识以纯数据的形式，在一个 FBuiltinCatalog 中抵达；后者由 Editor 模块通过反射填充，也可以保存到 JSON，以及从 JSON 加载。

仅依赖 Core 的规则

DreamShaderLang.Build.cs 只声明一个依赖：

PublicDependencyModuleNames.AddRange(new[] { "Core" });

这是一条硬性边界，而不是当前状况：

• 没有 UObject，没有 Engine，没有 CoreUObject。 该模块中没有任何东西可以指名 UMaterial、UMaterialExpression 或资产路径类型。
• 没有 IPluginManager，没有 GetDefault<>()，没有配置访问。 该模块无法查找任何关于其运行所在项目的信息。
• 引擎事实以参数形式抵达。 DS_* 预处理器常量、资产根和表达式类名由宿主以纯数据形式提供——DreamShader 模块中的 DreamShaderDefineResolution.h 是通过询问引擎来构建定义表的那一半；DreamShaderLang 只消费它。
• 每个头文件都能在 commandlet、测试或未来的独立语言服务器中编译。 前端不创建任何对象，也不触碰任何文件：FLangSourceText 拿到的是别人已经读取的文本。

公共头文件

Lang/ — 2.0 前端

这里的一切都在 UE::DreamShader::Lang 中。包含路径保留 Lang/ 前缀，例如 #include "Lang/LangParser.h"。

Semantic/ — 绑定器

UE::DreamShader::Lang，一个头文件。绑定是介于“它能解析”和“它能被降低”之间的步骤：每个名字都得到解析，每个表达式都得到类型，每次调用都与某个签名或目录相匹配，文件的产物也被决定。

已绑定的模块会保留指向它所绑定的 FModule 以及 include 解析器返回的任何内容的指针；两者都必须比它存活更久。构建器下游的任何内容都不这样做 —— 一个 FIRModule 两者都不指回。

IR/ —— 图 IR

UE::DreamShader::IR，十二个头文件。IR 是成为材质图之前的材质图：节点、操作数、属性和产物，其中没有任何引擎类型。include 路径保留 IR/ 前缀。

IR 在其标识中不保存源位置：FIRSourceRef 搭载在节点上供工具使用 （资产的 DreamShader.SourceSpans 表、节点 ↔ 源导航），并且从不属于 去重键的一部分。两个结构相同的节点无论写在哪里都会合并。

Decompile/ 和 Migrate/ —— 返回之路

UE::DreamShader::Lang，各一个头文件。两者都不知道资产：编辑器模块将图导入 FIRModule 并移交。

模块根 —— 2.0 中移到此处的部分

下面四个头文件中有三个在 1.9.x 之前位于 DreamShader 模块中，并在 2.0 中移入 DreamShaderLang。它们保留了 UE::DreamShader 命名空间和 include 路径，因此 现有调用者无需更改源代码 —— 只需在其 Build.cs 依赖列表中添加一个 DreamShaderLang 条目。DreamShaderLangModule.h 是 2.0 中新增的。

FDreamShaderError（1.x，FString/FText 消息）与 FLangDiagnostic（2.0，代码 + 严重级别 + FText + 跨度）是刻意共存的：1.x 管线仍然携带前者，而 2.0 前端 从不产生它。它们之间不会隐式转换。

入口点

该模块是一条由六次调用组成的管线——预处理、词法分析、解析、绑定、降级、运行各趟处理——外加一个 验证器、两个转储、一个打印器，以及一个用于单独解析单个表达式的调用。

// MyTooling.Build.cs:  PrivateDependencyModuleNames.AddRange(new[] { "Core", "DreamShaderLang" });

#include "Lang/LangParser.h"
#include "Lang/LangPrinter.h"

using namespace UE::DreamShader::Lang;

void Normalise(const FString& Path, const FString& Text)
{
    const FLangSourceText Source(Path, Text);
    const FLangParseResult Result = ParseDreamShaderLang(Source);

    for (const FLangDiagnostic& Diagnostic : Result.Diagnostics.GetDiagnostics())
    {
        UE_LOG(LogTemp, Warning, TEXT("%s(%d,%d): %s"),
            *Diagnostic.FilePath, Diagnostic.Span.Line, Diagnostic.Span.Column,
            *FLangDiagnosticSink::ToWireString(Diagnostic));
    }

    if (Result.Succeeded())
    {
        const FString Printed = PrintDreamShaderLang(*Result.Module);
    }
}

前端选择

FLangParseOptions::Frontend 默认为 ELangFrontend::Auto，它根据 FLangSourceText::GetPath() 所携带的文件扩展名进行判断：

旧版前端将 1.x 构造降到相同的 AST 节点类型上——一个 Shader 块 变成 uniform、一个 #pragma material 和一个导出函数——因此下游无需知道 是哪个解析器生成了模块。1.x 文本在此之外所述内容（块名、节、重命名、 输出选择）随树一起保存在 FLangParseResult::Legacy 中，而声明携带 bLegacy，这正是绑定器对其（且仅对其）应用文档化 1.x 规则的原因。

打印器契约

打印器的承诺是结构保真，而非文本保真：parse(print(parse(X))) 产生的树与 parse(X) 相同。具体而言——在 FParenExpr 记录的位置以及优先级要求的位置发出括号；/// 块在自由文本之后按每行一条指令重新发出；不透明（/// @custom）主体从 RawBody 原样写出；pragma 和 include 保留其拼写；字面量保留书写时的词素，因此 1.0f、0x10 和 2u 都能保留。除 /// 以外的注释在解析保留它们时会被重现：使用 FLangParseOptions::bKeepTrivia 时，每条 注释和空行都附着到它旁边的声明或语句上 （FModule::Trivia），打印器会将它们写回——这正是 dsc migrate 能够承诺 不丢失任何注释的原因。不使用该选项时，它们会像以前一样被丢弃。

FLangPrintOptions::NewLine 默认为 \n，但不透明主体是其源文件的一个切片， 保留该文件的终止符，因此打印一个 CRLF 文件会产生混合终止符。这是稳定的： 下一次解析会切出相同的字节，因此固定点仍然成立。

不透明主体

一个函数的 /// 块携带 @custom 时，其主体被原样捕获：FFunctionDecl::Body 为 null，bOpaqueBody 为 true，RawBody 是花括号之间的文本，BodySpan 覆盖 含花括号的范围。解析器只读取花括号——它们必须成对平衡，而其中的字符串、注释和 # 行不会破坏平衡，因为词法分析器已把每一个都变成单个 token。

由于该文本不是 DreamShaderLang，ParseDreamShaderLang 丢弃每一个跨度起始于 BodySpan 内部的词法诊断。其中的 $、@、' 或行中 # 不是关于程序的事实， 由着色器编译器来判定。该抑制仅限于这些跨度： 在外部一行处的相同字符仍然是 DSH2101 / DSH2106。

诊断

每个抛出位置都字面地写出其代码，因此 .skill/gen-diagnostics.ps1 可以找到它：

Diagnostics.Error(TEXT("DSH2151"), Span, LOCTEXT("ExpectedExpression", "expected an expression"));

这些消息在每文件 LOCTEXT_NAMESPACE 下是 LOCTEXT，形式为 "DreamShader.Lang.<Unit>"，因此编辑器可以本地化它们。针对代码断言，绝不要针对 消息文本断言。

绑定器、构建器、各个 pass、验证器和自定义 HLSL 构建器都通过 同一个接收器抛出，各自带有自己的范围：

DSH1030–DSH1042（预处理器的自身代码）随预处理器一起移入此模块，并 保留了其编号。每个代码的说明文字位于诊断下。

测试：Lang 语料库

前端由数据驱动的语料库覆盖，而不是每个功能手写的测试。测试固件 位于 Tests/Corpus/Lang/ 下，每个功能一个 .dss 或 .dsh，每个可选择性地配对一个 <name>.expected.json 黄金文件；一个复杂的自动化测试在运行时枚举该树，并将 每个固件暴露为其自身的子测试。

每个用例都会通过 ParseDreamShaderLang 解析一次，然后与其黄金文件进行比对：

• outcome — ok 或 error。如果没有黄金文件，默认是“正向固件解析成功， *.bad.* 固件失败”。
• errorContains / warningsContain — 该严重级别下每条诊断的 FLangDiagnosticSink::ToWireString 的子字符串（大小写敏感）。在实践中： DSHnnnn 代码。
• module — 对解析后的 FModule 进行结构性计数：declarations（pragma 和 include 也会计数）、pragmas、includes、structs、uniforms（仅 Uniform 存储）、constants （仅 StaticConst）、functions（全部三种链接方式）、exports、externs、opaqueBodies、 entry（其签名为 void (inout material) 的第一个函数，无论链接方式如何） 以及 roundtrip。
• roundtrip — 打印 → 解析 → 打印逐字节相同，这就是打印器的契约以 测试形式表达出来。

为新构造添加覆盖就是往树中放入一个文件；无需 C++ 更改，无需重新编译。 以无头模式运行整个层：

"F:\UnrealEngine\UE_Moon\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" ^
  "I:\UnrealProject_Moon\DEV_58\MoonEngineSample\MoonEngineSample.uproject" ^
  -ExecCmds="Automation RunTests DreamShader.Lang2; Quit" ^
  -nullrhi -unattended -nopause -nosplash -log

添加 -DreamShaderUpdateGolden 会根据实际结果重写每个黄金文件，而不是进行断言。 提交前手动审查差异 — 这个开关正是回归变成基线的方式。

除了语料库之外，每个前端单元都有自己的专注测试文件 （DreamShaderLangLexerTests.cpp、…DeclarationTests.cpp、…ExpressionTests.cpp、 …PrinterTests.cpp），全部位于 DreamShader.Lang2.* 下。

另请参阅

• 2.0 管线做了什么 — 从作者视角看的语言表面与管线限制
• C++ API 索引 — 其他四个模块
• Custom Pass 管线 — 从作者视角看的 .dsp 语言
• 预处理器 — 从语言视角记录的 #if 和定义表
• 诊断索引 — 每个 DSHnnnn 及其原因和修复
• 测试 — 自动化套件与固件语料库