docs(rendering): realign api docs to module structure

docs/api/XCEngine/Rendering/Execution/CameraRenderer/CameraRenderer.md

@@ -6,51 +6,94 @@
 
 **头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h`
 
-**描述**: 单个 `CameraRenderRequest` 的执行器，负责在一次提交里串起 scene extraction、shadow/depth 预阶段、主管线、fullscreen 阶段，以及注入式 pre / post / overlay pass。
+**描述**: 单个 `CameraRenderRequest` 的执行器，负责把一份显式 request 变成稳定的逐阶段渲染流程。
 
 ## 概览
 
-`CameraRenderer` 是当前 Rendering 执行层里最核心的“单 request 执行器”。
+`CameraRenderer` 是 Execution 层里最靠近“真正发起一次相机渲染”的类。
 
-它不负责决定有哪些相机会进入本次渲染；那属于 [Planning](../../Planning/Planning.md) 和 [SceneRenderer](../SceneRenderer/SceneRenderer.md) 的职责。它负责的是另一半：
-
-- 使用 [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) 生成 `RenderSceneData`
-- 按阶段执行 `shadowCaster`、`depthOnly`、主管线、`postProcess`、`finalOutput`、`objectId`
-- 消费调用方注入的 `preScenePasses`、`postScenePasses` 与 `overlayPasses`
+它不负责决定应该渲染哪些相机，也不负责 request 排序；这些职责在 [Planning](../../Planning/Planning.md) 和 [SceneRenderer](../SceneRenderer/SceneRenderer.md)。  
+它负责的是另一半：把一份已经构造好的 `CameraRenderRequest` 按当前引擎约定的阶段顺序完整跑完。
 
 ## 当前持有对象
 
 - `m_sceneExtractor`
+  负责把 `Scene + Camera` 压成 `RenderSceneData`。
 - `m_pipelineAsset`
+  当前主管线的创建来源；为空时表示直接持有 runtime pipeline。
 - `m_pipeline`
+  真正执行主场景绘制的 [RenderPipeline](../../RenderPipeline/RenderPipeline.md)。
 - `m_objectIdPass`
+  object-id 输出阶段使用的 `RenderPass`。
 - `m_depthOnlyPass`
+  depth-only 阶段使用的 `RenderPass`。
 - `m_shadowCasterPass`
+  shadow-caster 阶段使用的 `RenderPass`。
 - `m_directionalShadowSurface`
+  当 request 只提供 `DirectionalShadowRenderPlan`、而没有显式 `shadowCaster.surface` 时，按需生成阴影贴图 surface。
 - `m_postProcessSurfaceCache`
 - `m_finalOutputSurfaceCache`
+  fullscreen 阶段多 pass 链使用的中间 surface cache。
 
 ## 当前执行顺序
 
-对一份有效 request，当前主顺序是：
+`CameraRenderer::Render(...)` 会按 `kOrderedCameraFrameStages` 依次执行：
 
-1. 校验 request 与 surface 前置条件
-2. 解析 shadow surface 与 `RenderSceneData`
-3. 执行 `preScenePasses`
-4. 执行 `shadowCaster`
-5. 执行 `depthOnly`
-6. 执行 `m_pipeline->Render(...)`
-7. 执行 `postProcess`
-8. 执行 `finalOutput`
-9. 执行 `objectId`
-10. 执行 `postScenePasses`
-11. 执行 `overlayPasses`
+1. `PreScenePasses`
+2. `ShadowCaster`
+3. `DepthOnly`
+4. `MainScene`
+5. `PostProcess`
+6. `FinalOutput`
+7. `ObjectId`
+8. `PostScenePasses`
+9. `OverlayPasses`
+
+其中：
+
+- `MainScene` 永远会尝试执行。
+- 其他阶段是否执行，由 `CameraRenderRequest::HasFrameStage(...)` 决定。
+- `ShadowCaster` 既可以消费显式 `request.shadowCaster`，也可以由 `request.directionalShadow` 推导出内部阴影 surface。
+
+## 设计要点
+
+### 为什么这里坚持“显式阶段链”
+
+这和 Unity SRP 里常见的 camera render loop 思路相似：每个阶段有稳定顺序，request 只是声明“这一帧这个阶段要不要做”。  
+这样做的好处是：
+
+- post-process、final-output 和 editor 注入 pass 都能接到同一条链上
+- 不同调用方不需要各自复制一套“主场景之后到底先做什么”的隐式约定
+- object-id、selection、scene view overlay 这类非主画面输出，不会反向污染主管线实现
+
+### 为什么 fullscreen 阶段不放到 pipeline 内部
+
+`RenderPipeline` 关注的是主场景绘制；fullscreen 链更像是 request 级组合层。  
+把它们留在 `CameraRenderer`，可以让不同 pipeline 共享一致的 post-process / final-output 接线方式。
 
 ## 当前实现边界
 
-- 它只执行单个 request，不负责 request 排序。
-- 它会消费 `DirectionalShadowRenderPlan`、`PostProcessRenderRequest` 与 `FinalOutputRenderRequest`，因此比旧版 `CameraRenderer` 更完整。
-- 它不自己规划 Editor 的 Scene View pass；那仍由 Editor 层先写回 request。
+- 这里只执行单个 request，不负责 request 排序。
+- 这里只消费 request 上已经挂好的 sequence / sub-request，不负责为 Editor 自动生成这些附加阶段。
+- `RenderPassSequence` 的生命周期由 request 拥有方管理；当前实现不会在一次 `Render()` 结束后主动销毁这些 sequence。
+
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 构造执行器，并决定主管线与 builtin pass 的初始来源。 |
+| [Destructor](Destructor.md) | 关闭当前主管线与 builtin pass。 |
+| [SetPipeline](SetPipeline.md) | 直接替换 runtime `RenderPipeline`。 |
+| [SetPipelineAsset](SetPipelineAsset.md) | 通过 `RenderPipelineAsset` 重建当前主管线。 |
+| [SetObjectIdPass](SetObjectIdPass.md) | 替换 object-id pass。 |
+| [SetDepthOnlyPass](SetDepthOnlyPass.md) | 替换 depth-only pass。 |
+| [SetShadowCasterPass](SetShadowCasterPass.md) | 替换 shadow-caster pass。 |
+| [GetPipeline](GetPipeline.md) | 返回当前主管线的非拥有指针。 |
+| [GetPipelineAsset](GetPipelineAsset.md) | 返回当前 pipeline asset 的非拥有指针。 |
+| [GetObjectIdPass](GetObjectIdPass.md) | 返回当前 object-id pass 的非拥有指针。 |
+| [GetDepthOnlyPass](GetDepthOnlyPass.md) | 返回当前 depth-only pass 的非拥有指针。 |
+| [GetShadowCasterPass](GetShadowCasterPass.md) | 返回当前 shadow-caster pass 的非拥有指针。 |
+| [Render](Render.md) | 执行一次完整的单相机 request。 |
 
 ## 相关文档
 
@@ -58,8 +101,7 @@
 - [SceneRenderer](../SceneRenderer/SceneRenderer.md)
 - [CameraRenderRequest](../../Planning/CameraRenderRequest/CameraRenderRequest.md)
 - [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md)
-- [RenderPipeline](../../RenderPipeline/RenderPipeline.md)
+- [BuiltinForwardPipeline](../../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
+- [BuiltinObjectIdPass](../../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)
 - [BuiltinDepthOnlyPass](../../Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md)
 - [BuiltinShadowCasterPass](../../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md)
-- [Camera Request Planning And Clear Rules](../../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md)
-