UE5.8 Substrate Toon Shading

Pipeline Analysis · Technical Report · 2026-06-22
基于 SQL-ManyThing FTS5 源码检索 + LLM 分析,梳理 UE5.8 Substrate 渲染框架下 Toon BSDF 的完整管道——从材质编译到运行时评估,覆盖 6 层 12 个源文件。
📑 目录 1. 管道分层
2. BSDF 类型注册
3. Shader 入口
4. 评估调度流程
5. 移动端约束
6. Console Variables
7. 源文件索引
8. BSDF 注册链路

1. 管道分层(6 Layers)

L1 — BSDF 类型定义
SubstrateDefinitions.h
BSDF 枚举常量 + 位宽约束
.h
L2 — 材质编译翻译
HLSLMaterialTranslator.cpp
材质节点 → HLSL 翻译
.cpp
L3 — Shader 实现
SubstrateToonBSDF.ush
Toon BSDF Shader 入口 + 核心函数
.ush
L4 — 评估调度
SubstrateEvaluation.ush
运行时 BSDF 类型分发
.ush
L5 — C++ 运行时
SubstrateVisualize.cpp
可视化调试 + 材质集成
.cpp
L6 — Atlas 管理
ToonProfileCommon.ush
3D ToonProfile Atlas 采样
.ush

2. BSDF 类型注册

Substrate 框架在 SubstrateDefinitions.h 中定义所有 BSDF 类型。Toon BSDF 注册为常量 SUBSTRATE_BSDF_TYPE_TOON = 6

#define SUBSTRATE_BSDF_TYPE_SLAB                0
#define SUBSTRATE_BSDF_TYPE_VOLUMETRICFOGCLOUD  1
#define SUBSTRATE_BSDF_TYPE_UNLIT               2
#define SUBSTRATE_BSDF_TYPE_HAIR                3
#define SUBSTRATE_BSDF_TYPE_SINGLELAYERWATER   4
#define SUBSTRATE_BSDF_TYPE_EYE                 5
#define SUBSTRATE_BSDF_TYPE_TOON                6  // ← Toon BSDF
常量含义
SUBSTRATE_MAX_CLOSURE_COUNT8最大 Closure 数(4bit×8=32bit)
SUBSTRATE_MAX_OPERATOR_COUNT15最大操作符数
SUBSTRATE_FULLY_SIMPLIFIED_NUM_UINTS8简化材质 32 字节

3. Shader 入口 — SubstrateToonBSDF.ush

Pack/Unpack ToonCustomData(UV → 32-bit uint)
uint PackToonCustomData(in float2 UVs, in float ProfileId, in float Dither)
{
    uint U12bits = saturate(UVs.x) * 4095.0f;
    uint V12bits = saturate(UVs.y) * 4095.0f;
    uint Packed  = U12bits;
    Packed |= V12bits << 12;
    Packed |= (uint(ProfileId) & 0xFF) << 24;
    return Packed;
}

UV: 12-bit (0~4095) → ProfileId: 8-bit (0~255) → 总计 32-bit

评估结果结构 — FSubstrateEvaluateToonResult
struct FSubstrateEvaluateToonResult {
    float3 IntegratedDiffuseValue;
    float3 IntegratedSpecularValue;
    float3 DiffuseColor;
    float3 EmissivePathValue;
    float3 DiffusePathValue;
    float3 SpecularPathValue;
    float  DiffusePDF;
    float3 ThroughputV;
    float3 TransmittanceAlongN;
    bool   bPostProcessSubsurface;
    float  ToonDataWeight;
    float  ToonDataShadowNoL;
};
核心评估函数调用链
SubstrateToonEvaluateCommon()
  ├─ GetToonProfileEvaluateSettings(ProfileId)
  ├─ EvaluateToonProfileDiffuseDither()
  ├─ EvaluateToonProfileSpecularDither()
  └─ EvaluateToonProfileShadowHatch()

4. 评估调度流程

Material
Toon BSDF
BSDF Type?
SUBSTRATE_BSDF_TYPE_TOON
Forward
SubstrateToonBSDF.ush
Deferred
SubstrateEvaluation.ush
SubstrateToonEvaluateCommon()
中央评估函数
ToonProfile Atlas
L6 3D 纹理采样

三种路径(Forward / Deferred / Mobile)汇聚到同一入口,最终从 L6 的 3D ToonProfile Atlas 采样漫反射 Ramp、镜面反射和阴影排线。

5. 移动端约束

#define TOON_CAN_USE_PATTERNS_UVS \
  (!SHADING_PATH_MOBILE || \
   (!MOBILE_DEFERRED_SHADING || MOBILE_EXTENDED_GBUFFER))
条件能力
桌面 / 非移动路径✅ Ramp UV + Shadow Hatching 全开
移动延迟 + 扩展 GBuffer✅ 支持 Patterns UV
移动无扩展 GBuffer❌ Ramp UV 和 Shadow Hatching 被跳过

6. Console Variables

r.Substrate.Experimental.ToonUnifiedDiffuse 0 统一漫反射着色(=1) vs 分别照明漫反射(=0)
r.Substrate.Experimental.ToonReflectionQuantizationEnabled 0 反射项量化,节省 GBuffer 带宽

7. 源文件索引

文件角色
Engine/Shaders/Shared/SubstrateDefinitions.hL1BSDF 类型枚举、位宽常量
Engine/Source/.../HLSLMaterialTranslator.cppL2材质节点→HLSL 翻译
Engine/Source/.../SubstrateTranslatorCommon.cppL2Substrate 通用翻译器
Engine/Shaders/Private/Substrate/SubstrateToonBSDF.ushL3Toon BSDF Shader 实现
Engine/Shaders/Private/Substrate/SubstrateEvaluation.ushL4评估调度入口
Engine/Shaders/Private/Substrate/Substrate.ushL4Substrate 主框架
Engine/Shaders/Private/Substrate/SubstrateDeferredLighting.ushL4延迟光照路径
Engine/Source/.../Substrate/SubstrateVisualize.cppL5C++ 可视化调试
Engine/Source/.../Substrate/SubstrateMaterial.cppL5材质系统集成
Engine/Shaders/Private/ToonProfileCommon.ushL6ToonProfile Atlas 采样
Engine/Shaders/Private/Substrate/SubstrateExport.ushL5导出/GBuffer 打包
Engine/Shaders/Private/Substrate/SubstrateRead.ushL4Substrate 材质读取

8. BSDF 注册链路

1. HLSLMaterialTranslator.cpp → case SUBSTRATE_BSDF_TYPE_TOON:
   → 生成 SubstrateToonBSDF.ush include
2. SubstrateEvaluation.ush → 运行时 #if SUBSTRATE_BSDF_TYPE_TOON
3. SubstrateToonEvaluateCommon() → ToonProfile Atlas 3D
4. ToonProfileCommon.ush → Diffuse Ramp + Shadow Hatching + Dither
结论:UE5.8 Substrate Toon 管道分 6 层、12 个源文件。 L1-L3 编译时(BSDF 类型定义 → HLSL 翻译 → Shader 生成), L4-L6 运行时(评估调度 → 可视化调试 → Atlas 采样)。 两个实验性 Console Variable 控制漫反射统一和反射量化, TOON_CAN_USE_PATTERNS_UVS 宏区分桌面/移动能力。

LaTeX source available: C:\Projects\NoReturn\_bridge\reports\substrate_toon\substrate_toon_report.tex