docs(rendering): document builtin final color pass API

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md

@@ -6,35 +6,47 @@
 
 **头文件**: `XCEngine/Rendering/Passes/BuiltinFinalColorPass.h`
 
-**描述**: final-color 阶段的 fullscreen pass，负责把 `ResolvedFinalColorPolicy` 应用到最终输出颜色上。
+**描述**: final-color 阶段的 fullscreen pass，负责把曝光、tone mapping、output transfer 与最终颜色缩放应用到最终输出颜色附件上。
 
-## 概览
+## 概述
 
-`BuiltinFinalColorPass` 位于 post-process 之后、最终回写目标表面之前。它当前统一承载：
+`BuiltinFinalColorPass` 处在 post-process 之后、最终回写目标表面之前。它当前统一承载：
 
 - output transfer
 - exposure
 - tone mapping
 - final color scale
 
-对应的参数通过 `FinalColorSettings` 或 `ResolvedFinalColorPolicy` 注入。
+对应参数通过 [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md) 注入；真正的源颜色来自 `RenderPassContext::sourceColorView`，目标颜色来自 `context.surface` 的唯一颜色附件。
 
-## 当前公开能力
+## 公开类型
 
-- 构造时指定 `FinalColorSettings` 和可选 `shaderPath`
+- [OwnedDescriptorSet](OwnedDescriptorSet.md)
-- `GetName()` / `Execute(...)` / `Shutdown()`
+
-- `SetSettings(...)` / `GetSettings()`
+## 公开方法
-- `SetShaderPath(...)` / `GetShaderPath()`
+
+| 方法 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 构造 final-color pass，并可选指定自定义 shader 路径。 |
+| [Destructor](Destructor.md) | 析构时释放内部 GPU 资源。 |
+| [GetName](GetName.md) | 返回固定 pass 名称。 |
+| [Execute](Execute.md) | 执行 fullscreen final-color 绘制。 |
+| [Shutdown](Shutdown.md) | 主动释放当前持有的 GPU 资源。 |
+| [SetSettings](SetSettings.md) | 更新曝光、tone mapping 与颜色缩放配置。 |
+| [GetSettings](GetSettings.md) | 读取当前配置。 |
+| [SetShaderPath](SetShaderPath.md) | 切换 final-color shader 路径，并使资源缓存失效。 |
+| [GetShaderPath](GetShaderPath.md) | 读取当前 shader 路径。 |
 
 ## 当前实现边界
 
-- 它只负责 final-color 阶段，不解析相机 override 或 pipeline 默认值。
+- 它只消费已经规划好的 [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)，不负责解析相机 override 或 pipeline 默认策略。
-- `SceneRenderer` 先在 planning 阶段解析 [ResolvedFinalColorPolicy](../../Planning/FinalColorSettings/FinalColorSettings.md)，再通过 factory 创建当前 pass。
+- 当前实现要求 source surface 与 destination surface 都是“单颜色附件”形态；不支持 MRT，也不使用深度附件。
-- 和其他 fullscreen pass 一样，它依赖 `RenderPassContext::sourceColorView`，不会自己管理中间表面生命周期。
+- 构造函数会在传入空路径时自动回退到 builtin final-color shader；但后续若显式调用 `SetShaderPath("")`，资源创建会因为空路径而失败，直到重新设置为非空路径。
+- GPU 资源缓存会随着 backend、目标格式、sample count、sample quality 和 shader path 变化而失效；[SetSettings](SetSettings.md) 本身只更新常量，不会重建 pipeline。
 
 ## 真实接入位置
 
-- `SceneRenderer::ResolveCameraFinalColorPolicies(...)` 先解析策略。
+- `SceneRenderer` 先在 planning 阶段解析 `FinalColorSettings`。
 - `BuildFinalColorPassSequence(...)` 根据策略决定是否创建当前 pass。
 - `CameraRenderer` 在 `postProcess` 之后、`objectId` 之前执行 final-output 阶段。
 
@@ -44,3 +56,4 @@
 - [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)
 - [FinalColorPassFactory](../../Planning/FinalColorPassFactory/FinalColorPassFactory.md)
 - [BuiltinColorScalePostProcessPass](../BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)
+- [RenderPass](../../RenderPass/RenderPass.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/Constructor.md

@@ -0,0 +1,26 @@
+# BuiltinFinalColorPass::BuiltinFinalColorPass
+
+构造 final-color pass，并初始化设置与 shader 路径。
+```cpp
+explicit BuiltinFinalColorPass(
+    const FinalColorSettings& settings = {},
+    Containers::String shaderPath = {});
+```
+
+## 参数
+
+- `settings` - 初始的 final-color 配置。
+- `shaderPath` - 可选自定义 shader 路径；传空时会自动回退到 builtin final-color shader。
+
+## 当前语义
+
+- 构造函数只保存 CPU 侧配置，不会立即创建 GPU 资源。
+- 如果 `shaderPath.Empty()`，构造函数会改写成 `Resources::GetBuiltinFinalColorShaderPath()`。
+- 真正的 pipeline、sampler、descriptor set 与 shader 资源会在第一次 [Execute](Execute.md) 时按目标 surface 延迟创建。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [Execute](Execute.md)
+- [SetShaderPath](SetShaderPath.md)
+- [SetSettings](SetSettings.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/Destructor.md

@@ -0,0 +1,21 @@
+# BuiltinFinalColorPass::~BuiltinFinalColorPass
+
+析构函数会兜底释放当前持有的 GPU 资源。
+```cpp
+~BuiltinFinalColorPass() override;
+```
+
+## 当前语义
+
+- 实现直接调用 [Shutdown](Shutdown.md)。
+- 因此即便调用方忘记手动 `Shutdown()`，析构时也会回收 pipeline、pipeline layout、sampler、descriptor pool / set 与 shader 句柄。
+
+## 当前实现边界
+
+- 析构只负责当前 pass 自己持有的 GPU 资源，不管理 source / destination surface 或外部传入的 `RenderPassContext` 资源。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [Shutdown](Shutdown.md)
+- [OwnedDescriptorSet](OwnedDescriptorSet.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/Execute.md

@@ -0,0 +1,39 @@
+# BuiltinFinalColorPass::Execute
+
+执行一次 fullscreen final-color 绘制。
+```cpp
+bool Execute(const RenderPassContext& context) override;
+```
+
+## 参数
+
+- `context` - 当前渲染上下文、source surface / source color view，以及目标 `RenderSurface` 的组合描述。
+
+## 返回值
+
+- 成功完成 final-color 绘制返回 `true`；前置条件不满足或 GPU 资源初始化失败时返回 `false`。
+
+## 当前语义
+
+- 要求 `context.renderContext` 有效，且 `context.sourceSurface` 与 `context.sourceColorView` 非空。
+- 要求 source surface 与 destination surface 都是“恰好一个有效颜色附件”的形态。
+- 会校验 destination `RenderSurface::GetRenderArea()` 的宽高必须大于 `0`。
+- 资源未就绪时会调用内部初始化逻辑；若 backend、目标格式、sample count、sample quality 或 shader path 发生变化，会先销毁旧资源再重建。
+- 每次执行都会把 [FinalColorSettings](GetSettings.md) 写入常量缓冲；source 纹理 descriptor 只有在 `sourceColorView` 变化时才会重新绑定。
+- destination surface 开启自动状态切换时，会把目标颜色附件从 `GetColorStateBefore()` 切到 `RenderTarget`，绘制完成后再切回 `GetColorStateAfter()`。
+- source surface 开启自动状态切换时，会把 `sourceColorView` 从 `context.sourceColorState` 切到 `PixelShaderResource`，结束后再切回原状态；若 source 关闭自动切换，则 `context.sourceColorState` 必须已经是 `PixelShaderResource`。
+- 绘制路径会设置 render target、viewport、scissor、triangle-list 拓扑、pipeline state 和 3 组 descriptor set，然后发出一次 `Draw(3, 1, 0, 0)`。
+
+## 当前实现边界
+
+- 当前实现不使用深度附件，也不处理多颜色附件输出。
+- 是否执行 final-color pass，本身由上层 planning / factory 决定；这里不负责策略选择。
+- 当前仓库里没有直接以 `BuiltinFinalColorPass` 命名的独立单元测试，更多约束来自 `SceneRenderer` 的 final-output 链路。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [Shutdown](Shutdown.md)
+- [SetSettings](SetSettings.md)
+- [RenderPass](../../RenderPass/RenderPass.md)
+- [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/GetName.md

@@ -0,0 +1,20 @@
+# BuiltinFinalColorPass::GetName
+
+返回当前 pass 的固定名称。
+```cpp
+const char* GetName() const override;
+```
+
+## 返回值
+
+- 固定返回字符串 `BuiltinFinalColorPass`。
+
+## 当前语义
+
+- 返回值不依赖 `FinalColorSettings`、backend 或 shader 路径。
+- 它主要用于调试、日志和统一的 pass 标识。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [Execute](Execute.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/GetSettings.md

@@ -0,0 +1,21 @@
+# BuiltinFinalColorPass::GetSettings
+
+返回当前保存的 final-color 配置。
+```cpp
+const FinalColorSettings& GetSettings() const;
+```
+
+## 返回值
+
+- 返回内部保存的 `FinalColorSettings` 引用。
+
+## 当前语义
+
+- 这里返回的是 CPU 侧配置快照，而不是 shader 常量缓冲的即时读回结果。
+- 若调用方先执行了 [SetSettings](SetSettings.md) 但尚未调用 [Execute](Execute.md)，这里已经能读到最新配置。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [SetSettings](SetSettings.md)
+- [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/GetShaderPath.md

@@ -0,0 +1,21 @@
+# BuiltinFinalColorPass::GetShaderPath
+
+返回当前保存的 final-color shader 路径。
+```cpp
+const Containers::String& GetShaderPath() const;
+```
+
+## 返回值
+
+- 返回内部保存的 `shaderPath` 引用。
+
+## 当前语义
+
+- 构造函数若收到空路径，会先把它替换成 builtin final-color shader 路径，因此默认情况下这里返回的是非空 builtin 路径。
+- 如果调用方后续显式执行 [SetShaderPath](SetShaderPath.md) 并传入空字符串，这里也会如实返回空路径。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [SetShaderPath](SetShaderPath.md)
+- [Constructor](Constructor.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/OwnedDescriptorSet.md

@@ -0,0 +1,26 @@
+# BuiltinFinalColorPass::OwnedDescriptorSet
+
+描述 `BuiltinFinalColorPass` 内部把“descriptor pool + descriptor set”作为一组资源一起持有的轻量结构。
+```cpp
+struct OwnedDescriptorSet {
+    RHI::RHIDescriptorPool* pool = nullptr;
+    RHI::RHIDescriptorSet* set = nullptr;
+};
+```
+
+## 字段
+
+- `pool` - 用来分配该 descriptor set 的 pool。
+- `set` - 实际绑定到图形管线的 descriptor set。
+
+## 当前语义
+
+- `BuiltinFinalColorPass` 用它分别管理常量、纹理和采样器三组 descriptor 资源。
+- 结构本身不提供独立生命周期函数；真正的释放逻辑由 pass 内部的 `DestroyOwnedDescriptorSet(...)` 和 [Shutdown](Shutdown.md) 统一处理。
+- 这里暴露的是原始指针打包结果，不附带所有权转移语义。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [Shutdown](Shutdown.md)
+- [Execute](Execute.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/SetSettings.md

@@ -0,0 +1,23 @@
+# BuiltinFinalColorPass::SetSettings
+
+更新当前 final-color 配置。
+```cpp
+void SetSettings(const FinalColorSettings& settings);
+```
+
+## 参数
+
+- `settings` - 新的曝光、tone mapping、output transfer 与最终颜色缩放配置。
+
+## 当前语义
+
+- 这个 setter 只更新 `m_settings`，不会立即创建或重建 GPU 资源。
+- 新配置会在下一次 [Execute](Execute.md) 时被写入常量缓冲并立即生效。
+- 因为 pipeline 选择不依赖 `FinalColorSettings`，这里只改配置不会触发资源失效。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [GetSettings](GetSettings.md)
+- [Execute](Execute.md)
+- [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/SetShaderPath.md

@@ -0,0 +1,28 @@
+# BuiltinFinalColorPass::SetShaderPath
+
+切换当前 final-color shader 路径，并使已有资源缓存失效。
+```cpp
+void SetShaderPath(const Containers::String& shaderPath);
+```
+
+## 参数
+
+- `shaderPath` - 新的 shader 资源路径。
+
+## 当前语义
+
+- 如果传入路径与当前 `m_shaderPath` 相同，函数直接返回，不做任何事。
+- 路径发生变化时，会先销毁现有 GPU 资源，然后再保存新的路径字符串。
+- 后续下一次 [Execute](Execute.md) 会按新的路径重新加载 shader 并创建 pipeline。
+
+## 当前实现边界
+
+- 与构造函数不同，这个 setter 不会在空字符串时自动回退到 builtin shader；如果显式传入空路径，后续资源创建会失败。
+- 它只让资源缓存失效，不会立即触发重建。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [GetShaderPath](GetShaderPath.md)
+- [Constructor](Constructor.md)
+- [Execute](Execute.md)

docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/Shutdown.md

@@ -0,0 +1,24 @@
+# BuiltinFinalColorPass::Shutdown
+
+主动释放当前持有的 GPU 资源。
+```cpp
+void Shutdown() override;
+```
+
+## 当前语义
+
+- 实现直接调用内部 `DestroyResources()`。
+- 会回收 pipeline state、pipeline layout、sampler，以及常量/纹理/采样器三组 descriptor pool / set。
+- 还会清空当前 shader 句柄、device/backend/format/sample 描述缓存与已绑定 source color view。
+
+## 当前实现边界
+
+- `Shutdown()` 不会重置 [FinalColorSettings](GetSettings.md) 或 `shaderPath`；后续再次 [Execute](Execute.md) 时仍会基于现有配置重建资源。
+- 析构函数也会调用它，因此可以把它视为幂等的显式清理入口。
+
+## 相关文档
+
+- [BuiltinFinalColorPass](BuiltinFinalColorPass.md)
+- [Destructor](Destructor.md)
+- [Execute](Execute.md)
+- [OwnedDescriptorSet](OwnedDescriptorSet.md)