XCEngine/docs/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.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-04`）：

- 已完成：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 组装路径
- 已完成：抽出 `ForwardLit / Unlit / ObjectId` 共用的 pass layout / descriptor set 组装骨架
  - `RenderMaterialUtility` 现在统一提供 `BuiltinPassSetLayoutMetadata` 与 `TryBuildBuiltinPassSetLayouts(...)`
  - `BuiltinForwardPipeline` 与 `BuiltinObjectIdPass` 现在都复用同一套 `binding plan -> set layout -> pipeline layout` 组装路径
  - forward 侧只保留 set0 compatibility fallback 与 draw/update 逻辑；object-id 侧只保留自身约束校验与 per-object 常量写入
- 已完成：builtin `DepthOnly / ShadowCaster` shader 与独立 pass skeleton 落地
  - 新增 builtin `depth-only` 与 `shadow-caster` shader 资产，以及 `BuiltinResources` 对应入口
  - 新增 `BuiltinDepthOnlyPass / BuiltinShadowCasterPass`，作为独立 `RenderPass` 复用同一套 shared pass-layout skeleton
  - 两个 pass 当前先收敛到 `PerObject` 常量路径；opaque 物体走 builtin fallback，`ShadowCaster` 额外尊重 `MeshRenderer.castShadows`
  - 这一步解决的是“pass contract 与执行骨架缺失”，还没有把 shadow map / light-space request flow 一次性做完
- 已完成：`CameraRenderRequest + CameraRenderer` 正式接入 `DepthOnly / ShadowCaster` request 流程
  - 新增 `depthOnly / shadowCaster` request，支持独立 surface、clear flags / clear color，以及可选 `RenderCameraData` override
  - `CameraRenderer` 现在按 `ShadowCaster -> DepthOnly -> Forward -> ObjectId` 的顺序执行这些请求，`BuiltinDepthStylePassBase` 也会按 request clear flags 清理目标
- 已验证：`rendering_unit_tests` 73/73
- 已验证：`rendering_integration_textured_quad_scene` 3/3（D3D12 / OpenGL / Vulkan）
- 已验证：`rendering_integration_unlit_scene` 3/3（D3D12 / OpenGL / Vulkan）
- 已验证：`rendering_integration_object_id_scene` 3/3（D3D12 / OpenGL / Vulkan）
- 下一步：如果继续沿 renderer 主线收口，优先补 `DepthOnly / ShadowCaster` 的真实 cross-backend integration coverage，并决定是否把 shadow-map 结果继续接回 forward lighting 消费链；如果先控制范围，request 流程这一块已经收口

### 阶段 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 scene，直接验证 object-id 输出采样点，而不是再维护一张新的大尺寸 GT 图片
  - 覆盖 `CameraRenderer + BuiltinObjectIdPass` 路径，以及 `Forward -> ObjectId -> Copy/Screenshot` 的跨 pass 回归
  - 修正了 `BuiltinObjectIdPass` 在 Vulkan 下的顶点输入步长问题，并让 object-id pass 自己清理/写入 depth，避免依赖前一 pass 的 depth 复用状态
- 已验证：`rendering_integration_object_id_scene`
  - D3D12：通过
  - OpenGL：通过
  - Vulkan：通过
- 阶段 E 当前状态：`unlit_scene` 与 `object_id_scene` 均已完成并通过三后端验证，本阶段可以收口

## 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 风格渲染架构中的稳定中层资产与执行契约。

## 10. 快速收口策略（`2026-04-04`）

目标收窄为只处理 `shader / material` 核心主线，不继续扩散到完整阴影功能、render graph、shader graph 或 editor 外围能力。

按下面顺序收口：

1. 先完成 Unity-like `.shader` authoring MVP importer  
   - 允许最小子集：`Shader / Properties / SubShader / Tags / Pass / HLSLPROGRAM / #pragma vertex / #pragma fragment`
   - importer 输出继续复用当前 runtime shader contract：`properties / passes / resources / backend variants`
   - 这一阶段不追求完整 Unity ShaderLab，只做 builtin 与主线材质系统需要的最小闭环

2. 再迁移 builtin shader 到新 authoring 入口  
   - 优先 `ForwardLit / Unlit / ObjectId / DepthOnly / ShadowCaster`
   - 要求 importer 产出的 runtime contract 与当前 renderer 消费路径保持一致

3. 然后收紧 material 主路径  
   - 以 imported shader schema 为主路径完成 property 类型校验、默认值回退、constant layout 与 resource mapping
   - builtin alias / canonical-name fallback 只保留兼容兜底，不再作为主执行路径

4. 最后做最小回归集收口  
   - `shader_tests`
   - `material_tests`
   - `rendering_unit_tests`
   - 必要的 rendering integration smoke

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

- 已完成：Step 1 `Unity-like .shader authoring MVP importer`
  - `ShaderLoader` 新增 Unity-like `.shader` authoring 识别与解析入口，但保留现有 JSON manifest `.shader` 兼容路径不动
  - importer 继续落到现有 runtime shader contract：`properties / passes / resources / backend variants`
  - `CollectSourceDependencies` 已覆盖新 authoring 路径，`AssetDatabase` 会继续追踪各 backend stage 文件依赖并参与重导入
- 已完成：Step 2 `builtin shader 迁到新 authoring 入口`
  - `forward-lit / unlit / object-id / depth-only / shadow-caster` 五个 builtin `.shader` 入口已全部切到 Unity-like authoring
  - stage 源文件、builtin shader 路径与 renderer 消费 contract 保持不变，迁移只发生在 authoring 入口层
  - 补充 `DepthOnly / ShadowCaster` builtin shader loader 覆盖，确保五类 builtin pass 都经过新 authoring 路径验证
- 已完成：Step 3 `material 主路径收紧到 imported shader schema`
  - `MaterialLoader` 在存在 shader schema 时，`properties / textures` 中的旧 key 会先解析到 shader property semantic，再落到 shader 正式属性名
  - 旧的 `baseColor / baseColorTexture` 等兼容 key 仍可导入，但只作为兼容输入存在，不再直接污染 material 主执行路径
  - 当 material 绑定 shader schema 后，未知 texture binding 现在会被显式拒绝，不再静默忽略
- 已验证：`shader_tests` 中新增 authoring 直载与 artifact/reimport 覆盖
- 已验证：`shader_tests` 31/31 通过，builtin `ForwardLit / Unlit / ObjectId / DepthOnly / ShadowCaster` 全部通过加载与 backend variant 覆盖
- 已验证：`material_tests` 53/53 通过，schema 驱动的 property/texture 映射与未知 binding 拒绝路径都已覆盖
- 已完成：Step 4 `最小回归集收口`
  - `rendering_unit_tests` 73/73 通过，builtin pass contract 与 renderer 侧消费路径在当前重构后保持稳定
  - 本轮最小回归集结果：`shader_tests` 31/31，`material_tests` 53/53，`rendering_unit_tests` 73/73
  - 以当前目标范围看，`shader / material` 核心主线已经可以阶段性收口
- 补充验收（`2026-04-04`）：
  - 补跑 integration smoke 时发现并修复了一处真实回归：Unity-like `.shader` authoring 将 HLSL 的 `MainVS / MainPS` 入口错误套到了 GLSL/Vulkan variant，上层表现为 Vulkan `BuiltinForwardPipeline` 建 pipeline 失败
  - 修复后补跑 `rendering_integration_textured_quad_scene` 与 `rendering_integration_unlit_scene`、`rendering_integration_object_id_scene`，三者在 `D3D12 / OpenGL / Vulkan` 下均通过
  - 额外补跑 `rendering_integration_backpack_lit_scene` 时，暴露出一条相邻但不同范围的问题：direct `MeshLoader` 导入的 mesh/material/texture 生命周期路径存在异常退出/不干净收尾，已超出本次 `shader / material contract` 收口范围
  - 因此本计划按“核心主线已收口，附带一条相邻 residual risk”归档；若后续继续补强，优先单独开一轮处理 `MeshLoader + imported subresource lifetime`
- 下一步：从当前目标范围出发，本计划可归档；后续如继续推进，请以新计划承接 `backpack_lit_scene` 这条相邻问题

当前阶段明确不做：

- 完整阴影贴图消费链
- render graph
- shader graph
- 完整 Unity ShaderLab 全语法
- 与 shader/material 主线无关的 editor/ui 扩展