88 lines
5.7 KiB
Markdown
88 lines
5.7 KiB
Markdown
# 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](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 等路径都会消费这些 before / after 状态；关闭自动切换后，`RenderSurface` 只保留契约信息，不会主动纠正真实 GPU 状态。
|
||
- [SetSampleDesc](SetSampleDesc.md) 会把 `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](Constructor.md) | 构造渲染表面。 |
|
||
| [GetWidth](GetWidth.md) | 获取宽度。 |
|
||
| [GetHeight](GetHeight.md) | 获取高度。 |
|
||
| [SetSize](SetSize.md) | 设置宽高。 |
|
||
| [SetColorAttachment](SetColorAttachment.md) | 设置单个颜色附件。 |
|
||
| [SetColorAttachments](SetColorAttachments.md) | 设置多个颜色附件。 |
|
||
| [GetColorAttachments](GetColorAttachments.md) | 获取颜色附件数组。 |
|
||
| [SetDepthAttachment](SetDepthAttachment.md) | 设置深度附件。 |
|
||
| [GetDepthAttachment](GetDepthAttachment.md) | 获取深度附件。 |
|
||
| [SetRenderArea](SetRenderArea.md) | 设置自定义渲染区域。 |
|
||
| [ResetRenderArea](ResetRenderArea.md) | 清除自定义渲染区域。 |
|
||
| [HasCustomRenderArea](HasCustomRenderArea.md) | 判断是否启用了自定义渲染区域。 |
|
||
| [GetRenderArea](GetRenderArea.md) | 获取当前实际生效的渲染区域。 |
|
||
| [GetRenderAreaWidth](GetRenderAreaWidth.md) | 获取当前渲染区域宽度。 |
|
||
| [GetRenderAreaHeight](GetRenderAreaHeight.md) | 获取当前渲染区域高度。 |
|
||
| [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏颜色覆盖。 |
|
||
| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏颜色覆盖。 |
|
||
| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏颜色覆盖。 |
|
||
| [GetClearColorOverride](GetClearColorOverride.md) | 获取清屏颜色覆盖值。 |
|
||
| [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) | 设置是否自动切换附件状态。 |
|
||
| [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) | 查询是否自动切换附件状态。 |
|
||
| [SetColorStateBefore](SetColorStateBefore.md) | 设置渲染前颜色附件状态。 |
|
||
| [GetColorStateBefore](GetColorStateBefore.md) | 获取渲染前颜色附件状态。 |
|
||
| [SetColorStateAfter](SetColorStateAfter.md) | 设置渲染后颜色附件状态。 |
|
||
| [GetColorStateAfter](GetColorStateAfter.md) | 获取渲染后颜色附件状态。 |
|
||
| [SetDepthStateBefore](SetDepthStateBefore.md) | 设置渲染前深度附件状态。 |
|
||
| [GetDepthStateBefore](GetDepthStateBefore.md) | 获取渲染前深度附件状态。 |
|
||
| [SetDepthStateAfter](SetDepthStateAfter.md) | 设置渲染后深度附件状态。 |
|
||
| [GetDepthStateAfter](GetDepthStateAfter.md) | 获取渲染后深度附件状态。 |
|
||
| [SetSampleDesc](SetSampleDesc.md) | 设置 sample count / quality。 |
|
||
| [GetSampleCount](GetSampleCount.md) | 获取 sample count。 |
|
||
| [GetSampleQuality](GetSampleQuality.md) | 获取 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 协议。
|
||
|
||
## 相关文档
|
||
|
||
- [当前模块](../Rendering.md)
|
||
- [RenderContext](../RenderContext/RenderContext.md)
|
||
- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
|
||
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
|