85 lines
4.7 KiB
Markdown
85 lines
4.7 KiB
Markdown
# RenderSurface
|
||
|
||
**命名空间**: `XCEngine::Rendering`
|
||
|
||
**类型**: `class`
|
||
|
||
**头文件**: `XCEngine/Rendering/RenderSurface.h`
|
||
|
||
**描述**: 描述一次渲染输出使用的目标表面，包括颜色/深度附件、render area、清屏覆写、自动状态切换约定以及采样描述。
|
||
|
||
## 概览
|
||
|
||
`RenderSurface` 把“这一阶段渲染到哪里、渲染前后资源期望处于什么状态、目标表面采用什么采样描述”集中到一个轻量对象里。当前它负责承载：
|
||
|
||
- 输出尺寸
|
||
- 颜色附件数组与深度附件
|
||
- 可选自定义 render area
|
||
- 可选 clear color override
|
||
- 颜色附件前后状态
|
||
- 深度附件前后状态
|
||
- 是否启用自动状态切换
|
||
- `sampleCount` / `sampleQuality`
|
||
|
||
`SceneRenderer`、`CameraRenderer`、builtin scene pass 和 fullscreen pass 会把这些约定继续传递到 request、pipeline desc 与 barrier 逻辑里。
|
||
|
||
## 当前实现边界
|
||
|
||
- 状态仍是“整组颜色附件一份 before/after，深度附件一份 before/after”，不是每个 attachment 独立配置。
|
||
- `SetSampleDesc()` 只记录采样描述，不会验证附件或后端是否真的支持该 MSAA 配置。
|
||
- `SetSampleDesc(0, quality)` 会把 `sampleCount` 归一化为 `1`；当有效 `sampleCount <= 1` 时，`sampleQuality` 会被压成 `0`。
|
||
- render area 仍会在设置和读取时 clamp 到当前 surface 尺寸内。
|
||
- 仍没有 load/store action、resolve attachment、mip slice、array slice 等更细粒度 surface 描述。
|
||
|
||
## 公开方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| [Constructor](Constructor.md) | 构造空的 render surface。 |
|
||
| [GetWidth](GetWidth.md) | 获取 surface 宽度。 |
|
||
| [GetHeight](GetHeight.md) | 获取 surface 高度。 |
|
||
| [SetSize](SetSize.md) | 更新 surface 尺寸。 |
|
||
| [SetColorAttachment](SetColorAttachment.md) | 设置单个颜色附件。 |
|
||
| [SetColorAttachments](SetColorAttachments.md) | 设置颜色附件数组。 |
|
||
| [GetColorAttachments](GetColorAttachments.md) | 读取当前颜色附件数组。 |
|
||
| [SetDepthAttachment](SetDepthAttachment.md) | 设置深度附件。 |
|
||
| [GetDepthAttachment](GetDepthAttachment.md) | 读取当前深度附件。 |
|
||
| [SetRenderArea](SetRenderArea.md) | 设置自定义 render area。 |
|
||
| [ResetRenderArea](ResetRenderArea.md) | 清除自定义 render area。 |
|
||
| [HasCustomRenderArea](HasCustomRenderArea.md) | 判断是否启用了自定义 render area。 |
|
||
| [GetRenderArea](GetRenderArea.md) | 获取当前实际生效的 render area。 |
|
||
| [GetRenderAreaWidth](GetRenderAreaWidth.md) | 获取 render area 宽度。 |
|
||
| [GetRenderAreaHeight](GetRenderAreaHeight.md) | 获取 render area 高度。 |
|
||
| [SetClearColorOverride](SetClearColorOverride.md) | 设置 clear color override。 |
|
||
| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除 clear color override。 |
|
||
| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否存在 clear color override。 |
|
||
| [GetClearColorOverride](GetClearColorOverride.md) | 读取 clear color override。 |
|
||
| [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) | 设置 surface 的采样数和采样质量。 |
|
||
| [GetSampleCount](GetSampleCount.md) | 读取当前采样数。 |
|
||
| [GetSampleQuality](GetSampleQuality.md) | 读取当前采样质量。 |
|
||
|
||
## 设计说明
|
||
|
||
把 surface 做成独立对象，而不是让 pipeline 直接吃裸 `RHIResourceView*`，好处是：
|
||
|
||
- 目标尺寸和附件集合可以一起传递。
|
||
- 清屏策略、资源状态约定和采样描述可以挂在目标表面上，而不是散落在调用点。
|
||
- 同一条渲染链更容易复用到 back buffer、离屏纹理、intermediate post-process surface 和 editor preview surface。
|
||
|
||
## 相关文档
|
||
|
||
- [当前模块](../Rendering.md)
|
||
- [RenderContext](../RenderContext/RenderContext.md)
|
||
- [RenderPass](../RenderPass/RenderPass.md)
|
||
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
|