VirtualFunction 工具

DreamShader » 工具 » VirtualFunction 工具

为现有 UMaterialFunction 资源生成、打开和刷新 VirtualFunction 声明的编辑器操作，以及使这些声明与其指定资源保持同步的启动服务。

上下文菜单

每次右键单击时都会重新构建 VirtualFunction 部分。在构建它之前，编辑器 会在每个项目源文件中搜索 VirtualFunction 声明，其解析后的资源与 所选 UMaterialFunction 匹配。你获得的条目取决于搜索结果。

当声明已存在时

不提供其他条目——特别是不提供 Create，因为已经存在一个声明。

当声明不存在时

匹配依据是声明解析后的资源对象路径，比较时不区分大小写；第一个 匹配项胜出。有两种拼写形式算作声明：任何源文件中的 1.x VirtualFunction 块，以及 （自 2.0.0 起） .dsh 或 .dss 中带有 /// @asset 行的 extern 原型。由于 查找会读取文件，刚刚手写的声明会立即被找到——启动时不会 缓存任何内容。

[!WARNING] 该查找会重新枚举并重新读取每个源文件（.dsm、.dsh、.dsf、.dss、.dsi、 .dsp），位于每个源根目录下、每个根目录的 Packages 文件夹之外，从磁盘读取，在每次 右键单击材质函数资源时都会执行；提及 extern 和 @asset 的 .dsh 或 .dss 也会被解析。开销随源文件数量增长，并在 上下文菜单出现之前产生。没有缓存，也无法禁用它，除非 -NoDreamShaderEditorBridge，而那样会完全移除菜单。

操作

本页中运行时替换项显示为 {Placeholder}。

[!NOTE] 对已有声明的资源执行 CreateVirtualFunction 会静默重定向到 OpenVirtualFunction。 它绝不会写入重复文件。你收到的提示是 Opened VirtualFunction definition: {File}，而不是“已创建”消息。当任一拼写形式存在时， Create extern Prototype 也会如此。

文件写入位置

在此写入的 .dsh 会像任何其他头文件一样被源目录监视器拾取，因此 导入它的材质会自动重新编译。

生成的声明

VirtualFunction(Name="<SanitizedName>")
{
    Options = {
        Asset = <asset-literal>;
        Description = "Generated from <full object path>";
    }

    Inputs = {
        [opt ]<type> <Name>[ = <default>][ [ Description="…"; SortPriority=<n>; ] ];
        …
    }

    Outputs = {
        <type> <Name>[ [ Description="…"; SortPriority=<n>; ] ];
        …
    }
}

正文使用制表符缩进。仅当资源至少公开一个输出时才会生成声明。

资源字面量

有关可接受的根拼写，请参见 路径。

输入类型

从 Unreal 的函数输入类型到 DreamShaderLang 标记的映射是穷尽的：

可选输入与默认值

当资源将某个输入标记为使用其预览值作为默认值时，该输入会加上 opt 前缀。 默认字面量根据该预览值渲染：

[!WARNING] 被标记为可选的纹理或材质属性输入会获得 opt 前缀，但没有默认 值，因为不存在可用于它的字面量语法。请在调用处提供该参数，或编辑 声明。

元数据后缀

标识符清理

非 ASCII 字母会被保留——该清理器支持 Unicode，而非仅 ASCII。

在输出的字符串字面量内部，\、"、回车符、换行符和制表符都会被转义。

调用示例

CopyVirtualFunctionCall 和 Copy Virtual Function Reference 都会生成：

<FunctionName>(<arg>, <arg>, …, OutputIndex=0)

复制的文本是 1.x 文本的模板。请用真实的 Graph 值替换占位参 数名，并在需要不同输出时更改 OutputIndex。参见调用。 将 default 作为参数是遗留规则（L25）：仅适用于 1.x 文本，且 dsc migrate 会将其改写为具名参数。

启动同步服务

每个编辑器会话中，在桥接启动时，DreamShader 会重新读取项目中的每个 VirtualFunction 声 明，从实时资源重建它，并在文本发生变化时将文件写回。

[!WARNING] 没有针对此操作的监视器。 编辑 UMaterialFunction 的输入或输出不会 刷新声明；保存 .dsh 也不会。声明只会在下一次编辑器启动时 重新同步。

由于扫描器是手写词法分析器而非前端，它能在文件合法存放声明的任何位置找到声明 ——包括在 .dsm 内部、与 Shader 块并存的情况。

条件源会被拒绝 （自 1.9.0 起）

包含任何预处理器指令的源文件不会被同步。它会被 报告一次，为 DSH9001，并完全保持原样。

原因在于写回，而非读取。同步会将 StartIndex / EndIndex 记录为字节 偏移量，并将重建的声明拼接到该范围上。预处理器保证行数 守恒——这只能换来行对齐，别无其他，因为被切掉的行会被替换为 更短的空行。因此，第一个切割点之后的每个字节偏移量都指向错误的位置，而 契约中没有可用于修正的偏移映射。如果经过预处理的字符串到达了 SaveStringToFile，文件中的每个死分支都会被永久压平。

这与 Adopt 是同一类意外，而且在某一点上更为严重：Adopt 是 由人选择的菜单项，而此服务会在桥接启动时无人值守地运行， 遍历项目中的每个可写源文件。

[!NOTE] 只有在 VirtualFunction 子字符串测试之后才会到达该门控，因此一个不包含声明 的条件材质——同步本来也永远不会改写它——不会在每次编辑器启动时都报告错误。

同一扫描器的只读使用者不受影响，会继续扫描原始文本：上下文菜 单、Open Virtual Function 以及复制的调用示例 都会看到所有分支的并集。这与依赖图所遵循的规则一致，而且出于同样的 原因它是安全的——读取所有分支会过度报告，而过度报告是无害的。

同步诊断

下面的每条消息都会记录阶段 virtualFunctionSync、代码 virtual-function-sync、 源 DreamShader VirtualFunction 和严重性 error——这是同步产生的唯一严重性。 它们会到达 diagnostics.json、分片的 diagnostics/ 目录和 bridge.db。

Expected exactly one VirtualFunction block. 是当代码块包含零个或多个声明时第四行携带的解析器错误文本。

条件源拒绝 与其它所有行一样遵循上述段落：其记录仍携带阶段 virtualFunctionSync、代码 virtual-function-sync 和严重级别 error。其 DSH9001 在 消息文本 中传递，与 DSH8149 在 Adopt 闸门上的行为完全一致 —— 线上契约不变。

尽管如此，它是通过编码式诊断所使用的同一个 FailWith 辅助函数抛出的，这是有意的权衡，而非不一致：gen-diagnostics.ps1 通过扫描完全相同的调用形态来发现代码，因此以任何其它方式编写的拒绝将存在于源代码中，而不存在于本手册中。DSH9001 是 DSH9xxx 工具范围的第一个条目，此前该范围为空白。

报告

至少包含一个声明且未产生诊断的文件，其诊断会被清除；产生了诊断的文件，其诊断会被设置。

示例

右键点击 /Game/Functions/MF_Weathering（一个含有一个标量和一个纹理输入、以及一个输出的 UMaterialFunction）▸ DreamShader ▸ CreateVirtualFunction。编辑器会写入 <Project>/DShader/VirtualFunctions/MF_Weathering.dsh 并打开它：

VirtualFunction(Name="MF_Weathering")
{
	Options = {
		Asset = Path(Game, "Functions/MF_Weathering");
		Description = "Generated from /Game/Functions/MF_Weathering.MF_Weathering";
	}

	Inputs = {
		opt float Amount = 0.5 [
			Description="Weathering strength";
		];
		Texture2D Mask;
	}

	Outputs = {
		float3 Result;
	}
}

CopyVirtualFunctionCall 在同一资源上复制：

MF_Weathering(default, Mask, OutputIndex=0)

从材质中使用它：

import "VirtualFunctions/MF_Weathering.dsh";

Shader(Name="Materials/M_Rock")
{
    Properties = {
        Texture2D MaskTex = Path(Game, "Textures/T_Mask");
    }

    Outputs = {
        float3 Color;
        Base.BaseColor = Color;
    }

    Graph = {
        Color = MF_Weathering(0.8, MaskTex, OutputIndex=0);
    }
}

另请参阅

• VirtualFunction —— 声明的语法及其 Options 键
• 选项 —— Options 区段接受的所有键
• 编辑器集成 —— 菜单附加到何处以及那里还有什么
• 调用 —— 从 Graph 调用 VirtualFunction
• 输入 / 输出 / 结果 —— 声明中的 opt、默认值和元数据
• 路径 —— Asset 键使用的 Path(Root, "…") 字面量
• 导入 —— 材质如何获取生成的 .dsh
• 预处理器 —— 为什么条件源会以 DSH9001 被拒绝
• 分歧 —— Adopt，另一个源写入器，因相同理由被拒绝
• 反编译器 —— 同一个声明构建器，用于每个被调用的函数
• 桥接 —— 同步诊断发布的位置
• 诊断索引 —— 按阶段列出的每条消息