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

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	构造空的 render surface。
GetWidth	获取 surface 宽度。
GetHeight	获取 surface 高度。
SetSize	更新 surface 尺寸。
SetColorAttachment	设置单个颜色附件。
SetColorAttachments	设置颜色附件数组。
GetColorAttachments	读取当前颜色附件数组。
SetDepthAttachment	设置深度附件。
GetDepthAttachment	读取当前深度附件。
SetRenderArea	设置自定义 render area。
ResetRenderArea	清除自定义 render area。
HasCustomRenderArea	判断是否启用了自定义 render area。
GetRenderArea	获取当前实际生效的 render area。
GetRenderAreaWidth	获取 render area 宽度。
GetRenderAreaHeight	获取 render area 高度。
SetClearColorOverride	设置 clear color override。
ClearClearColorOverride	清除 clear color override。
HasClearColorOverride	判断是否存在 clear color override。
GetClearColorOverride	读取 clear color override。
SetAutoTransitionEnabled	开关自动状态切换约定。
IsAutoTransitionEnabled	查询是否启用自动状态切换。
SetColorStateBefore	设置颜色附件渲染前状态。
GetColorStateBefore	读取颜色附件渲染前状态。
SetColorStateAfter	设置颜色附件渲染后状态。
GetColorStateAfter	读取颜色附件渲染后状态。
SetDepthStateBefore	设置深度附件渲染前状态。
GetDepthStateBefore	读取深度附件渲染前状态。
SetDepthStateAfter	设置深度附件渲染后状态。
GetDepthStateAfter	读取深度附件渲染后状态。
SetSampleDesc	设置 surface 的采样数和采样质量。
GetSampleCount	读取当前采样数。
GetSampleQuality	读取当前采样质量。

设计说明

把 surface 做成独立对象，而不是让 pipeline 直接吃裸 RHIResourceView*，好处是：

• 目标尺寸和附件集合可以一起传递。
• 清屏策略、资源状态约定和采样描述可以挂在目标表面上，而不是散落在调用点。
• 同一条渲染链更容易复用到 back buffer、离屏纹理、intermediate post-process surface 和 editor preview surface。

相关文档

• 当前模块
• RenderContext
• RenderPass
• BuiltinForwardPipeline