# 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)