DreamShaderVersionCompat.h

DreamShader » C++ API » DreamShaderVersionCompat.h

十三个预处理宏，用于控制插件中所有依赖引擎版本的行为——此外，在该头文件之外还有一个模块定义：Custom Pass 开关，DREAMSHADER_WITH_CUSTOM_PASS。本页是手册中所有 (自 UE 5.x 起) 标记的唯一事实来源。

定义于头文件 DreamShaderVersionCompat.h。

概要

所有其他宏都基于的版本运算。使用它的功能开关位于下方宏一节。

#include "Misc/CoreDelegates.h"
#include "Runtime/Launch/Resources/Version.h"

#ifndef DREAMSHADER_UE_MAJOR
#define DREAMSHADER_UE_MAJOR ENGINE_MAJOR_VERSION
#endif

#ifndef DREAMSHADER_UE_MINOR
#define DREAMSHADER_UE_MINOR ENGINE_MINOR_VERSION
#endif

#ifndef DREAMSHADER_UE_PATCH
#define DREAMSHADER_UE_PATCH ENGINE_PATCH_VERSION
#endif

#ifndef DREAMSHADER_WITH_SUBSTRATE_BUILTINS
#define DREAMSHADER_WITH_SUBSTRATE_BUILTINS (DREAMSHADER_UE_MAJOR > 5 || (DREAMSHADER_UE_MAJOR == 5 && DREAMSHADER_UE_MINOR >= 4))
#endif

#define DREAMSHADER_UE_VERSION_AT_LEAST(MajorVersion, MinorVersion) \
    (DREAMSHADER_UE_MAJOR > (MajorVersion) || (DREAMSHADER_UE_MAJOR == (MajorVersion) && DREAMSHADER_UE_MINOR >= (MinorVersion)))

#if DREAMSHADER_UE_VERSION_AT_LEAST(5, 4)
#define DREAMSHADER_ALLOW_SHRINKING_NO EAllowShrinking::No
#else
#define DREAMSHADER_ALLOW_SHRINKING_NO false
#endif

宏

六个受 #ifndef 保护的宏可由构建目标预先定义——例如在 5.4+ 引擎上通过定义 DREAMSHADER_WITH_SUBSTRATE_BUILTINS=0 来排除 Substrate 路径，或在测试时强制某个版本分支。DreamShader.Build.cs 正是利用这一点，根据其头文件探测来设置 DREAMSHADER_WITH_MOON_ENGINE 和 DREAMSHADER_WITH_PARAMETER_COLLECTION_PARAMETERS。该插件仅有的其他定义是 DREAMSHADER_WITH_CUSTOM_PASS（DreamShaderPass.Build.cs 的一个 PublicDefinitions 条目，本头文件并未定义它，见下文），以及 MOON_ENGINE=1（当引擎的 SceneTypes.h 声明 MP_MoonEncodedAttribute0 时由 DreamShaderEditor.Build.cs 添加的一个 PrivateDefinitions 条目，且没有任何源文件读取它）。

[!NOTE] DREAMSHADER_ALLOW_SHRINKING_NO 没有任何行为差异。它存在仅仅是因为 UE 5.4 将 TArray::RemoveAt、TArray::Pop、FString::RightChopInline 和 FString::LeftChopInline 末尾的 bool bAllowShrinking 参数改成了 EAllowShrinking 枚举。两种写法都表示“不要缩减分配”。它在整个插件中使用，并非调节旋钮。

[!NOTE] 在该头文件之外的插件任何地方，都没有原始的 #if ENGINE_MAJOR_VERSION、ENGINE_MINOR_VERSION 或 UE_VERSION_NEWER_THAN 测试。唯一在该头文件之外的版本测试不是 C++：DreamShaderPass.Build.cs 读取 Target.Version 来设置 DREAMSHADER_WITH_CUSTOM_PASS。所有依赖版本的行为都通过这些宏或该定义实现，这正是下表能够穷尽列举的原因。

[!NOTE] (自 2.0.0 起) 当某个成员比最早支持的引擎还要新、且无人能说清它出现在哪个版本时，代码会去询问类型而非版本：在一个小模板中使用 if constexpr (requires { … })，并在已知存在该成员的引擎上用 static_assert 就同一问题做检查，这样拼写错误就不会被解读为“该引擎没有此成员”。这些位置列在询问类型一节下。

DREAMSHADER_WITH_CUSTOM_PASS

(自 2.1.0 起) Custom Pass 开关不在本头文件中。DreamShaderPass.Build.cs 根据所针对构建的引擎计算它，并将其添加到模块的 PublicDefinitions 中：

bool bForcedOff = Target.ProjectDefinitions.Any(Definition =>
    Definition == "DREAMSHADER_FORCE_NO_CUSTOM_PASS" || Definition == "DREAMSHADER_FORCE_NO_CUSTOM_PASS=1");
bool bWithCustomPass = !bForcedOff
    && (Target.Version.MajorVersion > 5 || (Target.Version.MajorVersion == 5 && Target.Version.MinorVersion >= 8));
PublicDefinitions.Add("DREAMSHADER_WITH_CUSTOM_PASS=" + (bWithCustomPass ? "1" : "0"));

该模块可在所有引擎上构建。其中每个反射类型都是纯数据，因此管线、设置、组件和体积可在任何受支持的引擎上加载和保存；在 5.8 以下它们不渲染任何内容。0 按模块编译掉的内容见 UE ≥ 5.8 —— DREAMSHADER_WITH_CUSTOM_PASS。

完整的版本门控行为

插件中由这些宏之一守护的每个位置，按其所要求的版本分组。 诊断信息以代码形式引用；下面仍然引用的字符串是日志行、材质编译错误 和 UI 文本，它们不携带代码。

由节点目录决定

(自 2.0.0 起) 1.x 生成器中由引擎版本控制的绝大部分内容已不再属于 DreamShader 的 门控。UE.* 和 Substrate.* 节点、它们的引脚和属性、 其枚举属性的值以及源可写入的材质属性都来自 内置目录， 该目录是从正在运行的引擎反射而来的（它已加载的每个非抽象 UMaterialExpression 类）。引擎没有的内容，目录不会列出，绑定器会这样说明：

用 dsc export-catalog 从较旧引擎导出的目录会给出相同的答案。 C++ 中剩余的门控就是下面这些。

UE ≥ 5.4 — DREAMSHADER_UE_VERSION_AT_LEAST(5, 4)

UE ≥ 5.4 — DREAMSHADER_WITH_SUBSTRATE_BUILTINS

Substrate 门控是一个单独的宏，因此可以独立覆盖，但其默认 阈值同样是 5.4。

UE ≥ 5.5

periodicworld 基础和 PeriodicWorldTileSize 参数在此处不再受门控 (自 2.0.0 起)：参见 由节点目录决定。

UE ≥ 5.6

firstperson 基础和 FirstPersonInterpolationAlpha 参数在此处不再受门控 (自 2.0.0 起)：参见 由节点目录决定。

[!NOTE] DREAMSHADER_ENGINE_EXPRESSION_CLASS 是链接期门控，不是编译期门控。UE 5.6 更改了 UHT，使其在导出 Z_Construct_<Class>_NoRegister 的情况下生成 DECLARE_CLASS2，因此 即使对于那些既不携带 MinimalAPI 也不携带 ENGINE_API 的 UCLASS()，StaticClass() 也能从插件中解析出来。UE 5.5 及更早版本生成 DECLARE_CLASS(..., NO_API)：GetPrivateStaticClass 永远不会 离开 Engine.dll，而命名 StaticClass() 可在所有引擎上编译，随后会以 LNK2019 失败。只有完整的 RunUAT BuildPlugin 才能看到它——针对单个引擎的 编辑器构建永远看不到。

对类型的询问

（自 2.0.0 起） 此处没有版本号：每一行由引擎自身类型是否有该成员决定—— 或者，（自 2.0.1 起），由引擎是否有该节点的头文件决定（__has_include）。

DREAMSHADER_WITH_PARAMETER_COLLECTION_PARAMETERS

（自 2.0.0 起）

UE ≥ 5.7

UE ≥ 5.8

UE ≥ 5.8 — DREAMSHADER_WITH_CUSTOM_PASS

（自 2.1.0 起） Custom Pass 整体。语言本身没有变化：.dsp 可在 所有引擎上解析和绑定，.dss 也是如此——变化的是引擎侧能够构建和运行的内容。

“自 UE 5.x 起”摘要

只有较新引擎才有的节点、引脚、枚举器和材质属性不在此表中： 运行中引擎的目录决定它们（见上文）。其他所有内容 在从 5.3 到 5.8 的每个引擎上表现一致。.dsp 是唯一一个在所有引擎上都解析和绑定 且仅在 5.8 上构建的源。

注意事项

• 该门控是编译时的，而非运行时的。 针对 UE 5.3 构建的插件二进制文件 完全不包含 Substrate 代码路径。将项目迁移到更新的引擎需要重新构建 插件以获得更新的行为。
• GetInputsView() 仅在一个地方保留。 Epic 已弃用它，转而使用 FExpressionInputIterator 和 UMaterialExpression::GetInput()，在 UE 5.8 上命名它会产生 C4996 ——今天是警告，在移除它的任何版本中都是编译错误。剩余的调用是 GetDreamShaderExpressionInputCount 的 UE 5.3 – 5.4 分支，其中 CountInputs() 尚不存在， 弃用也未生效；其他所有位置都按索引请求引脚。
• （自 2.0.0 起） 引擎缺少的节点、引脚、枚举器或属性在其目录中缺失， 因此使用它们的源在绑定时是错误；1.x 会静默丢弃其中一些（未读取的参数）。 只有少数这些错误会指明版本 ——DSH5294（来自较新引擎的 Substrate 节点）、 DSH5300（UE.UserSceneTexture，Custom Pass 节点）、DSH7128（5.3 上的 ShadingModel="Substrate"）以及 DSH8300（低于 5.8 的 .dsp）；其余都说明该节点、 引脚、值或属性不存在（DSH5210、DSH5213、DSH5215、DSH5200）。5.3 上的 substrate-builtins.json 清单仍携带 unsupportedReason。要在多个引擎上构建一个源， 请用 #if DS_ENGINE_MINOR >= … 保护较新的代码。
• DREAMSHADER_WITH_SUBSTRATE_BUILTINS 作为值被求值，因此必须写为 #if DREAMSHADER_WITH_SUBSTRATE_BUILTINS，而不是 #ifdef。它始终被定义。
• DREAMSHADER_UE_VERSION_AT_LEAST 是无条件定义的，因此在构建目标中预定义它 会产生宏重定义。请改为覆盖三个版本号宏。
• 因为 DreamShaderModule.h 包含此头文件，任何使用插件路径辅助函数的 翻译单元也可以使用这些宏。

示例

保护使用受版本门控的 DreamShader 行为的项目代码：

#include "DreamShaderVersionCompat.h"

void ConfigureShadingModel(FString& OutSettingValue)
{
#if DREAMSHADER_WITH_SUBSTRATE_BUILTINS
    OutSettingValue = TEXT("Substrate");
#else
    OutSettingValue = TEXT("DefaultLit");
#endif
}

void TrimTrailing(TArray<int32>& InOut)
{
    if (InOut.Num() > 0)
    {
        InOut.RemoveAt(InOut.Num() - 1, 1, DREAMSHADER_ALLOW_SHRINKING_NO);
    }
}

#if DREAMSHADER_UE_VERSION_AT_LEAST(5, 6)
// Plugin-rooted asset paths are mount-validated here; a packaged-but-unmounted plugin is an error.
#endif

相应的 DreamShaderLang 源代码，编写为在 5.3 上也能编译：

Shader(Name="Materials/M_Portable")
{
    Settings { ShadingModel = "DefaultLit"; }   // "Substrate" would require UE 5.4+
    Outputs  { vec3 Color; Base.BaseColor = Color; }
    Graph    { Color = UE.TransformVector(Input = UE.VertexNormalWS(), Source = "World", Destination = "Tangent"); }
}

另请参阅

• C++ API — 模块、头文件和链接
• DreamShaderModule.h — 在各处包含此头文件的头文件
• DreamShaderSettings.h — 着色模型目录中的 Strata 别名门控
• Substrate.* — DREAMSHADER_WITH_SUBSTRATE_BUILTINS 背后的内置系列
• Transform builtins — 版本门控的基础名称
• UE.* 目录 — 反射目录提供的节点
• 材质枚举 — Substrate 作为着色模型出现的位置
• Path(...) — 插件根目录与 5.6 挂载检查
• 资产路径 — Root="Plugin.X" 与 5.6 挂载检查
• 反编译器 — 版本门控的往返属性
• DreamShaderPass — 其规则文件定义 DREAMSHADER_WITH_CUSTOM_PASS 的模块
• Custom Pass 运行时 — 在 5.8 上运行的内容
• 诊断索引 — 所有代码，包括版本要求相关的代码