C++ API

DreamShader » C++ API

该插件公开的 C++ 接口面：五个模块、69 个公共头文件，以及每个调用方都要经过的一个编译接口。

模块

这五个模块都在 DreamShader.uplugin 中声明。DreamShaderLang、DreamShader 和 DreamShaderPass 在 PostConfigInit 加载 —— 足够早，使设置对象与着色器目录映射在任何事物请求它们之前就已存在； 对于 DreamShaderPass，还早于引擎确定其着色器类型列表的时间（其全局着色器类型会在模块加载时加入该列表）—— 而两个 Editor 模块则在 Default 加载。DreamShaderLang 在描述符中列于首位：其他所有模块都直接或通过 DreamShader 依赖它，单靠加载阶段无法确定它们的顺序。基于同样的原因，DreamShaderPass 跟在 DreamShader 之后，DreamShaderCompiler 列在 DreamShaderEditor 之前；在编译器启动之前运行的调用方仍然能获得一个：GetDreamShaderCompiler() 会按需加载 该模块。 插件为 EnabledByDefault 和 CanContainContent；IsBetaVersion 为 false。

公共头文件

命名空间：DreamShaderModule.h、DreamShaderTypes.h、 DreamShaderCompilerInterface.h、DreamShaderDefineResolution.h、DreamShaderDefineTable.h 和 DreamShaderPreprocessor.h 中的所有内容都位于 UE::DreamShader 中——在 2.0 中迁移到 DreamShaderLang 的那两个保留了该命名空间，因此它们的调用方无需更改源码。语言位于 UE::DreamShader::Lang 和 UE::DreamShader::IR；编译器模块是 UE::DreamShader::Editor::Compiler。FDreamShaderModule、FDreamShaderCompilerModule、 UDreamShaderSettings、UDreamShaderMaterialInstance 和 EDreamShaderDefaultBackend 位于全局 作用域。DreamShaderPass （自 2.1.0 起） 将其反射类型——UDreamPassPipeline、 UDreamPassSubsystem、ADreamPassVolume、EDreamPass* 枚举和 FDreamPass* 结构体——置于全局 作用域（反射类型必须如此），并将其自由函数置于 UE::DreamPass 中。

链接

[!WARNING] DreamShaderEditor 不导出任何内容，无法被链接。 它根本没有 Public/ 文件夹， 其 Build.cs 未声明任何 PublicDependencyModuleNames，而 DREAMSHADEREDITOR_API—— UnrealBuildTool 为每个模块都会定义——在插件源码中零次出现。 其模块类 FDreamShaderEditorModule 声明于 .cpp 内部，而非头文件中，因此 也无法从外部命名。编辑器模块所做的一切只能通过 UE 的模块系统、通过 UI 操作或通过 commandlet 访问。 编译已不再属于这些操作：自 2.0 起编译器是独立模块，通过 IDreamShaderCompiler 访问。

UE_PLUGIN_NAME 对全部五个模块均为 "DreamShader"。

这些头文件均未用 #ifndef 保护其导出宏；它们都依赖 UBT 生成的定义。

不存在模块单例

该插件未在任何模块类上声明 Get()、IsAvailable() 或 GetChecked() 访问器。请使用标准的模块管理器——或者对于编译器，使用 GetDreamShaderCompiler()，这是该插件唯一的注册表：

FDreamShaderModule& Module = FModuleManager::LoadModuleChecked<FDreamShaderModule>(TEXT("DreamShader"));

实际上，模块对象本身并不需要任何东西——只要模块加载完成，UE::DreamShader 中导出的自由函数即可使用。

构建依赖

DreamShader.Build.cs

DreamShaderPass.Build.cs

（自 2.1.0 起）

引擎门控位于构建规则中，而不是描述符中，描述符没有按模块的引擎字段，并且该定义是公开的，以便 DreamShaderCompiler 和 DreamShaderEditor 询问同一问题，而不是再次推导它。

DreamShaderCompiler.Build.cs

这些公共依赖之所以是公共的，是因为公开头文件暴露了它们：UMaterial* 和 EMaterialProperty（Engine）、FTextShaderDefinition 以及编译接口（DreamShader）、 FLangDiagnosticSink / FModule / FIRModule（DreamShaderLang）。Editor 类型的模块不能 作为 Runtime 模块的依赖，这就是接口本身位于 DreamShader 的原因。

DreamShaderPass、RenderCore、RHI 和 TargetPlatform 是 .dsp 的另一半 (自 2.1.0 起)： DreamShaderPass 用于 .dsp 编译成的资产、其设置及其槽路径；另外三个用于 HLSL 槽——着色器源映射、预检查的进程内编译、它按名称找到的全局着色器类型、 着色器平台以及目标平台烘焙的格式。该模块没有任何公开头文件 提及它们，因此它们是私有的。

DreamShaderEditor.Build.cs

插件依赖

DreamShader.uplugin 恰好启用了两个其他插件。二者仅由 DreamShaderEditor 使用。

页面

说明

• 请求编译只需要运行时模块。 GetDreamShaderCompiler() 会返回编辑器端注册的编译器，若不存在则返回 null（游戏目标）。生成本身仅限编辑器，位于 DreamShaderCompiler。
• 该语言与引擎无关。 DreamShaderLang 中的所有内容——解析任一语法、绑定、降级为 IR、打印、迁移——都是对 Core 的字符串和数据处理；它不会创建任何 UObject，也不会加载任何资产。绑定需要一个 FBuiltinCatalog，dsc export-catalog 将其写为 JSON，供在编辑器外部运行的工具使用。
• DreamShader 导出两个 UCLASS，即 UDreamShaderSettings 和 UDreamShaderMaterialInstance。DreamShaderPass （自 2.1.0 起） 通过 DREAMSHADERPASS_API 导出七个——管线、设置、子系统、体积、两个组件和蓝图库——并声明其两个材质表达式 MinimalAPI。UDreamShaderCommandlet 存在于编辑器模块的 Private/ 文件夹中，没有 API 宏，因此只能通过 UE 的反射系统和 -run=DreamShader 访问。
• Config/FilterPlugin.ini 仅包含自带的带注释模板——该插件未声明任何额外的打包文件。

示例

一个希望解析 DreamShaderLang 并请求编译的使用方模块：

// MyTooling.Build.cs
PrivateDependencyModuleNames.AddRange(new[]
{
    "Core",
    "CoreUObject",
    "Engine",
    "DreamShaderLang",      // the language: parse, print, bind, IR
    "DreamShader"           // paths, settings, the compile interface
});

#include "DreamShaderCompilerInterface.h"
#include "DreamShaderModule.h"
#include "Lang/LangParser.h"

using namespace UE::DreamShader;

void InspectSource(const FString& InPath)
{
    if (!IsDreamShaderSourceFile(InPath))
    {
        return;
    }

    FString SourceText;
    const FString Path = NormalizeSourceFilePath(InPath);
    if (!FFileHelper::LoadFileToString(SourceText, *Path))
    {
        return;
    }

    // Auto picks the front end from the extension: .dss / .dsi / .dsp / .dsh are 2.0, .dsm / .dsf are 1.x.
    const Lang::FLangSourceText Source(Path, SourceText);
    const Lang::FLangParseResult Parsed = Lang::ParseDreamShaderLang(Source);
    UE_LOG(LogDreamShader, Display, TEXT("%s: %d declaration(s), %d diagnostic(s)."),
        *Path,
        Parsed.Module.IsValid() ? Parsed.Module->Declarations.Num() : 0,
        Parsed.Diagnostics.GetDiagnostics().Num());

    if (Parsed.Succeeded())
    {
        if (IDreamShaderCompiler* Compiler = GetDreamShaderCompiler())
        {
            FDreamShaderCompileRequest Request;
            Request.SourceFilePath = Path;
            Compiler->CompileAssets(Request);
        }
    }
}

ParseDreamShaderLang 不读取文件，也不遵循 #include / import：包含在绑定时解析，由宿主交给绑定器的解析器完成。

另请参阅

• DreamShaderModule.h —— 模块入口点及其导出的辅助函数
• DreamShaderCompiler —— 编译接口、服务和管线
• DreamShaderPass —— Custom Pass 运行时
• 项目设置 —— 从用户角度看的 UDreamShaderSettings
• 生成 —— 发出的资产是什么样子
• Commandlet —— -run=DreamShader，无头入口点
• 编辑器桥接 —— WebSocket 服务器和请求文件协议
• 工作区 —— bridge.db 缓存和导出的清单
• 贡献 —— 从源码构建插件