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

RenderSceneUtility

命名空间: XCEngine::Rendering

类型: utility header

头文件: XCEngine/Rendering/RenderSceneUtility.h

描述: 提供把相机和场景对象翻译成 RenderCameraData 与 VisibleRenderItem 的基础 helper。

概览

RenderSceneUtility.h 位于 RenderSceneExtractor 的下层，负责两类最基础的转换：

1. 把 CameraComponent 的参数整理成渲染侧消费的 RenderCameraData
2. 把 GameObject + MeshFilter + MeshRenderer 组合展开成可绘制的 VisibleRenderItem

公开函数

BuildRenderCameraData()

根据相机组件和目标视口大小构建 RenderCameraData：

• 复制 viewportWidth / viewportHeight
• 读取相机世界位置和 clearColor
• 根据投影模式构建 perspective 或 orthographic 投影矩阵
• 把 view、projection、viewProjection 以转置后的矩阵形式写入结果

当前还要注意一个边界：

• 这里不会根据 CameraComponent::GetClearMode() 推导 clearFlags
• 返回结果里的 clearFlags 仍保留 RenderCameraData 的默认值 RenderClearFlags::All
• 真正的 per-request clear 规则是在 SceneRenderRequestUtils 先解析成 CameraRenderRequest::clearFlags，再由 CameraRenderer 写回 sceneData.cameraData.clearFlags

AppendRenderItemsForGameObject()

把单个 GameObject 追加成一个或多个 VisibleRenderItem。 当前筛选规则是：

• 非激活对象直接跳过
• 缺少 MeshFilterComponent 或 MeshRendererComponent 直接跳过
• 任一组件被禁用时跳过
• mesh == nullptr 或 mesh->IsValid() == false 时跳过

若 mesh 存在 section，则每个 section 生成一个 VisibleRenderItem；否则退化成单个无 section 的 item。

CollectRenderItemsForEntityIds()

按给定 entityIds 收集可绘制对象，当前会：

• 跳过 0
• 去重重复实体 ID
• 忽略找不到的对象
• 复用 AppendRenderItemsForGameObject() 展开 section

真实使用位置

• engine/src/Rendering/RenderSceneExtractor.cpp 用它构建相机数据和可见物体列表。
• tests/Rendering/unit/test_render_scene_utility.cpp 覆盖了相机矩阵约定、实体过滤和 section 展开。

当前实现边界

• 当前没有做 frustum culling、LOD、遮挡剔除或 batching。
• cameraDistanceSq 只按对象变换平移量估算，不考虑 bounds 中心或 section 级差异。
• 这些函数直接操作场景对象和组件引用，还不是完全解耦的 render proxy 阶段。

相关文档

• Rendering
• RenderCameraData
• RenderSceneExtractor
• VisibleRenderObject
• RenderMaterialUtility