Formalize camera post-process descriptors

docs/plan/Renderer下一阶段_CameraPostProcess描述层正式化计划_2026-04-06.md

@@ -0,0 +1,127 @@
+# Renderer 下一阶段: Camera PostProcess 描述层正式化计划
+
+日期: `2026-04-06`
+
+## 1. 阶段目标
+
+在已经完成 runtime `SceneColor -> PostProcess -> FinalOutput` 主链收口的基础上，
+把相机上的后处理配置从临时的 `ColorScale` 专用字段，提升为正式的描述层。
+
+这一阶段只解决一件事:
+
+- `CameraComponent` 持有正式的 post-process pass 描述
+- `SceneRenderer` 通过工厂把描述翻译成 runtime pass sequence
+- 旧的 `ColorScale` 接口继续兼容，旧场景序列化继续可读
+
+## 2. 已完成内容
+
+### 2.1 相机后处理描述层
+
+已新增:
+
+- `CameraPostProcessPassType`
+- `CameraPostProcessPassDesc`
+- `CameraPostProcessStack`
+
+当前首个正式 builtin effect 仍然是:
+
+- `ColorScale`
+
+但它已经不再通过 `CameraComponent -> vector<Vector4> -> SceneRenderer if/for` 这种硬编码链路传递。
+
+### 2.2 CameraComponent 正式化
+
+已完成:
+
+- `CameraComponent` 内部存储迁移到 `CameraPostProcessStack`
+- 新增通用接口:
+  - `GetPostProcessPasses`
+  - `SetPostProcessPasses`
+  - `AddPostProcessPass`
+  - `ClearPostProcessPasses`
+- 旧接口继续保留:
+  - `SetColorScalePostProcessEnabled`
+  - `SetColorScalePostProcessScale`
+  - `SetColorScalePostProcessPasses`
+  - `GetColorScalePostProcessPasses`
+
+兼容规则:
+
+- 旧接口继续映射到 `ColorScale` 类型的描述
+- 新格式序列化写出正式 `postProcessPassN*` 字段
+- 反序列化同时兼容旧的 `colorScalePostProcess*` 字段
+
+### 2.3 SceneRenderer 工厂翻译层
+
+已完成:
+
+- 从 `SceneRenderer` 中移除 `ColorScale` 专用硬编码构造
+- 新增 `BuildCameraPostProcessPassSequence(...)`
+- `SceneRenderer` 现在只关心:
+  - 读取相机的 `CameraPostProcessStack`
+  - 为 post-process 分配 source surface
+  - 调用工厂生成 `RenderPassSequence`
+
+这意味着后续增加新的 builtin camera post-process 时，
+修改点已经收缩到描述层和工厂，而不是继续把分支堆进 `SceneRenderer`。
+
+## 3. 验证结果
+
+### 3.1 构建
+
+已通过:
+
+- `cmake --build --preset debug --target components_tests rendering_unit_tests rendering_integration_camera_post_process_scene rendering_integration_post_process_scene -- /m:1`
+
+### 3.2 单元测试
+
+已通过:
+
+- `components_tests --gtest_filter=CameraComponent_Test.*`
+- `rendering_unit_tests --gtest_filter=SceneRenderer_Test.*:CameraRenderer_Test.*`
+
+覆盖点包括:
+
+- 新描述层 round-trip
+- 旧 `ColorScale` 字段反序列化兼容
+- `SceneRenderer` 从 camera post-process stack 构建正式 request
+
+### 3.3 集成测试
+
+已通过:
+
+- `rendering_integration_camera_post_process_scene`
+  - D3D12
+  - OpenGL
+  - Vulkan
+- `rendering_integration_post_process_scene`
+  - D3D12
+  - OpenGL
+  - Vulkan
+
+说明:
+
+- `camera_post_process_scene` 验证 formal scene path
+- `post_process_scene` 保留为 manual / low-level multi-pass 覆盖
+
+## 4. 当前结论
+
+这一阶段已经完成。
+
+当前 renderer 在 camera post-process 这一层，已经从“单个效果的临时接线”升级为“正式描述 + 工厂翻译”的结构。
+
+但现阶段仍然有两个边界:
+
+- 描述层虽然正式化了，但当前 builtin effect 仍只有 `ColorScale`
+- editor / asset / material 侧还没有把 camera post-process 做成完整的资产化与配置面板体系
+
+## 5. 下一步建议
+
+下一步不要回头继续往 `SceneRenderer` 里塞特判，而应沿着下面的方向推进:
+
+1. 继续扩展 `CameraPostProcessPassDesc`
+   - 例如 tone mapping / exposure / gamma / final color transform
+2. 让新的 builtin camera effect 继续只经过“描述层 + 工厂”
+3. 等 shader/material 主线更稳定后，再决定 camera post-process 的资产化形式和 editor 配置入口
+
+本阶段的核心收口标准已经满足，可以提交归档。