5.7 KiB
5.7 KiB
RenderSurface
命名空间: XCEngine::Rendering
类型: class
头文件: XCEngine/Rendering/RenderSurface.h
描述: 描述当前渲染目标表面，包括尺寸、颜色/深度附件、自定义渲染区域、清屏覆盖、自动状态切换，以及与管线创建对齐的 sample 描述。
概述
RenderSurface 把“这一次渲染要写到哪里、写之前/写之后资源预期处于什么状态”从具体 swap chain、framebuffer 和缓存分配逻辑里抽离出来，变成 Planning、Execution、builtin pass 与 editor overlay 都能复用的统一协议对象。
当前它负责描述：
- 宽高。
- 一组颜色附件。
- 一个可选深度附件。
- 一个可选自定义 render area。
- 一个可选清屏颜色覆盖。
- 颜色附件共享的 before / after 状态。
- 深度附件共享的 before / after 状态。
- 是否由渲染路径自动执行颜色/深度附件状态切换。
- 当前 surface 的 MSAA
sampleCount/sampleQuality。
RenderSurface 自己不拥有 GPU 资源，也不验证附件尺寸、资源类型或 sample 描述是否真实匹配；它只是把这组约束交给调用方和具体渲染路径消费。
当前实现边界
- 颜色附件仍只有一组统一的
colorStateBefore/colorStateAfter，深度附件也只有一组统一的depthStateBefore/depthStateAfter；它不是逐 attachment 的精细状态表。 - 当 IsAutoTransitionEnabled 为
true时，BuiltinForwardPipeline、BuiltinDepthStylePassBase、BuiltinObjectIdPass、BuiltinInfiniteGridPass等路径都会消费这些 before / after 状态；关闭自动切换后，RenderSurface只保留契约信息，不会主动纠正真实 GPU 状态。 - SetSampleDesc 会把
sampleCount == 0规范化为单采样1, 0；只有sampleCount > 1时sampleQuality才保留调用方传入值。 SceneRenderer当前要求 fullscreen post-process / final-output 链路的主场景 surface 为单采样，因此多重采样主表面不会进入这两段 fullscreen 阶段。- 当前没有 load/store action、resolve target、mip slice、array slice 等更细粒度的 surface 配置。
公开方法
| 方法 | 说明 |
|---|---|
| Constructor | 构造渲染表面。 |
| GetWidth | 获取宽度。 |
| GetHeight | 获取高度。 |
| SetSize | 设置宽高。 |
| SetColorAttachment | 设置单个颜色附件。 |
| SetColorAttachments | 设置多个颜色附件。 |
| GetColorAttachments | 获取颜色附件数组。 |
| SetDepthAttachment | 设置深度附件。 |
| GetDepthAttachment | 获取深度附件。 |
| SetRenderArea | 设置自定义渲染区域。 |
| ResetRenderArea | 清除自定义渲染区域。 |
| HasCustomRenderArea | 判断是否启用了自定义渲染区域。 |
| GetRenderArea | 获取当前实际生效的渲染区域。 |
| GetRenderAreaWidth | 获取当前渲染区域宽度。 |
| GetRenderAreaHeight | 获取当前渲染区域高度。 |
| SetClearColorOverride | 设置清屏颜色覆盖。 |
| ClearClearColorOverride | 清除清屏颜色覆盖。 |
| HasClearColorOverride | 判断是否启用了清屏颜色覆盖。 |
| GetClearColorOverride | 获取清屏颜色覆盖值。 |
| SetAutoTransitionEnabled | 设置是否自动切换附件状态。 |
| IsAutoTransitionEnabled | 查询是否自动切换附件状态。 |
| SetColorStateBefore | 设置渲染前颜色附件状态。 |
| GetColorStateBefore | 获取渲染前颜色附件状态。 |
| SetColorStateAfter | 设置渲染后颜色附件状态。 |
| GetColorStateAfter | 获取渲染后颜色附件状态。 |
| SetDepthStateBefore | 设置渲染前深度附件状态。 |
| GetDepthStateBefore | 获取渲染前深度附件状态。 |
| SetDepthStateAfter | 设置渲染后深度附件状态。 |
| GetDepthStateAfter | 获取渲染后深度附件状态。 |
| SetSampleDesc | 设置 sample count / quality。 |
| GetSampleCount | 获取 sample count。 |
| GetSampleQuality | 获取 sample quality。 |
设计说明
把 RenderSurface 做成独立对象的价值在当前重构后的渲染链路里更直接：
SceneRenderer可以在构造 post-process / final-output request 时复制颜色/深度附件约束、sample 描述和 render area，而不必重新展开 swap chain 细节。BuiltinForwardPipeline与多个 builtin pass 可以从同一份 surface 描述中同时解析附件格式、状态切换与 sample 描述，避免每个调用点重复拼装GraphicsPipelineDesc前置条件。- Editor overlay、selection outline、object-id 等附加阶段可以复用主场景输出的深度/颜色状态约定，而不需要各自发明一套 surface 协议。