HLSL 简介

HLSL 是 Unreal 材质 Custom 节点使用的着色语言。DreamShaderLang 不是 HLSL 编译器，但这里的 HLSL 也不是摆设： .dss 里的 /// @custom 函数，以及 1.x 的 Function / GraphFunction，函数体就是 HLSL，几乎原样写进生成的 Custom 节点，由 Unreal 编译。.dss 的其余代码长得像 HLSL， 却会被降级成一张材质节点图。

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

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

since 2.0.0 起 HLSL 体直接写进 Custom 节点的代码；它调用的其他函数作为 DreamShaderFn_* 成员嵌进一个生成的 wrapper struct。不再生成逐源文件的 .ush include。见生成流程。

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

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

// .dss —— 同一个 helper，作为一个 Custom 节点
/// @custom
float3 ApplyTint(float3 color, float3 tint)
{
    return color * tint;
}

// 1.x —— 同一个 helper
Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
    result = color * tint;
}

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

类型

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

还有几个 HLSL 不认识的 token：.dss 的 material（材质属性集），1.x 的 MaterialAttributes、StaticBool 和 Substrate。 作为函数结果，MaterialAttributes 写成 FMaterialAttributes、StaticBool 写成 bool since 2.0.0；作为 Custom 节点的输入， MaterialAttributes 是 DSH6210，Substrate 在任何位置都是 DSH6253 —— Custom 节点没有这两种 pin。这类管线请写成普通图代码、 ShaderFunction 或 GraphFunction。完整的有效性矩阵见类型与值。

矩阵

图里没有矩阵值。float2x2 / float3x3 / float4x4 —— 以及 1.x 会规范化成它们的 mat2 / mat3 / mat4 —— 在 Properties 里是 DSH3252，在其他任何会变成节点或 pin 的位置都是 DSH4361。不过 1.x Function 签名在词法上接受 mat3， 所以声明能解析，失败发生在调用时：

Function float3 Rotate(in mat3 basis, in vec3 v) { return mul(basis, v); }
// 能解析；Graph 调用把矩阵传给 'basis' 时报 DSH4361

矩阵运算可以写在 /// @custom / Function 体内部，作为局部变量；或者通过 transform 内置 —— UE.TransformVector 和 UE.TransformPosition，见 UE.* 节点。

签名

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

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

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

since 2.0.0 起 return 保持原样：函数体现在就是返回节点第一个输出的那个 HLSL 函数的体，所以任何花括号深度上的 return expr; 都按 HLSL 的意思返回（1.x 只改写深度 0 上的 return，嵌套的会绕过 __return）。仍然检查的是：带返回类型的函数在 顶层写裸 return;（DSH6308）、没有返回类型的函数里任何位置的 return;（DSH6256），以及有返回类型却一个 return 都没有 （warning DSH6257，输出为 0）。

纹理与采样器

纹理类型的输入在节点上是一个携带纹理对象的 pin，引擎在它旁边声明 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;
}

since 2.0.0 起也可以写 tex.Sample(uv) —— 以及参数比 HLSL 自己的形式少一个的 SampleLevel、SampleBias、SampleGrad —— 它们会被改写成引擎的 Texture2DSample(tex, texSampler, uv) 一族。被嵌入的 helper 的签名会在每个纹理参数后面多出 SamplerState <Name>Sampler，别的函数体调用它时也会传入对应实参；这样的调用必须传全部实参（DSH6262），纹理实参必须是一个 名字（DSH6263）。SamplerState 不在触发这个展开的集合里。

控制流

内建函数

since 2.0.0 起 distance、exp、exp2、log、log2、log10、tan、sign、round、trunc、ddx、ddy、fwidth、rcp、 rsqrt 等都是内置了。仍然没有的是 sinh / cosh / tanh（没有对应的材质节点 —— 写进 @custom 体）和矩阵。

图里的 sin / cos 建出的 Sine / Cosine 节点按周期计（Period = 1），HLSL 体里的 sin / cos 才按弧度。round 四舍六入五取偶，和 HLSL 一样 since 2.1.2。

你的函数体会被怎么处理

每个 1.x Function 和 GraphFunction 体在存储前都会经过一次标识符级改写，扫描过程能识别注释和字符串。.dss 的 /// @custom 体原样保留，不做这层改写。

函数体最前面的 #include（之前只能有空白和注释）不属于函数：它被从函数体里拿掉（用空格覆盖，行列不变），挂到每个包含这个体的 Custom 节点的 include 列表上，引擎把它放在文件作用域。写在语句之后的 #include 留在函数体里。完整的双向别名表见 GLSL 简介。

DreamShaderBuiltins.ush

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

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

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

符号

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

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

怎么安全地用

• 其余的读取都没有副作用。它们碰到的每个字段和 Get*(Parameters) helper 都在像素入口无条件填充， 所以在任何不透明 Surface 像素求值里都能编过，不需要任何用途标记或插值器申请。
• DS_PerInstanceRandom 和 DS_PerInstanceFadeAmount 只对实例化或 GPU 剔除的绘制有意义。 在普通网格上它们读回安全常量（分别是 0 和 1），不会报编译错误。
• 有 include guard，所以同一个翻译单元里重复包含无害。
• 1.x 函数体的 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 自己的词汇，在 /// @custom 和 Function 体里都有效。DreamShaderLang 中一列标明函数体之外认得的部分。

接下来