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

# RenderSceneExtractor

**命名空间**: `XCEngine::Rendering`

**类型**: `class + related structs`

**头文件**: `XCEngine/Rendering/RenderSceneExtractor.h`

**描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、主方向光提取和 `visibleItems` 收集。

## 概览

`RenderSceneExtractor` 处在“场景对象组织”和“单相机渲染提交”之间。它不负责真正发 draw call，而是把场景转换成一份更适合渲染阶段消费的数据：

- `camera`
- `cameraData`
- `lighting`
- `visibleItems`

当前 `CameraRenderer` 会在执行单个 `CameraRenderRequest` 时调用它。

## `RenderSceneData`

| 字段 | 类型 | 说明 |
|------|------|------|
| `camera` | `Components::CameraComponent*` | 当前提取使用的相机。 |
| `cameraData` | `RenderCameraData` | 由相机和 viewport 推导出的渲染相机数据。 |
| `lighting` | `RenderLightingData` | 当前主方向光快照。 |
| `visibleItems` | `std::vector<VisibleRenderItem>` | 当前帧提取出的可绘制项列表。 |

`RenderSceneData::HasCamera()` 当前只是检查 `camera != nullptr`。

## 当前提取规则

### 相机

- `SelectCamera()` 优先使用可用的 `overrideCamera`。
- 否则在场景里选出所有可用相机中的“最高深度 primary camera”。
- 如果没有 primary，则回退到第一个可用相机。

### 光照

- 只提取可用的方向光。
- 当前只保留一盏“主方向光”。
- 选择规则是“强度最高的可用方向光”。

### 可绘制项

- 只递归遍历 `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) | 自动选择相机并提取 `RenderSceneData`。 |
| [ExtractForCamera](ExtractForCamera.md) | 使用显式给定相机提取 `RenderSceneData`。 |
| [SelectCamera](SelectCamera.md) | 按当前规则选择可用相机。 |

## 相关文档

- [Rendering](../Rendering.md)
- [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md)
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
- [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md)