XCEngine/docs/used/Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md

Renderer 下一阶段：Unity 风格 Shader 体系正式化计划

日期：2026-04-06

1. 阶段结论

当前 renderer 主线已经可以阶段性收口，但 Shader / Material / Pass 体系还没有真正统一。

现在仓库里的 shader 体系处于一个过渡态：

• 逻辑上已经有 Shader -> Pass -> Variant 模型
• authoring 外观上已经接近 Unity ShaderLab
• 运行时已经能按 pass 和 backend variant 选择 shader
• 三后端已经能稳定跑通 builtin shader

但它仍然不是 Unity 风格的正式体系，因为当前 authoring 仍然暴露了太多 backend 与 binding 细节：

• .shader 文件里仍然显式写 #pragma backend D3D12/OpenGL/Vulkan
• .shader 文件里仍然显式写 Resources { name(type, set, binding) }
• material 仍然可以显式指定 shaderPass
• shader 关键字、变体、include、pass state、SubShader 选择还没有真正成体系

所以这一阶段的主线不是继续做新渲染效果，而是把 shader 体系升级成：

• authoring 层完全按 Unity 风格书写
• 三后端编译路径统一收敛到 importer / compiler 层
• runtime 只消费正式 shader artifact / material contract

这一步不是 SRP 本身，但它是后续 SRP 能否成立的硬地基。

---

2. 阶段目标

本阶段要达成的核心目标只有一件事：

把当前“伪 ShaderLab + 后端直连”的过渡体系，升级为“Unity 风格 authoring + 引擎内部统一 shader IR + 三后端编译产物”的正式体系。

完成后应达到：

1. shader authoring 采用 Unity 风格 .shader 语法，不再要求作者显式写 backend variant 分发表。
2. 新语法不再要求作者手写 set/binding 级资源绑定表。
3. HLSL 成为 raster shader 的单一 authoring 语言源。
4. D3D12 / Vulkan / OpenGL 的差异退到 importer / compiler / artifact 层。
5. material 只管 property / keyword / texture / render state，不再负责点名 pass。
6. renderer 按 LightMode / pass contract 选 pass，而不是靠 material 的临时字符串兜底。
7. builtin shader 全部迁移到新体系并保持三后端回归稳定。
8. 保留 legacy shader 兼容层，避免一次性炸掉现有工程内容。

---

3. 非目标

本阶段明确不做：

• SRP 本体
• render graph
• deferred / clustered
• Shader Graph
• Surface Shader
• 完整 Unity ShaderLab 100% 全语法一次性覆盖
• volume 系统
• 更多新渲染效果

本阶段也不追求一口气把 Unity 的所有 authoring 特性补完，例如：

• Fallback
• UsePass
• CustomEditor
• GrabPass
• tessellation / geometry / ray tracing authoring

这些可以后续补，但不应阻塞当前阶段把“统一 shader 体系”先做正确。

---

4. 当前真实状态与根本问题

4.1 当前已经具备的能力

当前工程已经具备：

• .shader 文件解析能力
• Shader 的 pass / property / resource / variant 数据模型
• builtin shader 资产化
• material property / texture / render state / tag 载体
• renderer 中按 builtin pass metadata 选择可用 shader pass

这意味着当前不是从零开始设计。

4.2 当前最根本的问题

当前最大的问题不是“没有 shader 体系”，而是“authoring 层和 runtime 层的边界还没收干净”。

具体表现为：

1. authoring 层暴露后端差异

   • .shader 文件直接写 #pragma backend D3D12/OpenGL/Vulkan
   • shader 作者必须知道后端与源码文件映射

2. authoring 层暴露 RHI binding 细节

   • .shader 文件显式写 Resources { ConstantBuffer / Texture2D / Sampler, set, binding }
   • 这更像 Vulkan/D3D12 binding 清单，不是 Unity 风格 shader authoring

3. material 还带着临时 pass 选择职责

   • Material::SetShaderPass() 仍然存在
   • renderer 仍然优先吃 material 显式指定的 pass
   • 这会阻碍未来 RendererFeature / SRP 规范化

4. 关键字与变体体系缺失

   • 没有正式的 multi_compile / shader_feature
   • 没有变体剥离与编译缓存策略

5. include 与共享库体系缺失

   • 没有正式的 shader include 搜索路径、预处理、公共库组织

6. pass state 仍然不在 shader authoring 的统一语义内

   • 诸如 Cull / ZWrite / ZTest / Blend / ColorMask / Stencil 还没有完整进入 shader authoring contract

7. 三后端仍然是物理三套源码直连

   • 当前虽然“逻辑上一个 shader asset”
   • 但作者本质上还在维护三套 shader stage 文件

---

5. 核心设计结论

5.1 目标不是“看起来像 Unity”，而是“真正采用 Unity 风格 authoring 模型”

最终目标应当是：

• 一个 .shader 文件描述一个逻辑 shader
• shader 内部有 Properties / SubShader / Pass / Tags / State / Program
• renderer 消费的是 import 后的统一 IR / artifact
• backend 差异不暴露给 shader 作者

5.2 HLSL 作为单一 authoring 语言源

本阶段必须明确：

• 新体系下 raster shader 统一使用 HLSL authoring
• D3D12 直接编 HLSL
• Vulkan 由 HLSL 编到 SPIR-V
• OpenGL 由 HLSL 编到 SPIR-V，再转 GLSL 430

原因：

• 如果 authoring 仍然保留 GLSL/HLSL 三套并行，永远不可能真正统一写法
• 只有 single-source authoring，才能接近 Unity 的真实体验

5.3 backend 差异必须退到 importer / compiler 层

新 authoring 文件中不应再出现：

• #pragma backend ...
• backend 专属 stage 文件路径表

这些内容应由 importer 根据 target backend 生成产物。

5.4 resource binding 不再由 shader 作者手写 Resources(set,binding)

Unity 风格 shader authoring 不要求作者手写 descriptor set / binding。

因此新体系下应改为：

• material 暴露属性来自 Properties
• engine 内建 constant buffer / texture / sampler 来自约定与 reflection
• importer 通过 HLSL reflection + 约定库推导 runtime resource layout

也就是说：

• authoring 层写“语义”
• importer 层生成“绑定布局”
• runtime 层消费“绑定布局”

5.5 pass 选择必须回归 renderer，而不是 material

新体系中：

• material 只绑定 shader 与 property / keyword / texture
• renderer 按 LightMode 选 pass
• Material::shaderPass 进入弃用与最终移除路径

这与 Unity 的 ShaderTagId / LightMode 思路对齐，也更利于未来 SRP。

5.6 必须保留 legacy 兼容层

当前仓库已经有一批 builtin shader 和测试资产。

因此不能激进地“一刀切重做”，而应：

• legacy .shader 继续可加载
• 新 Unity 风格 .shader 进入新 importer 路径
• builtin shader 分批迁移
• runtime 统一落在同一套 Shader / artifact / variant 模型上

---

6. 目标架构

建议把 shader 体系正式分成 5 层。

6.1 Authoring 层

职责：

• 让开发者以 Unity 风格书写 shader

建议语法子集：

• Shader
• Properties
• SubShader
• Pass
• Tags
• LOD
• HLSLINCLUDE
• HLSLPROGRAM
• ENDHLSL
• #pragma vertex
• #pragma fragment
• #pragma target
• #pragma multi_compile
• #pragma shader_feature
• #pragma shader_feature_local
• Cull
• ZWrite
• ZTest
• Blend
• ColorMask
• Stencil
• Offset

6.2 Importer / Parser 层

职责：

• 解析 Unity 风格 .shader
• 生成统一的内部 ShaderIR

建议引入：

• ShaderAuthoringParser
• ShaderIR
• ShaderSubShaderIR
• ShaderPassIR
• ShaderKeywordDecl
• ShaderPassStateDesc
• ShaderProgramIR

6.3 Compiler / Reflection 层

职责：

• 编译 authoring 中的 HLSL
• 为不同 backend 生成最终编译产物
• 生成 resource layout / constant layout / keyword variant metadata

建议技术路径：

• D3D12：DXC -> DXIL/DXBC
• Vulkan：DXC -> SPIR-V
• OpenGL：DXC -> SPIR-V -> SPIRV-Cross -> GLSL 430

输出：

• 每个 pass / stage / keyword-set / backend 的编译产物
• 反射出的 constant buffer / texture / sampler 布局

6.4 Artifact 层

职责：

• 保存运行时真正消费的 shader 产物

建议引入新版 artifact：

• xcshader2 或继续升级现有 xcshader

artifact 内容至少包含：

• shader 名称 / guid
• properties
• subshader / pass tags
• pass state
• keyword declarations
• keyword variant table
• backend binaries / backend source payload
• reflected resource layout
• include 依赖与 hash

6.5 Runtime 层

职责：

• renderer 根据 pass contract、keywords、backend 选择最终 variant
• material 根据 property/texture 生成常量与资源绑定
• pipeline cache 根据 shader variant + render state 建 key

---

7. Unity 风格 authoring 范围定义

7.1 第一阶段必须支持的语法

第一阶段建议正式支持：

Shader "XCEngine/Example/Lit"
{
    Properties
    {
        _BaseColor ("Base Color", Color) = (1,1,1,1)
        _BaseMap ("Base Map", 2D) = "white" {}
        _Cutoff ("Alpha Cutoff", Range(0,1)) = 0.5
    }

    HLSLINCLUDE
    #include "ShaderLibrary/Core.hlsl"
    ENDHLSL

    SubShader
    {
        Tags { "RenderType"="Opaque" "Queue"="Geometry" }
        LOD 200

        Pass
        {
            Name "ForwardLit"
            Tags { "LightMode"="ForwardLit" }
            Cull Back
            ZWrite On
            ZTest LEqual
            Blend One Zero

            HLSLPROGRAM
            #pragma target 4.5
            #pragma vertex Vert
            #pragma fragment Frag
            #pragma multi_compile _ XC_MAIN_LIGHT_SHADOWS
            #pragma shader_feature_local _ XC_ALPHA_TEST
            ENDHLSL
        }
    }
}

7.2 第一阶段暂不支持的语法

第一阶段可暂缓：

• Fallback
• UsePass
• GrabPass
• CustomEditor
• Category
• Dependency
• Surface Shader
• CG fixed-function 时代遗留语义

这些需要列入兼容性说明，但不应阻塞首版落地。

---

8. 统一的 shader library 与 include 体系

这一层是“写法统一”能否成立的关键。

8.1 必须引入正式的 include 库

建议新增：

• engine/assets/shaderlib/ShaderLibrary/Core.hlsl
• engine/assets/shaderlib/ShaderLibrary/Common.hlsl
• engine/assets/shaderlib/ShaderLibrary/SpaceTransforms.hlsl
• engine/assets/shaderlib/ShaderLibrary/Lighting.hlsl
• engine/assets/shaderlib/ShaderLibrary/MaterialInput.hlsl
• engine/assets/shaderlib/ShaderLibrary/Shadow.hlsl

目标：

• builtin shader 共用统一宏与公共函数
• authoring 层不再重复声明一堆 per-object / lighting 结构

8.2 统一的内建常量组

建议统一为接近 Unity 的内建分组：

• UnityPerFrame 或 XCPerFrame
• UnityPerCamera 或 XCPerCamera
• UnityPerDraw 或 XCPerDraw
• UnityPerMaterial 或 XCPerMaterial

建议引擎内部最终保留 XC* 前缀实现名，但 authoring 宏层提供 Unity 风格别名。

8.3 内建纹理/采样器由 include 库与 reflection 管理

例如：

• 主纹理
• 阴影图
• 环境图
• sampler state

这些都不再由 .shader 手填 Resources(set,binding)。

---

9. Material 体系同步改造

shader 统一如果不带 material 一起改，最后会停在半路。

9.1 material 的职责边界

新体系里 material 负责：

• 选择 shader
• 保存 property override
• 保存 texture override
• 保存 keyword 开关
• 保存材质级 render queue / tag override（如保留）

新体系里 material 不再负责：

• 指定 shaderPass
• 硬编码 backend 资源名
• 猜测 shader 内的 descriptor set / binding

9.2 material constant buffer 正式化

必须建立：

• Properties -> UnityPerMaterial/XCPerMaterial 布局
• importer 生成 property layout
• material 按 layout 打包 GPU 常量
• layout/hash 进入 pipeline/material cache key

9.3 keyword 体系正式化

建议引入：

• global keywords
• local keywords
• material keyword set
• variant lookup key

material 应持有：

• ShaderKeywordSet

renderer 运行时根据：

• shader
• pass
• keyword set
• backend

选择最终 shader variant。

---

10. Renderer 运行时契约调整

10.1 pass 选择规则统一为 LightMode

renderer 选 pass 时只看：

• 当前 pipeline 阶段需要的 LightMode
• shader/subshader/pass 是否匹配
• backend 是否有有效 variant

例如：

• 主几何：ForwardLit / Unlit
• 阴影：ShadowCaster
• 深度：DepthOnly
• ObjectId：ObjectId
• FinalOutput：FinalColor

10.2 material 显式 shaderPass 进入弃用路径

建议执行顺序：

1. 第一阶段保留字段，但标记为 legacy
2. runtime 优先按 pass contract / LightMode 选 pass
3. 只有 legacy 资产才允许 fallback 到 shaderPass
4. migration 完成后移除 shaderPass 主路径职责

10.3 builtin pass metadata 继续保留，但收进 importer/runtime

当前基于 semantic 的 builtin pass binding 解析仍然有价值，但应改成：

• authoring/IR 层表达语义
• compiler/reflection 层生成 binding plan
• runtime 只消费 binding plan

而不是继续靠散落的名字匹配和 fallback。

---

11. 三后端统一策略

11.1 D3D12

目标：

• 直接消费 HLSL 编译产物
• 反射得到 root signature / resource layout 所需元数据

第一阶段可继续沿用 ps_5_0 / vs_5_0，但建议同时规划升级：

• 后续逐步转 SM 6.x

11.2 Vulkan

目标：

• 统一吃由 HLSL 编到 SPIR-V 的产物
• 摆脱独立 .vk.glsl 长期维护

11.3 OpenGL

目标：

• 不再长期维护独立 .glsl authoring 文件
• importer 自动生成 OpenGL 目标 GLSL 430

这一步会是整个阶段最大的工程风险之一，但它是“写法统一”绕不开的核心点。

11.4 迁移期间的策略

在新体系落稳前，允许：

• legacy backend-specific variant 继续存在
• 新 Unity 风格 shader 走统一 HLSL single-source 路径

两套 importer 并行一段时间，最终再逐步淘汰 legacy path。

---

12. 分阶段实施计划

Phase A：冻结目标与建立兼容边界

目标：

• 明确“什么叫 Unity 风格 shader”
• 明确 legacy 与新 authoring 的兼容边界

工作项：

1. 写清 Unity 风格支持子集。
2. 明确旧 .shader 的 legacy 模式规则。
3. 明确新 authoring 中禁止出现：
   • #pragma backend
   • Resources(set,binding)
4. 明确 material 中 shaderPass 的弃用策略。

完成标准：

• 文档、命名、兼容边界全部写死

Phase B：建立新的 Shader Authoring Parser 与 IR

目标：

• 新 .shader authoring 能导入到统一 ShaderIR

工作项：

1. 新增 parser，支持：
   • Shader / Properties / SubShader / Pass / Tags
   • HLSLINCLUDE / HLSLPROGRAM
   • #pragma vertex / fragment / target / multi_compile / shader_feature
   • pass state DSL
2. 生成 ShaderIR
3. 支持 include 依赖收集
4. 保留 legacy importer

完成标准：

• authoring parser 单测齐全
• 可以把一个 Unity 风格 shader 解析成稳定 IR

Phase C：建立单一 HLSL 编译链

目标：

• 打通 HLSL -> D3D12/Vulkan/OpenGL 编译管线

工作项：

1. 接入 DXC 编译 HLSL。
2. Vulkan 产出 SPIR-V。
3. OpenGL 产出 GLSL 430。
4. 建立 reflection 数据抽取：
   • cbuffer
   • texture
   • sampler
   • entry point
   • keywords
5. 缓存编译产物与依赖 hash。

完成标准：

• 一份 HLSL authoring 能生成三后端产物
• OpenGL 不再依赖手写 .glsl 作为新体系长期主路径

Phase D：Material 与 property/keyword/runtime binding 正式化

目标：

• material 能正式驱动新 shader artifact

工作项：

1. 引入正式 property layout。
2. 引入 material keyword set。
3. 生成 PerMaterial 常量缓冲布局。
4. texture/sampler 绑定从 reflection/约定生成。
5. 让 material 运行时不再关心 set/binding。

完成标准：

• material property / texture / keyword 真正接入 GPU 绑定链

Phase E：renderer pass 选择与 pipeline cache 收口

目标：

• renderer 完全按 pass contract 驱动 shader

工作项：

1. 按 LightMode 选 pass。
2. shaderPass 降级为 legacy fallback。
3. pipeline cache key 引入：
   • shader artifact id
   • pass id
   • keyword variant id
   • render state
4. builtin pass 的 runtime contract 全部切到新 artifact。

完成标准：

• renderer 主路径不再依赖 material 显式 pass 指定

Phase F：分批迁移 builtin shader

建议迁移顺序：

1. unlit
2. forward-lit
3. depth-only
4. shadow-caster
5. object-id
6. skybox
7. color-scale-post-process
8. final-color

完成标准：

• builtin shader 全部有新 authoring 版本
• 旧版 backend 分发文件不再是长期主定义来源

Phase G：文档、测试、旧路径收口

目标：

• 让新旧体系的边界最终收口

工作项：

1. 更新 tests/TEST_SPEC.md 中 shader/material 测试矩阵。
2. 增加 authoring parser / compiler / runtime 回归测试。
3. 更新开发文档。
4. 标记 legacy 路径弃用阶段。

完成标准：

• 新体系文档、测试、builtin 迁移都完成

---

13. 测试策略

13.1 Parser / Importer 单测

必须覆盖：

• Properties 解析
• SubShader / Pass / Tags 解析
• HLSLINCLUDE / HLSLPROGRAM 解析
• pragma 解析
• pass state 解析
• include 依赖收集
• legacy / 新 authoring 双路径兼容

13.2 Compiler 单测

必须覆盖：

• 单一 HLSL 源能生成三后端产物
• reflection 结果稳定
• keyword variant 正确展开
• 编译错误日志可读、可定位到 authoring 源文件

13.3 Material 单测

必须覆盖：

• property 默认值
• property override
• texture binding
• keyword set
• 常量缓冲布局打包

13.4 Rendering 单测

必须覆盖：

• renderer 按 LightMode 选 pass
• legacy shaderPass fallback 行为
• keyword variant 参与 pipeline cache key
• final color / post-process / shadow / object-id 不回退

13.5 集成测试

至少回归：

• material_state_scene
• transparent_material_scene
• camera_stack_scene
• directional_shadow_scene
• multi_light_scene
• skybox_scene
• post_process_scene
• final_color_scene
• object_id_scene

要求：

• 三后端全部跑通
• GT 不回退

---

14. 风险与控制策略

风险 1：OpenGL 是统一写法最难的一环

原因：

• OpenGL 当前直接吃 GLSL
• 统一 authoring 要求它改为编译链生成目标 GLSL

控制策略：

• 先把 importer/IR 做好
• OpenGL 先走“生成 GLSL 文本产物”路径
• legacy OpenGL GLSL 文件在迁移期保留 fallback

风险 2：一次性追 full Unity 语法会把阶段拖爆

控制策略：

• 明确 first-class 子集
• 先做 SRP 真正依赖的 authoring 基础
• 非关键语法延后

风险 3：material / pass 迁移会破坏当前 builtin renderer

控制策略：

• legacy runtime path 保留一段时间
• builtin shader 分批迁移
• 每迁移一个 shader 就跑对应 integration

风险 4：编译错误如果不可读，会极大拖慢落地

控制策略：

• 必须做 authoring 源到 backend 编译日志的映射
• 错误日志要带 shader 名、pass 名、stage、backend、源文件行号

---

15. 收口判定

满足下面条件时，本阶段可视为完成：

1. 新 .shader authoring 采用 Unity 风格子集。
2. 新体系 shader authoring 中不再出现 #pragma backend。
3. 新体系 shader authoring 中不再出现 Resources(set,binding)。
4. HLSL single-source 能生成 D3D12 / Vulkan / OpenGL 三后端产物。
5. material 已正式接入 property / keyword / texture binding runtime。
6. renderer 按 LightMode 正式选择 pass。
7. shaderPass 只剩 legacy fallback，不再是主路径。
8. builtin shader 已完成新体系迁移。
9. 三后端关键集成测试全部通过。

---

16. 与后续 SRP 的承接关系

这一阶段完成后，才能真正自然地承接：

• RenderPipelineAsset
• RenderPipeline
• RendererFeature
• ScriptableRenderPass
• C# 层对 shader/material/keyword 的控制

承接关系应当是：

Unity-style Shader Authoring
    -> Shader Importer / IR / Artifact
    -> Native Material & Pass Runtime
    -> Native Renderer Pass Contract
    -> C# SRP / RendererFeature

也就是说：

• 这一阶段不是 SRP
• 但这是 SRP 成立前必须先做完的最后一层底座

---

17. 一句话总结

当前 shader 体系不是没有，而是还停在“过渡态”。

下一阶段的正确方向不是继续堆更多 shader 功能，而是：

• 把 .shader 的 authoring 真正统一成 Unity 风格
• 把 backend 差异与 binding 细节收回 importer / compiler 层
• 把 material / pass / variant/runtime contract 一次性做正式

只有这样，后面的 SRP 才不会建立在一层伪统一的 shader 体系上。