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

Rendering

命名空间: XCEngine::Rendering

类型: module

描述: 当前场景渲染主链路所在模块，覆盖 request 规划、场景提取、主管线执行、shadow-caster / depth-only / object-id 输出，以及调用方注入的 pre / post / overlay pass。

概览

当前 Rendering 模块已经不再是简单的“scene -> pipeline”两段式结构，而是一条更完整的提交流程：

1. SceneRenderer 规划并排序 CameraRenderRequest。
2. CameraRenderer 执行单个 request。
3. RenderSceneExtractor 生成 RenderSceneData。
4. RenderPipelineAsset 决定当前主管线实例如何创建。
5. RenderPipeline 执行主场景绘制。
6. ObjectIdPass 和 Passes 子模块补上 shadow-caster、depth-only、object-id、grid、outline 等附加阶段。

默认主链路当前是：

• BuiltinForwardPipelineAsset
• BuiltinForwardPipeline

这套分层本身就是当前渲染架构最重要的设计点。

• SceneRenderer / SceneRenderRequestPlanner 处理“这次该画什么、顺序是什么”
• CameraRenderer 处理“单个 request 怎样被真正执行”
• RenderSceneExtractor 处理“场景语义怎样压平成渲染语义”
• RenderPipeline 处理“压平后的渲染数据怎样落到 GPU”

对商业级引擎来说，这种拆法的价值很直接：

• 相机编排规则不会和具体 pipeline 绑死
• Editor 可以在 request 层注入 object-id、outline、overlay，而不必改主管线
• 同一条主管线既能服务运行时，也能服务 Scene View、离屏目标和工具链

当前主流程

对一台相机的大致流程是：

1. SceneRenderer 生成 CameraRenderRequest。
2. CameraRenderer 校验 request 和 render-area。
3. RenderSceneExtractor 基于相机和 render-area 提取 RenderSceneData。
4. 执行 preScenePasses。
5. 如有需要，执行 shadow-caster / depth-only scene pass。
6. RenderPipeline 绘制主颜色目标。
7. 如有需要，执行 object-id pass。
8. 执行 postScenePasses 和 overlayPasses。

Scene View 里的无限网格、选中轮廓和编辑器 overlay，当前都不是 CameraRenderer 内部动态规划出来的，而是先在 Editor 层组装成 request plan，再通过 postScenePasses / overlayPasses 接入这条主链。

如果你想理解这条链路里最容易写错的部分，优先看：

• 哪些相机会进入本次提交
• base / overlay 如何排序
• CameraClearMode::Auto 为什么不是无脑清颜色
• normalized viewport 怎样和已有 RenderSurface::renderArea 叠加

这些规则目前都集中收口在 request planning 这一层，而不是散落在 CameraRenderer 或 builtin pipeline 里。

材质与 shader 语义如何进入主链路

RenderMaterialUtility 当前负责把材质里的：

• shaderPass
• LightMode
• renderQueue
• renderState

翻译成渲染链路可消费的规则。

在默认 builtin forward 路径里，shader pass 的 resources 声明还会进一步参与 PassResourceLayout 构建，因为 BuiltinForwardPipeline 已经开始按资源契约生成 descriptor set layout。

当前基础设施分层

更底层的基础协议由这些页面补齐：

• SceneRenderRequestPlanner
• SceneRenderRequestUtils
• RenderSceneUtility
• RenderPass
• ObjectIdEncoding

它们分别负责 request 规划、排序规则、scene helper、通用 pass 生命周期和 object-id 编解码约定。

当前实现边界

• 默认主路径仍然是 builtin forward，不是完整 SRP 或 render graph。
• RenderPipelineAsset 已经接入默认主链路，但当前还不是项目资源数据库里的完整 renderer asset。
• 多相机排序由 SceneRenderer 处理，CameraRenderer 只执行单个 request。
• 编辑器特有的 grid / outline / overlay 组装逻辑不在 Rendering 模块里完成，而是在 Editor 层先转成 RenderPassSequence。

头文件索引

• CameraRenderRequest - CameraRenderRequest.h
• CameraRenderer - CameraRenderer.h
• ObjectIdEncoding - ObjectIdEncoding.h
• ObjectIdPass - ObjectIdPass.h
• Passes - Passes/
• RenderCameraData - RenderCameraData.h
• RenderContext - RenderContext.h
• RenderMaterialUtility - RenderMaterialUtility.h
• RenderPass - RenderPass.h
• RenderPipeline - RenderPipeline.h
• RenderPipelineAsset - RenderPipelineAsset.h
• RenderResourceCache - RenderResourceCache.h
• RenderSceneExtractor - RenderSceneExtractor.h
• RenderSceneUtility - RenderSceneUtility.h
• RenderSurface - RenderSurface.h
• SceneRenderRequestPlanner - SceneRenderRequestPlanner.h
• SceneRenderRequestUtils - SceneRenderRequestUtils.h
• SceneRenderer - SceneRenderer.h
• VisibleRenderObject - VisibleRenderObject.h
• Pipelines - Pipelines/

相关指南

• Camera Request Planning And Clear Rules
• Scene Extraction And Builtin Forward Pipeline

相关文档

• Components
• RHI
• XCEngine
• API 索引