HLSL 简介

HLSL 是 Unreal 材质 Custom 节点使用的着色语言。DreamShaderLang 不是 HLSL 编译器，但这里的 HLSL 也不是摆设：Function 或 GraphFunction 的函数体就是 HLSL， 几乎原样输出到生成的 include 里，由 Unreal 编译。

本页写给从 HLSL 过来的读者：哪些 HLSL 经验能直接用、哪些不能，以及分界线在哪里。

HLSL 在哪里运行，在哪里不运行

所以：节点图写起来啰嗦的算术就交给 HLSL，引擎输入、参数和绑定就留在 Graph 里。两者在函数调用处汇合。

// 纯 HLSL
float3 ApplyTint(float3 color, float3 tint)
{
    return color * tint;
}

// 同一个 helper 的 DreamShaderLang 声明
Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
    result = color * tint;
}

两种写法都存在。声明返回类型是合法的，会降级成单个输出，所以 Function float3 ApplyTint(in vec3 color, in vec3 tint) { return color * tint; } 是同一个 helper 的 HLSL 式写法。

类型

DreamShaderLang 的类型 token 是一个封闭集合。它接受的 HLSL 写法如下：

还有两个 HLSL 根本不认识的 token：MaterialAttributes 和 StaticBool。它们在 DreamShaderLang 这边能解析，但 token 会被原样写进生成的签名里，于是用了它们的 Function 会产出一个 Unreal 编不过的 helper。这类管线请改用 ShaderFunction 或 GraphFunction。完整的有效性矩阵见 类型与值。

矩阵

没有矩阵类型。float2x2 / float3x3 / float4x4 —— 以及会被规范化成它们的 mat2 / mat3 / mat4 —— 在每个声明位置都被拒绝。不过 mat3 在 Function 签名里词法上是被接受的，因为签名 规范化器在任何校验之前就把它改写掉了；声明能解析，失败发生在调用时：

Function float3 Rotate(in mat3 basis, in vec3 v) { return mul(basis, v); }
// 能解析；调用时失败：
//   DreamShader Function 'Rotate' input 'basis' uses unsupported type 'float3x3'.

矩阵形状的工作只能通过 transform 内置触达 —— UE.TransformVector 和 UE.TransformPosition， 见 UE.* 节点。

签名

HLSL 的函数签名和 Function 签名长得像，但规则在几处不同。

函数必须产出点什么：至少一个 out 参数，或者一个返回类型。都没有会报 Function '{Name}' must declare at least one out parameter.

Function float Luma(in vec3 color) {
    return dot(color, float3(0.299, 0.587, 0.114));      // 一个结果，HLSL 风格
}

Function SplitChannels(in vec4 src, out vec3 rgb, out float alpha) {
    rgb   = src.rgb;                                      // 两个结果，out 风格
    alpha = src.a;
}

声明了返回类型时，处在花括号深度 0 的每个 return 都会被改写成对合成变量 __return 的赋值。 深度 0 上的裸 return; 是硬错误。嵌在 if { … } 里的 return 仍然是真正的 HLSL return —— 合法，但绕过了 __return。

纹理与采样器

纹理类型的 in 参数会在生成的签名里紧随其后多出一个 SamplerState <ParamName>Sampler， 每个调用点也会传入对应实参。在函数体里就用这个名字采样：

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;
}

SamplerState 不在触发这个展开的集合里。声明为 SamplerState S 的参数在签名里就写成 SamplerState S，并在调用点收到一个纹理对象。

控制流

在 Function 体内部，HLSL 自己的控制流完全可用 —— if、else、for、while、do、switch、 break、continue、discard。函数体是透传的，所以能在 Custom 节点里编过的，在这里也能编过。

在 Graph 块里词汇量小得多：只有 if / else，条件必须带括号、分支体必须带花括号，没有循环。

内建函数

Graph 这一面是：abs、ceil、clamp、cos、dot、floor、fmod、frac、fract、lerp、 max、min、mix、mod、normalize、pow、saturate、sin、sqrt。明显缺席的有：step、 smoothstep、length、cross、reflect、refract、exp、log，以及全部反三角函数。 要用它们，走 UE.Expression(Class = …)，或者写进 Function 体里。

你的函数体会被怎么处理

每个 Function 和 GraphFunction 体 —— 语言中仅此两处 —— 在存储前都会经过一次标识符级改写。 扫描过程能识别注释和字符串。

完整的双向别名表见 GLSL 简介。

DreamShaderBuiltins.ush

插件自带一个 HLSL 头文件，定义了一批 DS_* 宏和函数，对应 UE.* 节点在材质翻译器里产生的 HLSL。

#include "/Plugin/DreamShader/DreamShaderBuiltins.ush"

模块启动时，DreamShader 会注册一条从虚拟目录 /Plugin/DreamShader 到插件 Shaders 目录的 shader 源目录映射，除非该虚拟目录已经有映射。这个映射是无条件的 —— 不依赖任何项目设置、backend 选择或引擎版本 —— 所以上面那条路径对引擎的 shader 预处理器永远可解析。它和生成的逐源文件 helper include 用的是两条不同的映射。

符号

Parameters 是 include 处作用域内的材质参数结构体；Tex 是一个纹理参数标识符， 采样器名由 token 粘接得到（Tex##Sampler）。

WSDemote 调用把引擎的大世界坐标向量降到 float3。camera-relative 的那个位置形式本身就是 float3，在相机附近保留精度。

怎么安全地用

• 其余的读取都没有副作用。它们碰到的每个字段和 Get*(Parameters) helper 都在像素入口无条件填充， 所以在任何不透明 Surface 像素求值里都能编过，不需要任何用途标记或插值器申请。
• DS_PerInstanceRandom 和 DS_PerInstanceFadeAmount 只对实例化或 GPU 剔除的绘制有意义。 在普通网格上它们读回安全常量（分别是 0 和 1），不会报编译错误。
• 有 include guard，所以同一个翻译单元里重复包含无害。
• GLSL 别名改写跳过字符串字面量，所以 #include "…" 里的路径永远不会被改写。

Function vec2 Wobble(in vec2 uv, in float speed)
{
    #include "/Plugin/DreamShader/DreamShaderBuiltins.ush"
    float t = DS_TIME * speed;
    return uv + float2(sin(t), cos(t)) * 0.02;
}

基于节点的等价写法既不需要 include，也不需要任何 HLSL helper：

GraphFunction vec2 Wobble(in vec2 uv, in float speed)
{
    float t = UE.Time() * speed;
    return uv + vec2(sin(t), cos(t)) * 0.02;
}

HLSL 常见关键字

作为参考 —— 这些是 HLSL 自己的词汇，在 Function 体里都有效。DreamShaderLang 中一列标明 声明语法在函数体之外认得的部分。

接下来