docs(rendering): realign api docs to module structure

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

@@ -6,29 +6,89 @@
 
 **头文件**: `XCEngine/Rendering/Extraction/RenderSceneUtility.h`
 
-**描述**: 提供把相机和场景对象翻译成 `RenderCameraData` 与 `VisibleRenderItem` 的基础 helper。
+**描述**: 为 scene extraction 提供相机数据构建、mesh/volume 展开、稳定排序和光照辅助查询等基础 helper。
 
-## 当前公开函数
+## 概览
+
+`RenderSceneUtility.h` 是 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) 的下层规则库。
+它把最容易散落在 extractor 里的局部逻辑单独收口，当前主要覆盖四类工作：
+
+1. 构建 [RenderCameraData](../../FrameData/RenderCameraData/RenderCameraData.md)
+2. 展开 `VisibleRenderItem`
+3. 展开 `VisibleVolumeItem`
+4. 提供可见排序与光照辅助函数
+
+## 公开函数
+
+### 相机与可见项构建
 
 - `BuildRenderCameraData(...)`
 - `AppendRenderItemsForGameObject(...)`
-- `CompareVisibleRenderItemsStable(...)`
+- `AppendVisibleVolumesForGameObject(...)`
 - `CollectRenderItemsForEntityIds(...)`
+
+### 稳定排序
+
+- `CompareVisibleRenderItemsStable(...)`
+- `CompareVisibleVolumesStable(...)`
+
+### 光照辅助
+
 - `IsUsableLight(...)`
 - `IsLightVisibleForCullingMask(...)`
 - `BuildRenderLightDirection(...)`
 - `FindMainDirectionalLight(...)`
 
-## 当前语义
+## 当前实现语义
 
-- `BuildRenderCameraData(...)` 负责构建矩阵、姿态、viewport 尺寸与默认 clear 参数。
-- `AppendRenderItemsForGameObject(...)` 会把 `GameObject` 展开成一个或多个 `VisibleRenderItem`。
-- `CollectRenderItemsForEntityIds(...)` 用于按实体 ID 收集渲染项，常见于 editor 工具链。
+### `BuildRenderCameraData()`
+
+- 读取相机的世界位置、朝向、clear color、投影参数与 clip plane
+- 根据 perspective / orthographic 模式构建投影矩阵
+- 写入 `view`、`projection`、`viewProjection`
+- 同时补 `worldRight`、`worldUp`、`worldForward` 与 `aspectRatio`
+
+它不会解析 `clearFlags`；那部分由 planning 层写进 `CameraRenderRequest`，再在执行层回写。
+
+### `AppendRenderItemsForGameObject()`
+
+- 仅接受激活且启用的 mesh 物体
+- 按 mesh section 展开成多个 `VisibleRenderItem`
+- 为每项补 `material`、`renderQueue`、`cameraDistanceSq`、`localToWorld`
+- 同时把运行时对象 ID 转成渲染侧 `renderObjectId`
+
+### `AppendVisibleVolumesForGameObject()`
+
+- 仅接受激活且启用的 `VolumeRendererComponent`
+- 要求 `VolumeField` 有效且材质存在
+- 生成 `VisibleVolumeItem`，写入 `volumeField`、`material`、`renderQueue`、`cameraDistanceSq` 和 `localToWorld`
+
+### 排序与光照
+
+- `CompareVisibleRenderItemsStable(...)` 与 `CompareVisibleVolumesStable(...)` 都按 `renderQueue` 和相机距离做稳定比较
+- `FindMainDirectionalLight(...)` 负责找出当前 culling mask 下的主方向光
+- `BuildRenderLightDirection(...)` 统一把组件朝向转换为渲染侧光照方向
+
+## 设计说明
+
+把这些 helper 独立出来是一个典型的商业引擎做法：
+不是为了“拆文件而拆文件”，而是为了让 extractor 保持在“组织一帧数据”的层级，而不是同时背负矩阵约定、排序约定和组件过滤约定。
+
+这样做的收益是：
+
+- 提取逻辑更容易单元测试
+- `RenderSceneExtractor` 的职责边界更清晰
+- 新增体积、额外光源、材质排序规则时，不必把所有细节塞回一个大类
+
+## 当前实现边界
+
+- 仍然直接操作场景组件，还不是完全解耦的 render proxy 阶段。
+- `cameraDistanceSq` 目前按对象变换位置估算，不使用更精细的 bounds 中心。
+- 没有 LOD、culling 或 batching。
 
 ## 相关文档
 
-- [Extraction](../Extraction.md)
 - [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
 - [RenderCameraData](../../FrameData/RenderCameraData/RenderCameraData.md)
 - [VisibleRenderItem](../../FrameData/VisibleRenderItem/VisibleRenderItem.md)
-
+- [VisibleVolumeItem](../../FrameData/VisibleVolumeItem/VisibleVolumeItem.md)