函数

Function 和 GraphFunction 把可复用逻辑从裸的 Graph 语句里挪出来。两者都用 C 风格 签名加一段 HLSL 函数体，每个调用点都变成一个 Custom 节点，节点代码就是这段函数体；区别在于函数体里的 UE.* 调用怎么处理。legacy 前端把两者都读成 2.0 /// @custom 函数（自 2.0.0 起），dsc migrate 也这样写。

不再写共享的 .ush include：每个节点的 Code 自己带着它需要的全部 HLSL （自 2.0.0 起）。Namespace 把这两种块归到 Ns:: 前缀之下。

语法概览

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

<attributes>     := Generate = <string> [ , Library = <string> ] [ , Description = <string> ]

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

唯一的 (Key = Value) 头部是关键字之后那个可选头部（2.1.2 之后）：Generate、Library 和 Description，它们只在包的头部里有意义 —— 指包从函数生成的材质函数；Generate = "" 让函数退出其命名空间的模板。另一个键 是 DSH6331，即模板 DSH6332 里非 {Name} 的 {...}。见 包 ▸ 资产头部。它没有 Settings，也没有任何 section。参数列表之后的 { … } 是原始 HLSL，原样保留：只读它的花括号，字符串和注释里的花括号不算。

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

声明顺序

解析器从左到右读标识符，靠前瞻消歧：读完一个标识符后，下一个是 ( 它就是名字；下一个还是标识符，它就是返回类型，再下一个是名字。

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

警告：

函数不能取名为 Inline 或 SelfContained。Function SelfContained(in float a, out float b) { … } takes the modifier branch and finds ( where the name should be: DSH6300。旧的 section 式函数体 Function Name { Inputs = { … } Code = { … } }也是DSH6300`。

参数

一个参数是到下一个 , 或 ) 为止的那些单词；任意空白 —— 包括制表符和换行 —— 都只是分隔。接受 2 或 3 个单词：

至少一个输出

函数必须产出点什么：要么至少有一个 out 参数，要么有返回类型。两者都没有是 DSH6305。

返回类型

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

return 不再改写

return 原样保留（自 2.0.0 起）。1.x 把每个顶层 return 改写成对合成 __return 结果的赋值；现在函数体就是返回节点第一个输出的那个 HLSL 函数的 函数体 —— Custom 节点自己的，或者被内嵌时 helper 的。所以 return expr; 在任何花括号深度都返回值，1.x 里嵌在 __return 中绕过的情况现在和顶层的一样。

仍然检查的有：有返回类型时顶层的裸 return;（DSH6308）、没有返回类型时任何位置的 return; （DSH6256），以及声明了返回类型但函数体里一个 return 都没有 —— 这是 警告 DSH6257，输出会是 0。整个函数体只是一个裸表达式时会自动补上 return。 __return 这个名字仍然保留。

接受的参数类型

15 个 GLSL 别名在解析时被规范化成它们的 HLSL 拼法，而换了大小写的标量或向量（Float3）按小写读入。不是类型的 token 在声明处就是 DSH4201（自 2.0.0 起）（1.x 只有在函数被调用时才失败）。

生成的 HLSL 用 2.0 的方式书写每个类型：vec3 是 float3，MaterialAttributes 是 FMaterialAttributes，VolumeTexture 是 Texture3D。

警告：

Substrate 在 Function 或 GraphFunction 上永远不可用：任何引擎版本的 Custom 节点都没有 Substrate 引脚。请在 ShaderFunction 或 Shader 的 Graph 里构建 Substrate 部分。

纹理参数与采样器

Texture2D、TextureCube、Texture2DArray、Texture3D 和 VolumeTexture 是纹理参数。在节点上，它是一个承载纹理对象的引脚，引擎会在它旁边声明 SamplerState <Name>Sampler —— 在函数体里使用那个名字。被内嵌为 helper 时，它的 HLSL 签名会在每个纹理参数后面多出 SamplerState <Name>Sampler，而其他函数体对它的每次调用会在纹理实参之后传入 <argument>Sampler；这种调用必须传满每个实参（DSH6262），而且它的纹理实参必须是一个纯名字（DSH6263）。你自己名为 <Texture>Sampler 的参数会和这一对撞上（DSH6255）。SamplerState 不是纹理参数，没有伴随参数。

纹理参数上的 <Texture>.Sample(UV) —— 以及 SampleLevel、SampleBias、SampleGrad 比 HLSL 自身形式少一个参数时 —— 会被改写成引擎的 Texture2DSample(<Texture>, <Texture>Sampler, UV) 一族（自 2.0.0 起）；原生 HLSL 拼法保持原样。

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。

警告：

因为别名匹配忽略大小写、且作用于函数体内任意位置的整个标识符，你自己名为 Mix、Mod、Fract、Vec3 或 Mat4 的 helper —— 或者以这些名字命名的变量 —— 会在产出的 HLSL 里被静默改名。没有任何诊断 —— 针对 GLSL 拼法的 DSH5277 警告只覆盖 Graph 文本。请改名，或者换一个不会撞上的拼法（MixColor、 ModValue）。

压平后的 Common_Remap01 正是命名空间函数的名字，所以函数体里的 Ns::Fn(…) 调用现在能到达那个函数（自 2.0.0 起）。

顶部 #include 的提升

（自 1.8.0 起）

函数体顶部的 #include 指令 —— 前面只允许空白和注释 —— 不属于函数本身。它们会从函数体里被抹去（用空格覆写，所以之后每一行、每一列仍然和源码对得上），并被提升到每个代码里含这段函数体的 Custom 节点的 include 列表（IncludeFilePaths）上：函数自己的节点，以及内嵌它的其他 Function 的节点，被内嵌函数的 include 排在前面（自 2.0.0 起）。

Function float3 SampleWind(in float3 WorldPos)
{
    #include "/Plugin/DreamWind/Shared/DreamWindShared.h"   // hoisted
    FDreamWindSample S = DW_SampleAnalytic(DW_UnpackParams(P0, P1, P2), WorldPos);
    return S.Velocity;
}

引擎把节点的 include 放在文件作用域，所以定义了函数的头文件也能用。这正是让一个 C++ 与 HLSL 共用的头文件能被直接消费、而不必把它的函数抄进 DreamShaderLang 的东西。

生成的 HLSL

调用点的 Custom 节点把它的全部 HLSL 放在自己的 Code 里（自 2.0.0 起）：

struct generated_wrapper_<Name>_<CRC32>          // only when the body calls other Functions
{
	<Type0> DreamShaderFn_<Callee>(<params>)     // one member per embedded Function,
	{                                            // a callee before its caller
		// Begin DreamShader source: <file>
		// DreamShader custom: <Callee> line <N>
		<callee body, verbatim>
		// End DreamShader source: <file>
		return <Out0>;
	}
};
generated_wrapper_<Name>_<CRC32> __ds_wrapper_<CRC32>;

<Type0> <Out0> = (<Type0>)0;                     // the first out, for a function without a return type
// Begin DreamShader source: <file>
// DreamShader custom: <Name> line <N>
<body, verbatim; calls to embedded functions go through __ds_wrapper_<CRC32>>
// End DreamShader source: <file>
return <Out0>;                                   // appended only when the body has no top-level return

节点的标题（它的 Description）是函数名 —— 命名空间成员则是 Ns::Fn。

Inline / SelfContained

每个调用点的节点都带着函数自己的函数体，以及这个函数体（传递地）调用的每个其他 Function，作为 generated_wrapper_* 结构体的成员 —— HLSL 没有嵌套函数，而 Custom 节点的代码就是一个函数体。1.x 只对 SelfContained 函数这样做，其他情况引用它共享的 include；2.0 没有共享 include，所以每个函数都得到了 SelfContained 当初要求的东西，这个修饰符会被读入但不改变任何东西（自 2.1.1 起）。（2.0.0 – 2.1.0 把它读成 /// @custom selfcontained，那表示什么都不内嵌，于是这种函数体里的每个调用都留给 shader 编译器，然后失败。）

Inline 是 SelfContained 的旧拼法；读法相同，但给出警告 DSH6306。函数体调用不是 Function 的东西 —— ShaderFunction 或 VirtualFunction —— 是 DSH6261；调用提升了 UE.* 的 GraphFunction 是 DSH6327。只差大小写的调用是警告 DSH6259，留给 shader 编译器。

GraphFunction 与 UE.* 提升

（自 1.3.1 起）

读函数体时会扫描一遍，每个 UE.* 调用都记作一次提升。组装节点代码时，调用文本被替换成一个生成输入引脚的名字，那个引脚承载这次调用求值得到的材质表达式。

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

第 1–4 步不满足时，文本原样静默透传。第 5 步失败是 DSH6314。扫描跳过注释、字符串和字符字面量，所以写在注释里的 UE.Time() 不会被提升。

提取出的文本按 Graph 表达式解析，所以任何 UE.* 内置 —— 包括 UE.Expression —— 都可用。它在函数自己的作用域里绑定 （自 2.0.0 起）：函数的参数（每次调用时换成那次调用的实参），以及文件作用域的声明。只有调用方才有的名字是 DSH6325 —— 1.x 在调用方的 Graph 作用域里求值提升的调用；请把值作为参数传进来。谁都没有的名字（包括函数体自己声明的变量）是 DSH6326。

生成的引脚名

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

_ds_WindPulse_UE0

的引脚，而带命名空间的 Common::Pulse 产出 _ds_Common_Pulse_UE0。声明的 in 参数按声明顺序占据前面的引脚，提升出的引脚排在后面。这些名字在生成的节点上、以及任何提到它们的 shader 编译错误里都是用户可见的。

提示：

提升恰好消费 UE.Name( … ) 到配对的 ) 为止，一个字符都不多。尾随的 swizzle 或成员访问会留在原地，作为作用于引脚的 HLSL，所以 UE.CameraVector().xy 变成 _ds_<Fn>_UE0 .xy，由 shader 编译器求值；引脚承载节点默认输出的完整分量。引脚名用空格补齐到原调用的长度，所以函数体后面的每一列仍然和源码对得上。

警告：

只有 UE. 会被提升。 Substrate.* 调用不被提升，作为文本到达 shader 编译器，而那不是合法 HLSL；前端会给出警告 DSH6316 （自 2.0.0 起）。Substrate 值根本不能跨越 Custom 节点边界 —— 请在 ShaderFunction 或 Shader 的 Graph 里构建 Substrate 图。

被提升的调用必须产出 Custom 输入能承载的东西：数字、布尔，或者纹理对象 （自 2.0.0 起）。MaterialAttributes 值或 Substrate 材质是 DSH6329。有多个输出的节点把默认输出送进引脚。

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

一次调用会生成：

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

float pulse = (float)0;
// Begin DreamShader source: DShader/Lib/Motion.dsh
// DreamShader custom: WindPulse line 4

    float t = _ds_WindPulse_UE0;
    pulse = sin(uv.x * 8.0 + t);
// End DreamShader source: DShader/Lib/Motion.dsh
return pulse;

附加的 out 参数是节点的附加输出，以声明的参数命名 （自 2.0.0 起）（1.x 以调用方的变量命名），函数体直接给它们赋值。函数体里对普通 Function 的调用和在 Function 节点里一样被内嵌。

Namespace

Namespace 给它包含的 Function 和 GraphFunction 声明的名字加前缀。它不是一个实体：不会为它存储任何对象，它也不创建作用域。成员的名字是压平后的标识符 （自 2.0.0 起）：

Namespace(Name = "Common") { Function ApplyTint(…) }   →   Common::ApplyTint   →   function Common_ApplyTint

名字查找、绑定器诊断和 helper 符号 DreamShaderFn_Common_ApplyTint 看到的都是 Common_ApplyTint；限定拼法只留在一个地方：成员 Custom 节点的标题（Description）是 Common::ApplyTint，和 1.x 一样。

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);   // statement call
    float K = Common::Remap01(Tinted.r);          // value call
}

警告：

因为 :: 和 _ 压平后是同一个东西，Namespace(Name="Common") 的成员 ApplyTint 和顶层的 Function Common_ApplyTint 声明的是同一个名字：DSH4210。

在另一个 Function 或 GraphFunction 函数体里，Ns::Fn(…) 现在能调用到该函数 （自 2.0.0 起）：函数体规范化把 Common::ApplyTint 改写成 Common_ApplyTint，那正是函数自己的名字，于是 这个调用像其他 Function 调用一样被内嵌。在 1.x 里它会作为未定义的 Common_ApplyTint 到达 shader 编译器然后失败。写 :: 时它两边不能有空格。

调用

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

实参太多是 DSH4224；漏掉一个输入是 DSH4217。命名参数现在可以用 （自 2.0.0 起）：它们命名一个参数（没有这个名字是 DSH4216），使用了命名参数的调用按名字和声明 顺序匹配，而不是"先输入后接收者"。修饰后的拼法 DreamShaderFn_Luma(c) 不再指向这个函数（自 2.0.0 起）： DSH4208。

完整的参数规则、default 和输出选择器见 调用。

说明

• 一个名字只声明一样东西。 同名的两个函数 —— 同一文件里，或文件和它导入的 header 之间 —— 是 DSH4210；A::B 和 A_B 是同一个名字。同名的 Function 和 GraphFunction 同样是 DSH4210（自 2.0.0 起）（1.x 把调用报成有歧义）。函数名和内置函数 （lerp、saturate……）相同是 DSH6206。没有重载。
• 名字大小写敏感（自 2.0.0 起）。Luma 和 luma 是两个函数；Graph 调用只差大小写且唯一匹配时仍能解析，并给出警告 DSH5275。
• header 单独解析。 导入的 .dsh 不会被粘贴进文件；它的函数被登记进文件。见 import 与命名空间。
• 只含 Function / GraphFunction 块的 .dsm 或 .dsf 能编译成功且不产出任何东西。
• UE 5.3 上生成的 Custom 节点会在材质图里显示代码；UE 5.4 起 ShowCode 被设为 false。

示例

// DShader/Lib/Color.dsh

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

Function 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);      // statement call with a nested value call

        Color = Tex.rgb * Key;
    }
}

每个调用都是一个 Custom 节点。Luma 节点的代码 —— 注意函数体自己的 return：

// Begin DreamShader source: DShader/Lib/Color.dsh
// DreamShader custom: Luma line 4

    return dot(color, float3(0.299, 0.587, 0.114));
// End DreamShader source: DShader/Lib/Color.dsh

诊断

该选哪一种

继续阅读

• 调用 — 全部实参形式、默认值和输出选择器。
• import 与命名空间 — 把 helper header 带进调用它的文件。
• UE.* 节点 — GraphFunction 函数体能提升的一切。
• 类型与值 — 签名里的类型 token 及其 HLSL 拼写。