docs: sync scene renderer docs

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

@@ -2,66 +2,85 @@
 
 **命名空间**: `XCEngine::Rendering`
 
-**类型**: `class + struct`
+**类型**: `class + related structs`
 
 **头文件**: `XCEngine/Rendering/RenderSceneExtractor.h`
 
-**描述**: 从 `Scene` 中挑选相机并收集可渲染 mesh 对象，输出渲染层使用的 `RenderSceneData`。
+**描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、主方向光提取和 `visibleItems` 收集。
 
-## 概述
+## 概览
 
-`RenderSceneExtractor` 是当前渲染架构里最接近“scene extraction”阶段的对象。
+`RenderSceneExtractor` 处在“场景对象组织”和“单相机渲染提交”之间。它不负责真正发 draw call，而是把场景转换成一份更适合渲染阶段消费的数据：
 
-它的职责不是绘制，而是把面向 gameplay / scene graph 的对象整理成渲染层更容易消费的数据：
+- `camera`
+- `cameraData`
+- `lighting`
+- `visibleItems`
 
-- 一台要使用的相机
-- 一份拍平后的 [RenderCameraData](../RenderCameraData/RenderCameraData.md)
-- 一组 [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md)
-
-这和商业引擎里把 scene traversal、visibility building、render packet generation 放在真正 draw submission 之前的设计是一致的。
+当前 `CameraRenderer` 会在执行单个 `CameraRenderRequest` 时调用它。
 
 ## `RenderSceneData`
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `camera` | `Components::CameraComponent*` | 选中的相机。 |
-| `cameraData` | `RenderCameraData` | 渲染阶段使用的拍平相机数据。 |
-| `visibleObjects` | `std::vector<VisibleRenderObject>` | 当前提取到的可见对象列表。 |
+| `camera` | `Components::CameraComponent*` | 当前提取使用的相机。 |
+| `cameraData` | `RenderCameraData` | 由相机和 viewport 推导出的渲染相机数据。 |
+| `lighting` | `RenderLightingData` | 当前主方向光快照。 |
+| `visibleItems` | `std::vector<VisibleRenderItem>` | 当前帧提取出的可绘制项列表。 |
 
 `RenderSceneData::HasCamera()` 当前只是检查 `camera != nullptr`。
 
 ## 当前提取规则
 
-相机选择当前按以下顺序执行：
+### 相机
 
-1. 如果 `overrideCamera` 可用，直接使用它。
-2. 否则从场景里找出 `IsPrimary()` 的可用相机，取 `depth` 最大者。
-3. 如果仍没有，则退回到第一个可用相机。
+- `SelectCamera()` 优先使用可用的 `overrideCamera`。
+- 否则在场景里选出所有可用相机中的“最高深度 primary camera”。
+- 如果没有 primary，则回退到第一个可用相机。
 
-对象提取当前只要求：
+### 光照
 
-- `GameObject` 处于 `IsActiveInHierarchy()`
-- 同时有 `MeshFilterComponent` 和 `MeshRendererComponent`
-- 两个组件都启用
-- `MeshFilterComponent` 提供的 mesh 非空且 `IsValid()`
+- 只提取可用的方向光。
+- 当前只保留一盏“主方向光”。
+- 选择规则是“强度最高的可用方向光”。
 
-## 当前实现限制
+### 可绘制项
 
-- 当前没有 frustum culling。
-- 当前没有 render layer 过滤。
-- 当前没有透明/不透明分类、排序或 batching。
-- 当前不会读取 `castShadows` / `receiveShadows`。
-- 当前把“visible”理解为“满足基本组件条件且在激活层级中”，而不是严格意义上的屏幕可见。
+- 只递归遍历 `IsActiveInHierarchy()` 的对象。
+- 先按相机 `cullingMask` 过滤 `GameObject` 层。
+- 对通过过滤的对象，调用 `AppendRenderItemsForGameObject(...)` 展开成一个或多个 `VisibleRenderItem`。
+
+因此当前 `visibleItems` 不只是旧说法里的“visible object 列表”，而是已经展开过材质、section、render queue 和相机距离的渲染项数组。
+
+## 当前排序规则
+
+提取完成后，`visibleItems` 会做一次 `std::stable_sort`：
+
+1. `renderQueue` 小的排前面。
+2. 如果是透明队列，按 `cameraDistanceSq` 从远到近。
+3. 否则按 `cameraDistanceSq` 从近到远。
+4. 最后再按 `gameObject` 指针和 `sectionIndex` 打破平局。
+
+这让 opaque 与 transparent 的默认排序方向和当前 `RenderMaterialUtility` 的队列语义保持一致。
+
+## 当前限制
+
+- 没有 frustum culling。
+- 没有 occlusion culling。
+- 没有 batching 或 instancing。
+- 只提取单个主方向光，不保留多光源列表。
 
 ## 公开方法
 
 | 方法 | 说明 |
 |------|------|
-| [Extract](Extract.md) | 从场景中提取渲染数据。 |
+| [Extract](Extract.md) | 自动选择相机并提取 `RenderSceneData`。 |
+| [ExtractForCamera](ExtractForCamera.md) | 使用显式给定相机提取 `RenderSceneData`。 |
+| [SelectCamera](SelectCamera.md) | 按当前规则选择可用相机。 |
 
 ## 相关文档
 
-- [当前模块](../Rendering.md)
-- [RenderCameraData](../RenderCameraData/RenderCameraData.md)
+- [Rendering](../Rendering.md)
 - [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md)
-- [SceneRenderer](../SceneRenderer/SceneRenderer.md)
+- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
+- [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md)