docs(rendering): tighten planning and viewport docs

2026-04-10 17:14:27 +08:00
parent f917040e9a
commit f401a54806
14 changed files with 229 additions and 37 deletions
--- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md
@@ -86,5 +86,5 @@ ApplySceneViewportRenderRequestSetup(
 - [HasOverlayPasses](HasOverlayPasses.md)
 - [ApplySceneViewportRenderRequestSetup](../ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md)
 - [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md)
- [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)
+- [CameraRenderRequest](../../../Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md)
 - [Scene View Render Plan And Failure Flow](../../../../_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md)
--- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md
+++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md
@@ -12,7 +12,7 @@

 `SceneViewportRenderPlan.h` 处在 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 的 Scene View 主路径中段。

-它不负责决定“场景里有哪些相机需要渲染”，那是运行时 [SceneRenderer](../../../Rendering/SceneRenderer/SceneRenderer.md) 与 [SceneRenderRequestPlanner](../../../Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 的职责。
+它不负责决定“场景里有哪些相机需要渲染”，那是运行时 [SceneRenderer](../../../Rendering/Execution/SceneRenderer/SceneRenderer.md) 与 [SceneRenderRequestPlanner](../../../Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 的职责。

 它负责的是 Scene View 这一层独有的编辑器附加项：

--- a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md
+++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md
@@ -17,7 +17,7 @@ void ApplySceneViewportRenderRequestSetup(

 ## 作用

-把 Scene View 这一帧最基础的附加渲染设置写回 [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)。
+把 Scene View 这一帧最基础的附加渲染设置写回 [CameraRenderRequest](../../../Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md)。

 它负责的是“最低层 request 装配”：

@@ -80,5 +80,5 @@ void ApplySceneViewportRenderRequestSetup(
 - [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
 - [ApplySceneViewportRenderPlan](../SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md)
 - [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
- [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)
- [ObjectIdRenderRequest](../../../Rendering/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md)
+- [CameraRenderRequest](../../../Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md)
+- [ObjectIdRenderRequest](../../../Rendering/Planning/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md)
--- a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md
+++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md
@@ -183,4 +183,4 @@ Scene View 在构建 render plan 时，可能已经得到了更精确但非致
 - [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
 - [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
 - [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
- [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)
+- [CameraRenderRequest](../../../Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md)
--- a/docs/api/XCEngine/Rendering/Builtin/Builtin.md
+++ b/docs/api/XCEngine/Rendering/Builtin/Builtin.md
@@ -21,11 +21,14 @@
 ## 当前公开入口

 - [BuiltinPassContract](BuiltinPassContract/BuiltinPassContract.md)
- [BuiltinMaterialPass](../RenderMaterialUtility/BuiltinMaterialPass.md)
- [BuiltinPassResourceSemantic](../RenderMaterialUtility/BuiltinPassResourceSemantic.md)
- [BuiltinPassResourceBindingPlan](../RenderMaterialUtility/BuiltinPassResourceBindingPlan.md)
- [NormalizeBuiltinPassMetadataValue](../RenderMaterialUtility/NormalizeBuiltinPassMetadataValue.md)
- [TryBuildBuiltinPassResourceBindingPlan](../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md)
+- [BuiltinPassTypes](BuiltinPassTypes/BuiltinPassTypes.md)
+- [BuiltinPassMetadataUtils](BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md)
+- [BuiltinPassLayoutUtils](BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md)
+
+兼容说明：
+
+- [RenderMaterialUtility](../RenderMaterialUtility/RenderMaterialUtility.md)
+  保留旧专题入口，用来解释原先归在 `RenderMaterialUtility` 名下的契约页现在分别落在哪些真实头文件里。

 ## 相关文档

--- a/docs/api/XCEngine/Rendering/Materials/Materials.md
+++ b/docs/api/XCEngine/Rendering/Materials/Materials.md
@@ -17,6 +17,7 @@
 - [RenderMaterialResolve](RenderMaterialResolve/RenderMaterialResolve.md)
 - [RenderMaterialStateUtils](RenderMaterialStateUtils/RenderMaterialStateUtils.md)
 - [RenderMaterialUtility](../RenderMaterialUtility/RenderMaterialUtility.md)
+  兼容主题页，用来承接旧入口并指向新的 `Builtin/*` + `Materials/*` 分层。

 ## 当前职责

--- a/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/BuildRequests.md
+++ b/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/BuildRequests.md
@@ -19,11 +19,22 @@ std::vector<CameraRenderRequest> BuildRequests(

 这两个计数会传给 `ResolveClearFlags()`，用于推导 `Auto` clear mode 的最终清屏行为。

+在基础 request 构建成功后，当前实现还会尝试补方向光阴影规划：
+
+- 先判断这台相机当前是否应该进入自动方向光阴影路径。
+- 再按相机 `cullingMask` 查找主方向光，并要求该光源开启投影阴影。
+- 满足条件时，通过内部 `DirectionalShadowPlanning` helper 构建 `request.directionalShadow`。
+- 如果 plan 有效，还会同步写入：
+  - `request.shadowCaster.clearFlags = RenderClearFlags::Depth`
+  - `request.shadowCaster.hasCameraDataOverride = true`
+  - `request.shadowCaster.cameraDataOverride = request.directionalShadow.cameraData`
+
 ## 当前过滤规则

 - 如果某台相机最终生成的 request render area 宽高为 `0`，该请求会被跳过。
 - 只有真正成功加入结果数组的 base camera，才会推进 `renderedBaseCameraCount`。
 - 方法不会抛出失败原因；调用方只会拿到最终保留下来的请求数组。
+- 如果方向光阴影 plan 构建失败，主 request 仍然会保留，只是 `directionalShadow` 维持无效状态。

 ## 返回值

@@ -34,5 +45,6 @@ std::vector<CameraRenderRequest> BuildRequests(

 - [SceneRenderRequestPlanner](SceneRenderRequestPlanner.md)
 - [CollectCameras](CollectCameras.md)
+- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
 - [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
 - [SceneRenderer::BuildRenderRequests](../../Execution/SceneRenderer/BuildRenderRequests.md)
--- a/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md
+++ b/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md
@@ -20,13 +20,24 @@

 这样 Editor、离屏渲染和手工 request 注入都能复用同一套规划规则，而不用直接碰 `CameraRenderer` 内部执行链。

-## 公开方法
+## 公开类型与方法
+
+当前头文件除了 planner 本体，还公开了：
+
+- `DirectionalShadowPlanningSettings`
+  负责控制自动方向光阴影规划的 map 尺寸、focus 距离、padding 和深度范围下限。
+
+公开方法包括：

 | 方法 | 说明 |
 |------|------|
+| `SetDirectionalShadowPlanningSettings(...)` | 写入一份会先经过 sanitize 的阴影规划参数。 |
+| `GetDirectionalShadowPlanningSettings()` | 返回当前生效的阴影规划参数。 |
 | [CollectCameras](CollectCameras.md) | 收集本次应参与渲染的相机列表。 |
 | [BuildRequests](BuildRequests.md) | 把相机列表展开成可执行的 `CameraRenderRequest` 数组。 |

+## 公开方法
+
 ## 当前规划规则

 ### `CollectCameras()`
@@ -48,6 +59,13 @@
 这两个计数会影响自动 clear flag 的推导。
 如果某个相机最终解析出的 render area 宽高为 `0`，该请求会被直接丢弃，而且不会错误地推进 base camera 计数。

+如果当前相机满足方向光阴影规划条件，planner 还会：
+
+- 查找当前 `cullingMask` 下可投影阴影的主方向光
+- 用 `DirectionalShadowPlanningSettings` 生成 `request.directionalShadow`
+- 在 plan 有效时，把 `shadowCaster.clearFlags` 固定为 `RenderClearFlags::Depth`
+- 同时把 `shadowCaster.hasCameraDataOverride` 和 `cameraDataOverride` 写成阴影相机数据
+
 ## 设计取舍

 当前 planner 故意保持“只做一件事”：
@@ -72,6 +90,7 @@
 - 它只规划相机请求，不处理 `objectId` 或各类 `RenderPassSequence` 的具体填充；那部分通常由更上层调用方补充。
 - 当前没有 camera stacking 的更复杂依赖分析，只有 base / overlay 与 depth 的线性排序。
 - `BuildRequests()` 只返回成功构建的请求，不单独报告被过滤掉的相机原因。
+- 自动方向光阴影规划目前只产出单张 shadow map 方案，不在这里处理级联阴影或多光源阴影编排。

 ## 相关文档

--- a/docs/api/XCEngine/Rendering/Rendering.md
+++ b/docs/api/XCEngine/Rendering/Rendering.md
@@ -45,8 +45,9 @@
 4. 执行 `preScenePasses`。
 5. 如有需要，执行 shadow-caster / depth-only scene pass。
 6. `RenderPipeline` 绘制主颜色目标。
-7. 如有需要，执行 object-id pass。
-8. 执行 `postScenePasses` 和 `overlayPasses`。
+7. 如有需要，执行 `postProcess` 和 `finalOutput` fullscreen 阶段。
+8. 如有需要，执行 object-id pass。
+9. 执行 `postScenePasses` 和 `overlayPasses`。

 Scene View 里的无限网格、选中轮廓和编辑器 overlay，当前都不是 `CameraRenderer` 内部动态规划出来的，而是先在 Editor 层组装成 request plan，再通过 `postScenePasses` / `overlayPasses` 接入这条主链。

@@ -61,16 +62,18 @@ Scene View 里的无限网格、选中轮廓和编辑器 overlay，当前都不

 ## 材质与 shader 语义如何进入主链路

-[RenderMaterialUtility](RenderMaterialUtility/RenderMaterialUtility.md) 当前负责把材质里的：
+这部分职责当前已经不再由单一的 `RenderMaterialUtility.h` 承担，而是拆成两层：

- `shaderPass`
- `LightMode`
- `renderQueue`
- `renderState`
+- [RenderMaterialResolve](Materials/RenderMaterialResolve/RenderMaterialResolve.md)
+  负责材质、shader pass、render queue、skybox 与常量 payload 解析。
+- [RenderMaterialStateUtils](Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md)
+  负责把材质 render-state 映射到 RHI 状态描述。
+- [Builtin](Builtin/Builtin.md)
+  负责 builtin pass 名称、资源语义、binding plan 与 set-layout 规则。

-翻译成渲染链路可消费的规则。
+[RenderMaterialUtility](RenderMaterialUtility/RenderMaterialUtility.md) 现在只保留为兼容主题页，用来给旧文档入口做导航。

-在默认 builtin forward 路径里，shader pass 的 `resources` 声明还会进一步参与 `PassResourceLayout` 构建，因为 [BuiltinForwardPipeline](Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 已经开始按资源契约生成 descriptor set layout。
+在默认 builtin forward 路径里，shader pass 的 `resources` 声明会先进入 `Builtin` 层构建 binding plan 和 descriptor-set layout，再由 [BuiltinForwardPipeline](Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 消费这些契约。

 ## 当前基础设施分层

--- a/docs/api/_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md
+++ b/docs/api/_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md
@@ -164,8 +164,8 @@
 ## 相关 API

 - [Rendering](../../XCEngine/Rendering/Rendering.md)
- [SceneRenderer](../../XCEngine/Rendering/SceneRenderer/SceneRenderer.md)
- [SceneRenderRequestPlanner](../../XCEngine/Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
- [SceneRenderRequestUtils](../../XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md)
- [CameraRenderRequest](../../XCEngine/Rendering/CameraRenderRequest/CameraRenderRequest.md)
- [CameraRenderer](../../XCEngine/Rendering/CameraRenderer/CameraRenderer.md)
+- [SceneRenderer](../../XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md)
+- [SceneRenderRequestPlanner](../../XCEngine/Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
+- [SceneRenderRequestUtils](../../XCEngine/Rendering/Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md)
+- [CameraRenderRequest](../../XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md)
+- [CameraRenderer](../../XCEngine/Rendering/Execution/CameraRenderer/CameraRenderer.md)
--- a/docs/api/_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md
+++ b/docs/api/_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md
@@ -136,10 +136,10 @@ Scene View 的网格、选中描边和 editor overlay，当前就是先在 Edito
 ## 相关 API

 - [Rendering](../../XCEngine/Rendering/Rendering.md)
- [RenderSceneExtractor](../../XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md)
+- [RenderSceneExtractor](../../XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md)
 - [RenderSurface](../../XCEngine/Rendering/RenderSurface/RenderSurface.md)
 - [RenderPass](../../XCEngine/Rendering/RenderPass/RenderPass.md)
- [SceneRenderer](../../XCEngine/Rendering/SceneRenderer/SceneRenderer.md)
+- [SceneRenderer](../../XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md)
 - [BuiltinForwardPipeline](../../XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
 - [BuiltinForwardPipelineAsset](../../XCEngine/Rendering/Pipelines/BuiltinForwardPipelineAsset/BuiltinForwardPipelineAsset.md)
 - [MeshFilterComponent](../../XCEngine/Components/MeshFilterComponent/MeshFilterComponent.md)
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态

-**生成时间**: `2026-04-10 17:09:30`
+**生成时间**: `2026-04-10 17:12:12`

 **来源**: `docs/api/_tools/audit_api_docs.py`

--- a/docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md
+++ b/docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md
@@ -22,16 +22,16 @@

 | ID | 范围 | 目标改动 | 主要路径 | 风险 | 状态 | 领取人 |
 |----|------|----------|----------|------|------|--------|
-| `R1` | Rendering / 重复目录归位 | 把旧顶层 `CameraRenderer`、`SceneRenderer`、`CameraRenderRequest`、`SceneRenderRequestPlanner`、`SceneRenderRequestUtils`、`RenderCameraData`、`RenderResourceCache`、`RenderSceneExtractor`、`RenderSceneUtility` 合并到真实子模块位置 | `docs/api/XCEngine/Rendering/**` | `medium` | `pending` | |
+| `R1` | Rendering / 重复目录归位 | 把旧顶层 `CameraRenderer`、`SceneRenderer`、`CameraRenderRequest`、`SceneRenderRequestPlanner`、`SceneRenderRequestUtils`、`RenderCameraData`、`RenderResourceCache`、`RenderSceneExtractor`、`RenderSceneUtility` 合并到真实子模块位置 | `docs/api/XCEngine/Rendering/**` | `medium` | `completed` | 当前会话 |
 | `R2` | Rendering / 旧命名残留审计 | 处理 `ObjectIdEncoding`、`ObjectIdPass`、`RenderMaterialUtility`、`VisibleRenderObject`，判定迁移到哪里或删除 | `docs/api/XCEngine/Rendering/**` | `medium` | `pending` | |
 | `E1` | Editor / 历史失效页清理 | 移除 `XCUIDemoPanel` canonical 页面，修正 `panels.md`、`ImGuiTransitionBackend.md` 等反向链接 | `docs/api/XCEngine/Editor/panels/**` | `low` | `completed` | 当前会话 |
-| `V1` | Resources / Volume | 建立 `Volume.md`、`VolumeField.md`、`VolumeFieldLoader.md`，同步 `Resources.md` | `docs/api/XCEngine/Resources/Volume/**` | `low` | `pending` | |
-| `V2` | Components / Volume | 建立 `VolumeRendererComponent.md`，同步 `Components.md` | `docs/api/XCEngine/Components/VolumeRendererComponent/**` | `low` | `pending` | |
-| `V3` | Rendering / Volume FrameData | 建立 `VisibleVolumeItem.md`，同步 `FrameData.md` | `docs/api/XCEngine/Rendering/FrameData/**` | `low` | `pending` | |
-| `V4` | Rendering / Volume & Selection Passes | 建立 `BuiltinSelectionMaskPass.md`、`BuiltinSelectionOutlinePass.md`、`BuiltinVolumetricPass.md`，同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `pending` | |
-| `U1` | UI / Widgets Helpers | 建立 `UIDragDropInteraction.md`、`UIScrollModel.md`，同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `high-risk` | `pending` | |
-| `ED1` | Editor / ComponentEditors | 建立 `VolumeRendererComponentEditor.md`，同步 `ComponentEditors.md` | `docs/api/XCEngine/Editor/ComponentEditors/**` | `low` | `pending` | |
-| `ED2` | Editor / panels Material Authoring | 建立 `MaterialInspectorMaterialState.md`、`MaterialInspectorMaterialStateIO.md`，同步 `panels.md` | `docs/api/XCEngine/Editor/panels/**` | `low` | `pending` | |
+| `V1` | Resources / Volume | 建立 `Volume.md`、`VolumeField.md`、`VolumeFieldLoader.md`，同步 `Resources.md` | `docs/api/XCEngine/Resources/Volume/**` | `low` | `completed` | 当前会话 |
+| `V2` | Components / Volume | 建立 `VolumeRendererComponent.md`，同步 `Components.md` | `docs/api/XCEngine/Components/VolumeRendererComponent/**` | `low` | `completed` | 当前会话 |
+| `V3` | Rendering / Volume FrameData | 建立 `VisibleVolumeItem.md`，同步 `FrameData.md` | `docs/api/XCEngine/Rendering/FrameData/**` | `low` | `completed` | 当前会话 |
+| `V4` | Rendering / Volume & Selection Passes | 建立 `BuiltinSelectionMaskPass.md`、`BuiltinSelectionOutlinePass.md`、`BuiltinVolumetricPass.md`，同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `completed` | 当前会话 |
+| `U1` | UI / Widgets Helpers | 建立 `UIDragDropInteraction.md`、`UIScrollModel.md`，同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `high-risk` | `completed` | 当前会话 |
+| `ED1` | Editor / ComponentEditors | 建立 `VolumeRendererComponentEditor.md`，同步 `ComponentEditors.md` | `docs/api/XCEngine/Editor/ComponentEditors/**` | `low` | `completed` | 当前会话 |
+| `ED2` | Editor / panels Material Authoring | 建立 `MaterialInspectorMaterialState.md`、`MaterialInspectorMaterialStateIO.md`，同步 `panels.md` | `docs/api/XCEngine/Editor/panels/**` | `low` | `completed` | 当前会话 |
 | `RR1` | RHI 内容回归 | 根据当前真实头文件更新 `RHI*`、`D3D12`、`OpenGL`、`Vulkan` 文档内容与结构 | `docs/api/XCEngine/RHI/**` | `high-risk` | `pending` | |
 | `RR2` | Rendering / Passes 内容回归 | 根据当前修改中的 builtin pass 头文件更新文档内容与链接 | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `pending` | |
 | `RR3` | Rendering / Materials 内容回归 | 把 `RenderMaterialResolve` 相关文档与当前头文件重新对齐 | `docs/api/XCEngine/Rendering/Materials/**` | `high-risk` | `pending` | |
--- a/docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md
+++ b/docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md
@@ -0,0 +1,154 @@
+# API 文档目录结构重大重构并行任务板（2026-04-09）
+
+## 背景
+
+项目近期经过了大规模重构，`docs/api/XCEngine` 当前 canonical 树已经和实际源码出现新的结构偏差。
+本任务板用于给多会话 / 多代理并行协作时直接认领任务，避免重复劳动和目录冲突。
+
+本轮结论来自两类事实源：
+
+- 源码目录对照：
+  - `engine/include/XCEngine`
+  - `editor/src`
+  - `new_editor/include/XCEditor`
+- 文档审计：
+  - `python -B docs/api/_tools/audit_api_docs.py`
+  - 最新生成时间：`2026-04-10 17:07:09`
+
+## 当前关键问题
+
+### 当前审计状态
+
+- 当前 `docs/api/XCEngine/**` + `docs/api/XCEditor/**` + `editor/src/**` 范围内审计已经全绿：
+  - `Invalid header refs = 0`
+  - `Invalid source refs = 0`
+  - `Broken .md links = 0`
+  - `Missing directory index pages = 0`
+- 本轮补页已经覆盖：
+  - `VolumeRendererComponent`
+  - `VisibleVolumeItem`
+  - `BuiltinSelectionMaskPass`
+  - `BuiltinSelectionOutlinePass`
+  - `BuiltinVolumetricPass`
+  - `Volume`
+  - `VolumeField`
+  - `VolumeFieldLoader`
+  - `UIDragDropInteraction`
+  - `UIScrollModel`
+  - `VolumeRendererComponentEditor`
+  - `MaterialInspectorMaterialState`
+  - `MaterialInspectorMaterialStateIO`
+- 新增 canonical 根树与资源子模块：
+  - `docs/api/XCEditor/**`
+  - `XCEngine/Resources/Model/**`
+  - `XCEngine/Resources/GaussianSplat/**`
+- `XCUIDemoPanel` 已从 canonical API 树中移除；活跃 overview 只保留当前真实调用点和历史说明。
+
+### 剩余结构问题
+
+- `AGENT.md`、`docs/api-skill.md` 与 `docs/used/**` 的 active/archive 入口口径仍需同步到新根树与新任务板。
+- `RHI`、`Rendering/Passes`、`Rendering/Materials` 等高风险内容回归任务仍未收口。
+- 历史空目录与重复目录的进一步清理仍待继续验证。
+
+### 当前发现的可疑空目录
+
+以下目录当前为空，优先视为历史迁移残留；删除前需要先 `rg` 检查是否仍有链接引用：
+
+- `docs/api/XCEngine/Core/Core`
+- `docs/api/XCEngine/Core/Containers/Containers`
+- `docs/api/XCEngine/Debug/Debug`
+- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayRenderer`
+- `docs/api/XCEngine/Rendering/CameraRenderRequest/BuiltinPostProcessRequest`
+- `docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassPlan`
+- `docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassSequenceBuilder`
+- `docs/api/XCEngine/Resources/Shader/ShaderRenderState`
+
+说明：
+
+- `docs/api/XCEngine/Components/VolumeRendererComponent`
+- `docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem`
+- `docs/api/XCEngine/Rendering/Passes/BuiltinSelectionMaskPass`
+- `docs/api/XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass`
+- `docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass`
+- `docs/api/XCEngine/Resources/Volume/VolumeField`
+- `docs/api/XCEngine/Resources/Volume/VolumeFieldLoader`
+
+这些空目录是本轮结构补齐时创建的目标目录，不属于历史残留，需要补页面而不是删除。
+
+## 并行认领规则
+
+- 一个任务块只允许一个会话认领。
+- 每个任务块必须同时处理：
+  - 主页面
+  - 所在模块索引页
+  - 相关交叉链接
+- 删除任何目录或页面前，先执行：
+  - `rg -n "<名称>" docs/api/XCEngine docs/api/_guides`
+- 每个任务块完成后都要执行：
+  - `python -B docs/api/_tools/audit_api_docs.py`
+
+## 任务块
+
+| ID | 范围 | 目标改动 | 主要路径 | 状态 | 认领人 |
+|----|------|----------|----------|------|--------|
+| `S1` | Resources / Volume | 新建 `Volume.md`、`VolumeField.md`、`VolumeFieldLoader.md`，并更新 `Resources.md` | `docs/api/XCEngine/Resources/Volume/**` | `completed` | 当前会话 |
+| `S2` | Components / Volume | 新建 `VolumeRendererComponent.md`，并更新 `Components.md` | `docs/api/XCEngine/Components/VolumeRendererComponent/**` | `completed` | 当前会话 |
+| `S3` | Rendering / Volume FrameData | 新建 `VisibleVolumeItem.md`，并更新 `FrameData.md` | `docs/api/XCEngine/Rendering/FrameData/**` | `completed` | 当前会话 |
+| `S4` | Rendering / Volume & Selection Passes | 新建 `BuiltinSelectionMaskPass.md`、`BuiltinSelectionOutlinePass.md`、`BuiltinVolumetricPass.md`，并更新 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `completed` | 当前会话 |
+| `S5` | UI / Widgets Helpers | 新建 `UIDragDropInteraction.md`、`UIScrollModel.md`，并更新 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `completed` | 当前会话 |
+| `S6` | Editor / ComponentEditors | 新建 `VolumeRendererComponentEditor.md`，并更新 `ComponentEditors.md` | `docs/api/XCEngine/Editor/ComponentEditors/**` | `completed` | 当前会话 |
+| `S7` | Editor / panels Material Authoring | 新建 `MaterialInspectorMaterialState.md`、`MaterialInspectorMaterialStateIO.md`，并更新 `panels.md` | `docs/api/XCEngine/Editor/panels/**` | `completed` | 当前会话 |
+| `S8` | Editor 旧页清理 | 删除 `XCUIDemoPanel` 旧页与空目录，修正所有反向链接 | `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/**` | `completed` | 当前会话 |
+| `S9` | Canonical 空目录清理 | 清理历史空目录并验证无死链 | 见“可疑空目录”列表 | `pending` | |
+| `S10` | 全量回归 | 运行审计，更新状态，补最后的索引 / 链接 / 空目录问题 | `docs/api/_meta/rebuild-status.md` | `completed` | 当前会话 |
+
+## 各任务块的最低验收标准
+
+### `S1` - `S7`
+
+- 目录结构与源码平行。
+- 每个类型都是“一个文件夹 + 一个同名主页面”。
+- 页面必须基于当前源码和测试写内容，不能凭旧文档照搬。
+- 必须同步更新所属模块总览页中的目录列表 / 页面列表。
+
+### `S8`
+
+- `XCUIDemoPanel` 页面与目录从 canonical 树中移除。
+- 所有指向它的链接都替换为当前真实调用点描述，或者直接删除。
+- 审计中的 `Invalid source refs` 归零。
+
+### `S9`
+
+- 只清理已经确认无源码对应、且无链接引用的目录。
+- 不能误删本轮待补页面目录。
+
+### `S10`
+
+- `Invalid header refs = 0`
+- `Invalid source refs = 0`
+- `Broken .md links = 0`
+- `Missing directory index pages = 0`
+- 缺页计数进一步下降，最好清零
+
+## 推荐执行顺序
+
+1. `S8`
+2. `S1`
+3. `S2`
+4. `S3`
+5. `S4`
+6. `S5`
+7. `S6`
+8. `S7`
+9. `S9`
+10. `S10`
+
+## 备注
+
+- 当前阶段已经从“补缺页”转为“入口口径同步 + 高风险内容回归”。
+- 下一轮优先收口：
+  - `AGENT.md`
+  - `docs/api-skill.md`
+  - `docs/used/API文档实时同步任务池_2026-04-03*.md`
+  - `docs/api/XCEngine/RHI/**`
+  - `docs/api/XCEngine/Rendering/**`