函数

Function 和 GraphFunction 把可复用逻辑从裸的 Graph 语句里挪出来。两者都用 C 风格签名加一段 HLSL 函数体；区别在于这段函数体的去向。

Namespace 把这两种块归到 Ns:: 前缀之下。

语法概览

Function      [ { Inline | SelfContained } ] [ <return-type> ] <name> ( [ <parameter-list> ] ) { <hlsl> }
GraphFunction                                [ <return-type> ] <name> ( [ <parameter-list> ] ) { <hlsl> }

<parameter-list> := <parameter> [ , <parameter> ] …
<parameter>      := [ { in | out } ] <type-token> <parameter-name>

它没有 (Key = Value) 头部、没有 Settings、也没有任何 section。参数列表之后的 { … } 是原始 HLSL， 通过感知 //、/* */ 和 "…" 的花括号配平扫描提取出来。

关键字 Function 和 GraphFunction 大小写敏感；修饰符、in / out 限定符和所有类型 token 不敏感。

声明顺序

解析器从左到右读标识符，靠一个字符的前瞻消歧：读完一个标识符后跳过空白和注释，如果下一个字符不是 (， 那么刚读到的标识符就是返回类型。

所以修饰符的位置是固定的：紧跟在关键字之后的第一位。

参数

参数先按顶层 , 切分，每个参数再按任意一段空白切分。接受 2 或 3 个 token：

至少一个输出

函数必须产出点什么：解析完成后结果列表不能为空。这意味着声明里要么至少有一个 out 参数，要么 有返回类型。两者都没有会得到 Function '{Name}' must declare at least one out parameter.

返回类型

有返回类型就意味着恰好一个输出，并且禁止任何显式 out。 多输出必须用 out 参数且不写返回类型。

return 降级

声明了返回类型时，函数体在 codegen 之前会被改写：花括号深度 0 上、两侧是非标识符字符的每个 return 都变成字面文本 __return =。后面的表达式和它的 ; 原样保留，扫描会跳过注释、"…" 和 '…'，所以 returnValue 和 my_return 不受影响。

深度 0 的裸 return; 是硬错误： A function with a return type cannot use a bare 'return;'. Return a value, e.g. 'return expr;'.

接受的参数类型

15 个 GLSL 别名规范化之后，解析器接受：

未知 token 在解析阶段不会被校验 —— 它被透传过去，只有函数被调用时才失败。矩阵就走这条路径： DreamShader Function 'Rotate' input 'basis' uses unsupported type 'float3x3'.

纹理参数与采样器

有五个 token 被当作纹理函数参数：Texture2D、TextureCube、Texture2DArray、Texture3D、 VolumeTexture。每遇到一个，生成的 HLSL 签名就会在它后面多出一个 SamplerState <ParamName>Sampler 参数，每个生成的调用点也会传入对应的 <argument>Sampler。在函数体里用这个名字来采样纹理。

SamplerState 不在这个列表里：声明为 SamplerState S 的参数解析成普通的 Texture2D 对象，不会 获得伴随参数。

Function SampleTinted(in Texture2D tex, in vec2 uv, in vec3 tint, out vec3 rgb, out float alpha)
{
    float4 texel = Texture2DSample(tex, texSampler, uv);
    rgb   = texel.rgb * tint;
    alpha = texel.a;
}

函数体规范化

每个 Function 和 GraphFunction 的函数体 —— 语言里也只有它们 —— 在存储之前会过一遍标识符级别的改写。 扫描感知注释和字符串，做两件事：替换 18 个别名（15 个 GLSL 类型拼法，加上 mix → lerp、 fract → frac、mod → fmod），以及把 A::B 压平成净化后的标识符 A_B。

生成的 HLSL

每个 Function 以这种形态写进生成的 include：

<ResultType0> DreamShaderFn_<SanitizedName>(<params>)
{
	<ResultType0> <Result0Name> = (<ResultType0>)0;
	<Result1Name> = (<ResultType1>)0;
	<body, indented>
	return <Result0Name>;
}

一个解析单元里的每个 Function 都会进 include —— 包括 SelfContained 的。GraphFunction 永远不会。 见 生成流程。

Inline / SelfContained

Inline 是 SelfContained 的完全同义词 —— 同一个解析分支、同一个标志位，行为上毫无差别。两者都 不被 GraphFunction 接受。

不带修饰符时，调用点产出的 Custom 节点代码会去调用 include。带修饰符时，这个函数以及它调用的普通 Function 的传递闭包会被内嵌进调用节点自己的代码里，包在一个结构体中。

GraphFunction 与 UE.* 提升

在 Custom 节点的代码被组装之前，函数体会被扫描一遍，每个 UE.* 调用都会被替换成一个生成输入引脚的 名字，那个引脚承载这次调用求值得到的值。

只有下列条件按顺序全部满足时才会被提升：

第 1–4 步不满足时，文本原样静默透传。第 5 步失败时生成停止，报 DreamShader GraphFunction '{Name}' contains an unterminated UE.* call. 扫描会跳过注释和字符串字面量， 所以写在注释里的 UE.Time() 不会被提升。

提取出的文本会被重新按 Graph 表达式解析，并在一个包含外层 Graph 块变量和本次调用实参的作用域中求值， 所以任何 UE.* 内置（包括 UE.Expression）都可用。

生成的引脚名

所以函数体里含一个 UE.Time() 调用的 GraphFunction WindPulse 会产出一个字面名为：

_ds_WindPulse_UE0

的引脚，而带命名空间的 Common::Pulse 产出 _ds_Common_Pulse_UE0。这些名字在生成的节点上、以及任何 提到它们的 shader 编译错误里都是用户可见的。

被提升的表达式必须产出普通数值。纹理对象、MaterialAttributes 值或 Substrate 材质会失败于 DreamShader GraphFunction '{Name}' UE input '{CallText}' cannot be passed into a Custom node input.

GraphFunction WindPulse(in float2 uv, out float pulse)
{
    float t = UE.Time();
    pulse = sin(uv.x * 8.0 + t);
}

一次调用会生成：

UMaterialExpressionTime                →  Custom pin "_ds_WindPulse_UE0"
UMaterialExpressionTextureCoordinate   →  Custom pin "uv"
UMaterialExpressionCustom  Description="WindPulse"  OutputType=CMOT_Float1

float pulse = (float)0;
float t = _ds_WindPulse_UE0;
pulse = sin(uv.x * 8.0 + t);
return pulse;

Namespace

Namespace 给它包含的 Function 和 GraphFunction 声明的名字加前缀。它不是一个实体：不会为它存储 任何对象，它也不创建作用域。它唯一的作用是改写成员的记录名。

Namespace(Name = "Common") { Function ApplyTint(…) }   →   名字 "Common::ApplyTint"

Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }

    Function float Remap01(in float value) {
        return saturate(value * 0.5 + 0.5);
    }

    GraphFunction Pulse(in float speed, out float value) {
        value = sin(UE.Time() * speed);
    }
}

Graph = {
    vec3 Tinted;
    Common::ApplyTint(BaseColor, Tint, Tinted);   // 语句式调用
    float K = Common::Remap01(Tinted.r);          // 值式调用
}

调用

两种调用形式都写在 Graph 块里。

Function 和 GraphFunction 在两种形式下都不支持命名参数 —— 传 Key = Value 会失败于 … currently uses positional arguments only. out 目标必须是裸名字、非空，且在一次调用内互不重复。 因为查找也接受净化后的拼法，DreamShaderFn_Luma(c) 是合法调用。

完整的参数规则、default、输出选择器和跨类型歧义见 调用。

说明

• 没有重载解析。 名字不按 arity 或参数类型区分；忽略大小写后第一个匹配的声明胜出。
• 忽略大小写的冲突就是真冲突。 Luma 和 luma 会被判为"声明了多次"，A::B 和 A_B 也是。
• 解析单元是整个 import 闭包，所以跨导入 header 的重名就是冲突。见 import 与命名空间。
• 只含 Function 块的 .dsm 或 .dsf 能编译成功且不产出资产： Generated DreamShader helper include '{Path}' from {File}.
• 如果一个 Function 和一个 GraphFunction 同名，所有调用都会有歧义。
• UE 5.3 上生成的 Custom 节点会在材质图里显示代码；UE 5.4 起 ShowCode 被设为 false。
• 旧的 section 式函数体 Function Name { Inputs = { … } Code = { … } } 不是受支持的形式。

示例

// DShader/Lib/Color.dsh

Function float Luma(in vec3 color)
{
    return dot(color, float3(0.299, 0.587, 0.114));
}

Function SelfContained Remap01(in float value, out float result)
{
    result = saturate(value * 0.5 + 0.5);
}

import "Lib/Color.dsh";

Shader(Name="Materials/M_Tinted")
{
    Properties = {
        TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_Base");
        vec3                     Tint    = vec3(1.0, 0.6, 0.2);
    }
    Outputs = {
        vec3 Color;
        Base.EmissiveColor = Color;
    }
    Graph = {
        vec2 UV  = UE.TexCoord(Index = 0);
        vec4 Tex = BaseTex(Coordinates = UV);

        float Key;
        Remap01(Luma(Tex.rgb), Key);      // 语句式调用，内层是值式调用

        Color = Tex.rgb * Key;
    }
}

诊断

该选哪一种

继续阅读