XCEngine/docs/plan/Shader与Material系统下一阶段计划.md

# Shader 与 Material 系统下一阶段计划

日期：`2026-04-03`

## 1. 阶段结论

当前 Renderer 这一轮主线已经完成收口，但完成的是“基础运行时闭环”，不是“最终的 Unity 风格 shader/material 体系”。

已经完成并应视为当前基线的内容：

- `Shader` 运行时契约已具备 `properties / passes / resources / backend variants`
- builtin shader 资源已经外置，运行时不再依赖 C++ 内嵌 fallback
- `Material` 对 builtin forward 的基础属性解析已经优先走 shader semantic
- `BuiltinForwardPipeline` 已按 shader pass `resources` 合约生成 pipeline layout 与 descriptor binding
- `Shader` 已接入 `AssetDatabase / Library` 流程，shader import 会生成 `main.xcshader`
- `ShaderLoader` 已支持加载 `.xcshader` artifact
- shader manifest 依赖与 `Material -> Shader` 依赖已进入资产追踪链
- `rendering_unit_tests`
- `rendering_integration_textured_quad_scene`
- `rendering_integration_backpack_lit_scene`
- `shader_tests`
- `material_tests`

三后端验证当前是稳定的：

- D3D12：通过
- OpenGL：通过
- Vulkan：通过

但这仍然只是“Shader / Material Runtime 的第一层骨架”。

当前真正还没有完成的是：

- Unity 风格的 shader authoring 入口
- 正式的 material schema / instance contract
- 从 shader property layout 到 GPU material layout 的通用映射
- 从 builtin forward 扩展到更通用 pass 的正式执行模型

## 2. 旧计划归档说明

以下两份计划文档已经完成历史使命，应归入 `docs/used/`：

- `Renderer模块设计与实现.md`
- `Renderer下一阶段_ShaderMaterial与Pass体系设计.md`

原因不是它们“写错了”，而是：

- 第一份解决的是 Renderer 模块从无到有的问题，当前骨架已经落地
- 第二份解决的是“为什么下一阶段先做 shader/material/pass contract，而不是 render graph”的阶段判断；这份判断已经部分兑现，整体已过期

本文件接手它们之后的主线，只保留对当前 checkout 仍然有效的目标。

## 3. 当前真实问题

### 3.1 Shader 运行时有了，但 authoring 还没有正式化

现在的运行时已经能消费：

- shader property
- pass tag
- pass resource binding
- backend variant

但作者侧仍然不是最终形态。

当前还缺：

- 面向用户的 Unity 风格 `.shader` 语法入口
- import 阶段把 authoring 语法转换为 runtime contract 的正式流程
- shader 资产与 Library artifact 的稳定产物边界

### 3.2 Material 仍偏“资源容器”，还不是正式材质实例系统

当前 `Material` 已有：

- shader 引用
- render state
- property / texture 覆盖
- tag / queue

但它还缺少真正用于 Renderer 执行的正式约束：

- 基于 shader property schema 的类型验证
- property 默认值与 override 的统一解析
- per-pass material constant layout
- texture / sampler / buffer 到 pass resource 的正式映射
- renderer 侧可缓存、可失效、可复用的 material binding plan

### 3.3 现有 pass contract 仍偏 builtin-forward 视角

当前 forward 主链已经能跑，但完整的 pass contract 还没有正式化为可扩展系统。

后续至少要能稳定承接：

- `ForwardLit`
- `Unlit`
- `DepthOnly`
- `ShadowCaster`
- `ObjectId`

否则后面一旦开始做阴影、深度预通道、更多 editor/runtime helper pass，就会重新退化回 pipeline 内部的条件分支拼装。

### 3.4 三后端问题的本质不是“语法不同”，而是“资产如何统一”

当前真正要解决的，不是简单回答“到底用 GLSL 还是 HLSL”，而是明确三层边界：

1. 对外 authoring 语法是什么
2. import 后的内部运行时资产是什么
3. 每个 backend 最终执行的 variant 是什么

这三层不分开，后面一定会把 authoring、runtime、backend 编译链搅在一起。

## 4. 下一阶段的目标

下一阶段只做一件事：把 `Shader` 和 `Material` 从“能支撑当前 builtin forward 的运行时拼装”升级为“能长期承接 Unity 风格渲染架构的正式系统”。

### 4.1 对外 authoring 语法目标：严格向 Unity 对齐

最终对外公开的 shader 语法目标，必须与 Unity 的使用方式保持一致。

目标形态应当是：

- 单个 `.shader` 文件作为逻辑 shader 入口
- `Shader / Properties / SubShader / Pass` 的层级结构
- pass 内通过 `HLSLPROGRAM ... ENDHLSL` 或等价块组织代码
- 通过 `#pragma vertex` / `#pragma fragment` 指定 stage 入口

也就是说：

- 对外 authoring 视角应当是“Unity 风格的一体化 shader 文件”
- 不是要求作者直接去维护一堆 runtime JSON manifest
- 也不是让上层逻辑直接感知 D3D12/OpenGL/Vulkan 各自的底层差异

### 4.2 对内 runtime 资产目标：继续保留 contract 模型

虽然 authoring 目标要严格向 Unity 靠拢，但 runtime 不应直接拿 authoring AST 当执行数据。

运行时仍应落到清晰的 contract：

```text
Shader Asset
  -> Properties
  -> Passes
       -> Tags
       -> Resource Bindings
       -> Backend Variants
```

原因很直接：

- Renderer 需要稳定、扁平、可缓存的数据结构
- 三后端最终执行的仍然是 backend variant
- material schema 与 pass binding 都需要基于 import 结果，而不是原始文本

结论是：

- 外部写法要像 Unity
- 内部执行模型继续使用现在这套 runtime contract，并进一步完善

### 4.3 Material 目标：从资源对象升级为正式材质实例

Material 下一阶段的核心不是“多支持几个 SetFloat”，而是建立正式实例语义。

Material 至少要明确：

- 引用哪个 shader
- 使用哪个 pass 或 pass 策略
- 每个 property 的默认值、覆盖值、类型与序列化规则
- 每个 pass 对应的 material constant block 如何布局
- 每个 texture / sampler / buffer 如何映射到 pass resource

Renderer 侧则必须能把这些内容稳定编译成：

- material binding key
- material constant payload
- descriptor update plan
- pipeline compatibility key

## 5. 推荐架构

### 5.1 分成三层，不混写

推荐明确拆成三层：

```text
Unity-like Shader Authoring (.shader)
    -> Shader Importer
    -> Runtime Shader Contract
    -> Backend Variants / Material Binding Plan
```

三层职责分别是：

- authoring 层：给人写、给 editor 看
- importer 层：把 authoring 语法转成稳定运行时资产
- runtime 层：给 renderer 执行、缓存、绑定、测试

### 5.2 Shader 的 public contract 与 backend contract 分离

下一阶段不建议把“Unity 风格语法”直接等同于“单源码自动跨平台编译已完全成熟”。

更务实的路线是：

- public contract 先统一成 Unity 风格 `.shader`
- importer 先产出统一 runtime contract
- backend variant 暂时仍允许按 backend 持有各自的编译输入或中间产物

这意味着：

- 作者看到的是统一 shader
- Renderer 消费的是统一 runtime contract
- backend 最终执行的仍然可以是不同 variant

这个分层既不违背 Unity 风格目标，也不会过早把工程拖进复杂的全平台 shader 编译链泥潭。

### 5.3 Vertex / Fragment 的外部写法按 Unity 组织，内部可拆分

对外语义上，vertex / fragment 应当属于同一个 pass。

也就是说，public authoring 角度要符合 Unity：

- 一个 shader
- 一个或多个 subshader
- 一个或多个 pass
- 每个 pass 里通过 pragma 指定 vertex / fragment

但内部 import/runtime 完全可以把它们拆成：

- pass descriptor
- vertex stage variant
- fragment stage variant

外部合一，内部拆开，这是最稳妥的做法。

## 6. 下一阶段实施顺序

### 阶段 D0：先打通 Shader Import / Artifact 基础设施（已完成）

这是当前 checkout 在 `2026-04-03` 已经完成的新增里程碑。

完成内容：

- `ShaderImporter` 已接管 `.shader / .hlsl / .glsl / .vert / .frag / .geom / .comp`
- shader import 结果会写入 `Library/Artifacts/.../main.xcshader`
- `ShaderLoader` 已支持直接读取 `.xcshader`
- shader manifest 中声明的 stage 源文件会进入依赖追踪
- `Material` 对引用 shader 的直接依赖也已进入依赖追踪
- `shader_tests` 与 `material_tests` 已覆盖 shader artifact 生成、加载与重导场景

这一步的意义不是“最终方案已完成”，而是先把 shader 纳入和 texture/material/mesh 一致的资产闭环。

没有这一步，后续不管做 Unity 风格 frontend，还是做 material schema，都会一直建立在“运行时临时解析源码”的不稳定基础上。

### 阶段 0：当前基线确认

这部分已经完成，不再作为待办：

- runtime shader contract 已建立
- builtin forward 已按 pass resources 驱动
- 三后端渲染回归通过

### 阶段 A：建立 Unity 风格 Shader Authoring Frontend

目标：

- 新增 Unity 风格 `.shader` authoring 入口
- importer 能解析最小闭环子集

第一批建议支持的子集：

- `Shader`
- `Properties`
- `SubShader`
- `Tags`
- `Pass`
- `HLSLPROGRAM / ENDHLSL`
- `#pragma vertex`
- `#pragma fragment`

交付标准：

- builtin `forward-lit`
- builtin `unlit`
- builtin `object-id`
- builtin `infinite-grid`

至少迁移其中一条主线并成功跑通三后端测试。

### 阶段 B：建立正式的 Material Schema 与 Instance Contract

目标：

- shader importer 输出可供 material 消费的 property schema
- material 对 property override 做类型校验与默认值回退
- 为 pass 生成 material constant layout 与 resource mapping

交付标准：

- material 不再只靠 builtin alias 名字兜底
- shader property semantic 变成正式主路径，而不是兼容性补丁
- renderer 能从 shader schema 生成 material binding payload

当前建议把这一阶段作为下一步主线。

原因：

- shader artifact 与依赖追踪已经到位，shader 现在可以作为稳定 schema 来源
- material 仍然缺少基于 shader property 的正式类型校验、默认值回退和资源映射
- renderer 目前虽然能消费 pass resources，但 material binding 仍偏 builtin-forward 特判

当前进展（`2026-04-03`）：

- 已完成：shader schema 驱动的 property 类型校验与默认值回退
- 已完成：source `.material` 的 `properties` authoring 入口
- 已完成：material constant layout runtime contract
  - `Material` 现在会生成正式的 constant layout 元数据
  - layout 字段包含 `name / type / offset / size / alignedSize`
  - renderer 读取的已不再只是裸字节 payload，而是 `layout + payload` 组合
- 已完成：builtin pass resource mapping / material binding plan runtime contract
  - `RenderMaterialUtility` 现在统一提供 `PassResourceBindingLocation / BuiltinPassResourceBindingPlan`
  - 显式 shader pass `resources` 与 legacy builtin forward fallback 已走同一套解析与校验路径
  - `BuiltinForwardPipeline` 已改为消费通用 binding plan，而不是继续内联 forward 特判绑定逻辑
- 已验证：`rendering_unit_tests` 57/57，`material_tests` 51/51
- 下一步：把这套 pass binding plan 继续推到 `Unlit / ObjectId` 等 pass，收敛成真正共享的 shader/material 执行边界

### 阶段 C：把 Pass Binding 扩展为正式材质执行链路

目标：

- 不只是 builtin forward 能吃 pass resources
- `Unlit`、`ObjectId` 也逐步切到同一套 shader/material contract
- pipeline state key 与 descriptor binding plan 从“按功能写逻辑”升级到“按 shader pass contract 解析”

交付标准：

- 至少 `ForwardLit + Unlit + ObjectId` 共用同一套 shader/material 执行边界
- 新增 pass 不再默认要求先写一套新的硬编码 binding 路径

当前进展（`2026-04-03`）：

- 已完成：builtin `ObjectId` pass 接入通用 pass binding plan
  - builtin object-id shader 已显式声明 `PerObject` 资源合约
  - `BuiltinObjectIdPass` 已改为消费通用 binding plan，不再硬编码 `set0/binding0` 常量布局
  - 显式 shader `resources` 与 legacy object-id fallback 现在走同一套解析与校验路径
- 已完成：builtin `Unlit` shader / pipeline 主线接入共享执行边界
  - 新增 builtin `unlit` shader 资产与 `BuiltinResources` 入口
  - `BuiltinForwardPipeline` 现在会在 `ForwardLit + Unlit` 之间按 material/shader metadata 解析目标 pass
  - `Unlit` 与 `ForwardLit` 现在共用同一套 input layout、material schema、binding plan 与 descriptor 组装路径
- 已验证：`rendering_unit_tests` 61/61，`shader_tests` 27/27，`material_tests` 51/51
- 下一步：评估是否抽出 `ForwardLit / Unlit / ObjectId` 共用的 pass layout 构建与 descriptor set 组装骨架，并继续推进 `DepthOnly / ShadowCaster`

### 阶段 D：扩展 AssetDatabase / Library Artifact 能力

目标：

- 在已完成的 shader artifact 基础上，继续扩展 import 产物边界
- backend variant 的编译输入、中间产物或缓存策略进入 `Library/Artifacts`
- 为后续 Unity 风格 `.shader` frontend 预留稳定 importer 输出层

交付标准：

- 资源改动能够稳定触发 shader/material 重新导入
- editor/runtime 读取的是 import 后资产，不是源码临时解析
- shader importer 不再只服务当前 JSON manifest 兼容路径，也能承接下一步 authoring frontend

### 阶段 E：测试与回归收口

目标：

- 给 shader importer、material schema、binding plan 增加 unit tests
- 对 forward/unlit/object-id 增加 integration coverage
- 保持 D3D12 / OpenGL / Vulkan 一致回归

最低验证集：

- `shader_tests`
- `material_tests`
- `rendering_unit_tests`
- `rendering_integration_textured_quad_scene`
- `rendering_integration_backpack_lit_scene`

必要时新增：

- `rendering_integration_unlit_scene`
- `rendering_integration_object_id_scene`

当前进展（`2026-04-04`）：

- 已完成：`rendering_integration_unlit_scene`
  - 显式使用 builtin `unlit` shader + `Unlit` pass，覆盖 `BuiltinForwardPipeline` 的 `ForwardLit / Unlit` pass 选择路径
  - 复用 `textured_quad_scene` 构图做最小差异回归，验证 shader/material 新 contract 不改变既有画面输出
- 已验证：`rendering_integration_unlit_scene`
  - D3D12：通过
  - OpenGL：通过
  - Vulkan：通过
- 下一步：补 `rendering_integration_object_id_scene` 或等价的 object-id integration coverage，完成本阶段收口

## 7. 当前阶段明确不做

下一阶段不应把范围扩散到下面这些方向：

- render graph
- shader graph
- 全平台单源码自动转译一次性做完
- 完整 SRP scripting API
- 大规模后处理框架

这些都依赖 shader/material 正式体系先稳定下来。

## 8. 成功标准

这个阶段完成时，应该满足下面几个判断：

- 作者侧已经可以写 Unity 风格的 `.shader`
- runtime 已不再依赖手写 JSON manifest 才能描述 pass contract
- material 能基于 shader schema 做正式绑定，而不是 builtin 特判兜底
- 至少 `ForwardLit / Unlit / ObjectId` 三类 pass 共用统一 shader/material 执行边界
- 三后端回归测试仍稳定通过

## 9. 一句话总结

下一阶段不是继续给 builtin forward 打补丁，而是把 `Shader` 和 `Material` 正式提升为 Unity 风格渲染架构中的稳定中层资产与执行契约。