XCEngine/docs/used/Renderer下一阶段_CameraPostProcess描述层正式化计划_完成归档_2026-04-06.md

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 配置入口

本阶段的核心收口标准已经满足，可以提交归档。