docs(rendering): sync render surface state and sample docs
This commit is contained in:
@@ -0,0 +1,33 @@
|
|||||||
|
# RenderSurface::GetDepthStateAfter
|
||||||
|
|
||||||
|
返回深度附件在本次渲染结束后预期应处于的状态。
|
||||||
|
```cpp
|
||||||
|
RHI::ResourceStates GetDepthStateAfter() const;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 返回值
|
||||||
|
|
||||||
|
- 返回内部保存的深度附件“结束状态”；默认值是 `DepthWrite`。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 这个返回值描述的是阶段性契约，不是对 GPU 实际状态的即时查询。
|
||||||
|
- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，多个 builtin 渲染路径会在结束 render pass 后把深度附件切回这个状态。
|
||||||
|
- `SceneRenderer` 在派生 fullscreen surface 时会继续保留这份深度 after 状态，使后续阶段仍能沿用同一份资源状态约定。
|
||||||
|
|
||||||
|
## 调用方影响
|
||||||
|
|
||||||
|
- 如果后续 pass 依赖深度纹理以 `PixelShaderResource` 等状态被采样，调用方应显式把这个返回值对应的 setter 配置成匹配状态。
|
||||||
|
- 默认值 `DepthWrite` 适合“本阶段前后都继续作为深度写入目标”的简单场景。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [SetDepthStateAfter](SetDepthStateAfter.md)
|
||||||
|
- [GetDepthStateBefore](GetDepthStateBefore.md)
|
||||||
|
- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
# RenderSurface::GetDepthStateBefore
|
||||||
|
|
||||||
|
返回深度附件进入本次渲染前预期所处的状态。
|
||||||
|
```cpp
|
||||||
|
RHI::ResourceStates GetDepthStateBefore() const;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 返回值
|
||||||
|
|
||||||
|
- 返回内部保存的深度附件“起始状态”；默认值是 `DepthWrite`。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 这不是逐资源的真实状态查询，而是 `RenderSurface` 暴露给调用方和 builtin pass 的契约值。
|
||||||
|
- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，主场景、depth-style 与 object-id 这些路径会把它作为深度附件进入本次 pass 前的 barrier 来源状态。
|
||||||
|
- `SceneRenderer` 在复用深度附件构造 fullscreen 阶段 surface 时，也会保留这个值。
|
||||||
|
|
||||||
|
## 调用方影响
|
||||||
|
|
||||||
|
- 如果调用方关闭自动状态切换，就必须自己保证深度附件真的处于这里声明的状态。
|
||||||
|
- 这个值通常和 [GetDepthStateAfter](GetDepthStateAfter.md) 配对出现，用来描述同一块深度资源在本阶段前后的状态约定。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [SetDepthStateBefore](SetDepthStateBefore.md)
|
||||||
|
- [GetDepthStateAfter](GetDepthStateAfter.md)
|
||||||
|
- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
|
||||||
28
docs/api/XCEngine/Rendering/RenderSurface/GetSampleCount.md
Normal file
28
docs/api/XCEngine/Rendering/RenderSurface/GetSampleCount.md
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
# RenderSurface::GetSampleCount
|
||||||
|
|
||||||
|
返回当前 surface 的 sample count。
|
||||||
|
```cpp
|
||||||
|
uint32_t GetSampleCount() const;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 返回值
|
||||||
|
|
||||||
|
- 返回内部保存的采样数；默认值是 `1`。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 这个值会被 `RenderSurfacePipelineUtils` 消费并写入图形管线描述。
|
||||||
|
- `SceneRenderer` 也会用它判断主场景输出是否仍满足 fullscreen post-process / final-output 所要求的单采样约束。
|
||||||
|
- 如果调用方此前通过 [SetSampleDesc](SetSampleDesc.md) 传入了 `0`，这里返回的仍会是规范化后的 `1`。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [SetSampleDesc](SetSampleDesc.md)
|
||||||
|
- [GetSampleQuality](GetSampleQuality.md)
|
||||||
|
- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
# RenderSurface::GetSampleQuality
|
||||||
|
|
||||||
|
返回当前 surface 的 sample quality。
|
||||||
|
```cpp
|
||||||
|
uint32_t GetSampleQuality() const;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 返回值
|
||||||
|
|
||||||
|
- 返回内部保存的 quality 值；默认值是 `0`。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 这个值会被 `RenderSurfacePipelineUtils` 继续写入 `GraphicsPipelineDesc.sampleQuality`。
|
||||||
|
- 当前实现保证单采样 surface 的 quality 总是 `0`；只有多采样时这里才可能返回调用方显式设置的非零值。
|
||||||
|
- `CameraRenderRequest` 的 surface 合法性检查也依赖“单采样时 quality 必须为 `0`”这条约束。
|
||||||
|
|
||||||
|
## 调用方影响
|
||||||
|
|
||||||
|
- 如果后端只识别 `sampleCount`，调用方仍可以保留统一的 `RenderSurface` 描述，而把 `sampleQuality` 当作由具体 RHI 选择性消费的附加信息。
|
||||||
|
- 对 fullscreen post-process / final-output 链路而言，`sampleCount == 1 && sampleQuality == 0` 才是当前允许的输入形态。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [SetSampleDesc](SetSampleDesc.md)
|
||||||
|
- [GetSampleCount](GetSampleCount.md)
|
||||||
|
- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
|
||||||
@@ -6,31 +6,33 @@
|
|||||||
|
|
||||||
**头文件**: `XCEngine/Rendering/RenderSurface.h`
|
**头文件**: `XCEngine/Rendering/RenderSurface.h`
|
||||||
|
|
||||||
**描述**: 描述当前渲染目标表面，包括尺寸、颜色/深度附件、自定义渲染区域、清屏色覆盖和颜色附件自动状态切换策略。
|
**描述**: 描述当前渲染目标表面，包括尺寸、颜色/深度附件、自定义渲染区域、清屏覆盖、自动状态切换，以及与管线创建对齐的 sample 描述。
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
`RenderSurface` 的作用，是把“这一帧到底往哪里画”从具体 swap chain 或 framebuffer 管理逻辑里抽离出来。
|
`RenderSurface` 把“这一次渲染要写到哪里、写之前/写之后资源预期处于什么状态”从具体 swap chain、framebuffer 和缓存分配逻辑里抽离出来，变成 `Planning`、`Execution`、builtin pass 与 editor overlay 都能复用的统一协议对象。
|
||||||
|
|
||||||
当前它负责描述：
|
当前它负责描述：
|
||||||
|
|
||||||
- 宽高
|
- 宽高。
|
||||||
- 一组颜色附件
|
- 一组颜色附件。
|
||||||
- 一个深度附件
|
- 一个可选深度附件。
|
||||||
- 可选自定义 render area
|
- 一个可选自定义 render area。
|
||||||
- 可选清屏色覆盖
|
- 一个可选清屏颜色覆盖。
|
||||||
- 颜色附件渲染前后状态
|
- 颜色附件共享的 before / after 状态。
|
||||||
- 是否自动执行颜色附件状态切换
|
- 深度附件共享的 before / after 状态。
|
||||||
|
- 是否由渲染路径自动执行颜色/深度附件状态切换。
|
||||||
|
- 当前 surface 的 MSAA `sampleCount` / `sampleQuality`。
|
||||||
|
|
||||||
这类抽象很符合商业引擎里 render target / render surface 的常见分层，因为同一条渲染管线不应该只会往窗口 back buffer 画。
|
`RenderSurface` 自己不拥有 GPU 资源，也不验证附件尺寸、资源类型或 sample 描述是否真实匹配；它只是把这组约束交给调用方和具体渲染路径消费。
|
||||||
|
|
||||||
## 当前实现边界
|
## 当前实现边界
|
||||||
|
|
||||||
- 当前只为颜色附件维护统一的 `stateBefore` / `stateAfter`，不是每个附件单独配置。
|
- 颜色附件仍只有一组统一的 `colorStateBefore` / `colorStateAfter`，深度附件也只有一组统一的 `depthStateBefore` / `depthStateAfter`；它不是逐 attachment 的精细状态表。
|
||||||
- 自动状态切换当前只处理颜色附件，不处理深度附件。
|
- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 等路径都会消费这些 before / after 状态；关闭自动切换后，`RenderSurface` 只保留契约信息，不会主动纠正真实 GPU 状态。
|
||||||
- 自定义 render area 会在设置时和取回时都被夹到当前 surface 尺寸范围内。
|
- [SetSampleDesc](SetSampleDesc.md) 会把 `sampleCount == 0` 规范化为单采样 `1, 0`；只有 `sampleCount > 1` 时 `sampleQuality` 才保留调用方传入值。
|
||||||
- 当前不会校验附件数量、附件尺寸与 `RenderSurface` 宽高是否匹配。
|
- `SceneRenderer` 当前要求 fullscreen post-process / final-output 链路的主场景 surface 为单采样，因此多重采样主表面不会进入这两段 fullscreen 阶段。
|
||||||
- 当前没有 load/store action、MSAA resolve、mip slice 或 array slice 等更丰富的 surface 配置。
|
- 当前没有 load/store action、resolve target、mip slice、array slice 等更细粒度的 surface 配置。
|
||||||
|
|
||||||
## 公开方法
|
## 公开方法
|
||||||
|
|
||||||
@@ -51,28 +53,35 @@
|
|||||||
| [GetRenderArea](GetRenderArea.md) | 获取当前实际生效的渲染区域。 |
|
| [GetRenderArea](GetRenderArea.md) | 获取当前实际生效的渲染区域。 |
|
||||||
| [GetRenderAreaWidth](GetRenderAreaWidth.md) | 获取当前渲染区域宽度。 |
|
| [GetRenderAreaWidth](GetRenderAreaWidth.md) | 获取当前渲染区域宽度。 |
|
||||||
| [GetRenderAreaHeight](GetRenderAreaHeight.md) | 获取当前渲染区域高度。 |
|
| [GetRenderAreaHeight](GetRenderAreaHeight.md) | 获取当前渲染区域高度。 |
|
||||||
| [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏色覆盖。 |
|
| [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏颜色覆盖。 |
|
||||||
| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏色覆盖。 |
|
| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏颜色覆盖。 |
|
||||||
| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏色覆盖。 |
|
| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏颜色覆盖。 |
|
||||||
| [GetClearColorOverride](GetClearColorOverride.md) | 获取清屏色覆盖值。 |
|
| [GetClearColorOverride](GetClearColorOverride.md) | 获取清屏颜色覆盖值。 |
|
||||||
| [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) | 设置是否自动切换颜色附件状态。 |
|
| [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) | 设置是否自动切换附件状态。 |
|
||||||
| [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) | 查询是否自动切换颜色附件状态。 |
|
| [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) | 查询是否自动切换附件状态。 |
|
||||||
| [SetColorStateBefore](SetColorStateBefore.md) | 设置渲染前颜色附件状态。 |
|
| [SetColorStateBefore](SetColorStateBefore.md) | 设置渲染前颜色附件状态。 |
|
||||||
| [GetColorStateBefore](GetColorStateBefore.md) | 获取渲染前颜色附件状态。 |
|
| [GetColorStateBefore](GetColorStateBefore.md) | 获取渲染前颜色附件状态。 |
|
||||||
| [SetColorStateAfter](SetColorStateAfter.md) | 设置渲染后颜色附件状态。 |
|
| [SetColorStateAfter](SetColorStateAfter.md) | 设置渲染后颜色附件状态。 |
|
||||||
| [GetColorStateAfter](GetColorStateAfter.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。 |
|
||||||
|
|
||||||
## 设计说明
|
## 设计说明
|
||||||
|
|
||||||
把 surface 做成独立对象，而不是让 pipeline 直接吃裸 `RHIResourceView*`，好处很明确：
|
把 `RenderSurface` 做成独立对象的价值在当前重构后的渲染链路里更直接：
|
||||||
|
|
||||||
- 目标尺寸和附件集合可以一起传递。
|
- `SceneRenderer` 可以在构造 post-process / final-output request 时复制颜色/深度附件约束、sample 描述和 render area，而不必重新展开 swap chain 细节。
|
||||||
- 清屏策略和资源状态策略可以挂在目标上，而不是散落在调用点。
|
- `BuiltinForwardPipeline` 与多个 builtin pass 可以从同一份 surface 描述中同时解析附件格式、状态切换与 sample 描述，避免每个调用点重复拼装 `GraphicsPipelineDesc` 前置条件。
|
||||||
- 同一条管线更容易复用于 back buffer、离屏纹理和 editor preview surface。
|
- Editor overlay、selection outline、object-id 等附加阶段可以复用主场景输出的深度/颜色状态约定，而不需要各自发明一套 surface 协议。
|
||||||
|
|
||||||
## 相关文档
|
## 相关文档
|
||||||
|
|
||||||
- [当前模块](../Rendering.md)
|
- [当前模块](../Rendering.md)
|
||||||
- [RenderContext](../RenderContext/RenderContext.md)
|
- [RenderContext](../RenderContext/RenderContext.md)
|
||||||
- [RenderPipeline](../RenderPipeline/RenderPipeline.md)
|
- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
|
||||||
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
|
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
|
||||||
|
|||||||
@@ -0,0 +1,28 @@
|
|||||||
|
# RenderSurface::SetDepthStateAfter
|
||||||
|
|
||||||
|
设置深度附件在本次渲染结束后预期应回到的统一状态。
|
||||||
|
```cpp
|
||||||
|
void SetDepthStateAfter(RHI::ResourceStates state);
|
||||||
|
```
|
||||||
|
|
||||||
|
## 参数
|
||||||
|
|
||||||
|
- `state` - 调用方希望深度附件在本阶段结束后处于的资源状态。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 这个值只写入 `RenderSurface` 内部，不会主动触发过渡。
|
||||||
|
- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass` 等路径会在绘制结束后把深度附件从 `DepthWrite` 切回这里声明的状态。
|
||||||
|
- 一些 post-scene / overlay 路径会把它当作“主场景阶段结束后的深度基线状态”继续消费。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [GetDepthStateAfter](GetDepthStateAfter.md)
|
||||||
|
- [SetDepthStateBefore](SetDepthStateBefore.md)
|
||||||
|
- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
# RenderSurface::SetDepthStateBefore
|
||||||
|
|
||||||
|
设置深度附件在本次渲染开始前预期所处的统一状态。
|
||||||
|
```cpp
|
||||||
|
void SetDepthStateBefore(RHI::ResourceStates state);
|
||||||
|
```
|
||||||
|
|
||||||
|
## 参数
|
||||||
|
|
||||||
|
- `state` - 调用方认为当前深度附件进入本次 pass 前所处的资源状态。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 这个值只写入 `RenderSurface` 自身，不会立即发出 barrier。
|
||||||
|
- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass` 等路径会把它作为深度附件进入 `DepthWrite` 前的来源状态。
|
||||||
|
- `SceneRenderer` 在为 post-process / final-output 构造派生 `RenderSurface` 时，会继续复制这份深度 before 状态。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [GetDepthStateBefore](GetDepthStateBefore.md)
|
||||||
|
- [SetDepthStateAfter](SetDepthStateAfter.md)
|
||||||
|
- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
|
||||||
30
docs/api/XCEngine/Rendering/RenderSurface/SetSampleDesc.md
Normal file
30
docs/api/XCEngine/Rendering/RenderSurface/SetSampleDesc.md
Normal file
@@ -0,0 +1,30 @@
|
|||||||
|
# RenderSurface::SetSampleDesc
|
||||||
|
|
||||||
|
设置当前 surface 的 sample count 和 sample quality。
|
||||||
|
```cpp
|
||||||
|
void SetSampleDesc(uint32_t sampleCount, uint32_t sampleQuality = 0);
|
||||||
|
```
|
||||||
|
|
||||||
|
## 参数
|
||||||
|
|
||||||
|
- `sampleCount` - 期望的采样数；传入 `0` 时当前实现会规范化成单采样。
|
||||||
|
- `sampleQuality` - 当 `sampleCount > 1` 时保留的 quality 值；单采样时会被重置成 `0`。
|
||||||
|
|
||||||
|
## 当前语义
|
||||||
|
|
||||||
|
- 实现会把 `sampleCount == 0` 规范化为 `1`。
|
||||||
|
- 只有 `sampleCount > 1` 时，`sampleQuality` 才保留调用方传入值；否则内部强制存成 `0`。
|
||||||
|
- `RenderSurfacePipelineUtils` 会把这组值写入 `GraphicsPipelineDesc.sampleCount` / `sampleQuality`。
|
||||||
|
- `SceneRenderer` 当前要求 fullscreen post-process / final-output 链路的主场景输出为单采样，因此多采样主 surface 会跳过这两段 fullscreen 阶段。
|
||||||
|
|
||||||
|
## 测试覆盖
|
||||||
|
|
||||||
|
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||||||
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [RenderSurface](RenderSurface.md)
|
||||||
|
- [GetSampleCount](GetSampleCount.md)
|
||||||
|
- [GetSampleQuality](GetSampleQuality.md)
|
||||||
|
- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
|
||||||
Reference in New Issue
Block a user