docs(rendering): realign api docs to module structure

docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md

@@ -6,36 +6,87 @@
 
 **头文件**: `XCEngine/Rendering/Extraction/RenderSceneExtractor.h`
 
-**描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、环境与光照提取，以及网格 `visibleItems` 和体对象 `visibleVolumes` 收集。
+**描述**: 把场景对象树压平成执行层可直接消费的 `RenderSceneData`，负责相机选择、可见渲染项/体积项提取和光照快照构建。
 
 ## 概览
 
-`RenderSceneExtractor` 处在 `Scene` 与 `CameraRenderer` 之间。
+`RenderSceneExtractor` 是运行时场景语义和渲染提交语义之间的桥。
+它不负责发 draw call，而是把 `Scene` 转换成一份更稳定的帧数据快照，供 [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) 和各类 builtin pass 消费。
 
-它当前公开三条入口：
+当前导出的 `RenderSceneData` 重点包含：
 
-- `Extract(...)`
-- `ExtractForCamera(...)`
-- `SelectCamera(...)`
-
-## 当前提取内容
-
-- 当前相机
-- [RenderCameraData](../../FrameData/RenderCameraData/RenderCameraData.md)
-- [RenderEnvironmentData](../../FrameData/RenderEnvironmentData/RenderEnvironmentData.md)
-- `RenderLightingData`
+- `camera`
+- `cameraData`
+- `environment`
+- `lighting`
+- `globalShaderKeywords`
 - `visibleItems`
 - `visibleVolumes`
 
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [Extract](Extract.md) | 自动选择相机并提取 `RenderSceneData`。 |
+| [ExtractForCamera](ExtractForCamera.md) | 使用显式相机提取 `RenderSceneData`。 |
+| [SelectCamera](SelectCamera.md) | 按当前规则选择可用相机。 |
+
+## 当前提取规则
+
+### 相机选择
+
+- `overrideCamera` 可用时优先使用它。
+- 否则优先选择场景里深度最高的 `primary` 相机。
+- 若没有 primary，相机列表里第一个可用相机会作为回退。
+
+### 可见内容
+
+提取器会从场景根对象开始递归遍历：
+
+- 先按 `IsActiveInHierarchy()` 和相机 `cullingMask` 过滤对象
+- 再调用 `RenderSceneUtility` 展开 mesh 渲染项
+- 同时调用 `AppendVisibleVolumesForGameObject(...)` 提取体积渲染项
+
+因此当前 `RenderSceneData` 已经同时覆盖：
+
+- 常规 mesh 的 `visibleItems`
+- 体积渲染的 `visibleVolumes`
+
+两类结果都会在提取结束后做稳定排序。
+
+### 光照快照
+
+`ExtractLighting(...)` 当前会：
+
+- 选出主方向光并构建 `mainDirectionalLight`
+- 基于影响度、光源类型和对象 ID 选出有限数量的 `additionalLights`
+- 保留阴影相关槽位，供后续执行层写入 `mainDirectionalShadow`
+
+这意味着 extractor 不只是“找一盏太阳光”，而是已经承担了运行时可消费的光照快照整理职责。
+
+## 设计取舍
+
+这类 extractor 设计和 Unity/Unreal 常见的 render-view 构建阶段类似，本质上是在做一件事：
+把场景图的层级语义压扁成一份更适合渲染排序、pass 复用和后续 GPU 提交的帧快照。
+
+这样做的好处很直接：
+
+- `CameraRenderer` 不必在执行阶段重新遍历整个场景树
+- builtin pipeline、object-id pass、体积 pass 可以共享同一批 frame data
+- editor 或工具链要加附加阶段时，不必重新发明一套“场景如何提取”的规则
+
 ## 当前实现边界
 
-- 当前仍没有 frustum culling、occlusion culling 或 batching。
-- 当前光照提取仍以主方向光和 additional lights 快照为主。
-- 体对象提取已经进入正式 `RenderSceneData` 主链，但更复杂的 volume-specific culling 或排序策略当前还没有单独拆层。
+- 没有 frustum culling。
+- 没有 occlusion culling。
+- 没有 batching / instancing。
+- `globalShaderKeywords` 主要仍由后续执行层补充。
 
 ## 相关文档
 
 - [Extraction](../Extraction.md)
 - [RenderSceneUtility](../RenderSceneUtility/RenderSceneUtility.md)
 - [RenderSceneData](../../FrameData/RenderSceneData/RenderSceneData.md)
+- [VisibleRenderItem](../../FrameData/VisibleRenderItem/VisibleRenderItem.md)
+- [VisibleVolumeItem](../../FrameData/VisibleVolumeItem/VisibleVolumeItem.md)
 - [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md)