docs(api): refine D3D12 render pass and framebuffer docs
This commit is contained in:
@@ -1,28 +1,26 @@
|
||||
# D3D12Framebuffer::D3D12Framebuffer()
|
||||
|
||||
构造对象。
|
||||
# D3D12Framebuffer::D3D12Framebuffer
|
||||
|
||||
```cpp
|
||||
D3D12Framebuffer();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 framebuffer 包装对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 构造函数体为空
|
||||
- 宽高保持类内默认值 `0`
|
||||
- `m_renderPass` 为 `nullptr`
|
||||
- render target handle 数组为空
|
||||
- depth-stencil handle 为零值
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 使用说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
}
|
||||
```
|
||||
这个对象在构造后还不具备可用渲染语义，通常需要立即进入 [Initialize](Initialize.md)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [D3D12Framebuffer](D3D12Framebuffer.md)
|
||||
|
||||
@@ -6,38 +6,84 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/D3D12/D3D12Framebuffer.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Framebuffer` public API。
|
||||
**描述**: D3D12 后端的 framebuffer 抽象，但当前实现并不对应某个原生 D3D12 对象，而是一个“渲染目标句柄与尺寸打包器”。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`D3D12Framebuffer.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
在 Vulkan 里，framebuffer 往往是真实的 API 对象；在 D3D12 里，并不存在等价的 `ID3D12Framebuffer`。
|
||||
|
||||
## 声明概览
|
||||
因此当前 `D3D12Framebuffer` 的职责非常具体：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `D3D12Framebuffer` | `class` | 继承自 `RHIFramebuffer` 的公开声明。 |
|
||||
- 保存一组 color RTV 的 `D3D12_CPU_DESCRIPTOR_HANDLE`
|
||||
- 可选保存一个 depth-stencil DSV 的 `D3D12_CPU_DESCRIPTOR_HANDLE`
|
||||
- 缓存宽高和关联的 [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
|
||||
|
||||
## 公共方法
|
||||
这使得 [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 在 `BeginRenderPass(...)` 时可以一次性拿到渲染目标集合，而不需要每次都重新从视图对象中拆句柄。
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [D3D12Framebuffer()](Constructor.md) | 构造对象。 |
|
||||
| [~D3D12Framebuffer()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
|
||||
| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
|
||||
| [IsValid](IsValid.md) | 查询当前状态。 |
|
||||
| [GetRenderTargetHandle](GetRenderTargetHandle.md) | 获取相关状态或对象。 |
|
||||
| [GetDepthStencilHandle](GetDepthStencilHandle.md) | 获取相关状态或对象。 |
|
||||
| [HasDepthStencil](HasDepthStencil.md) | 判断是否具备指定状态或能力。 |
|
||||
| [GetRenderTargetCount](GetRenderTargetCount.md) | 获取相关状态或对象。 |
|
||||
| [GetRenderTargetHandles](GetRenderTargetHandles.md) | 获取相关状态或对象。 |
|
||||
| [GetRenderPass](GetRenderPass.md) | 获取相关状态或对象。 |
|
||||
## 设计定位
|
||||
|
||||
这个类更像引擎内部的“渲染附件绑定描述”。
|
||||
|
||||
它当前不做这些事情：
|
||||
|
||||
- 不创建原生 D3D12 framebuffer 对象
|
||||
- 不拥有纹理或资源视图生命周期
|
||||
- 不验证 render pass 与附件之间的格式兼容性
|
||||
- 不处理附件 resize、重建或状态迁移
|
||||
|
||||
从商业级引擎设计角度看，这种抽象是合理的。因为 D3D12 本来就把渲染目标绑定拆成了 RTV/DSV descriptor 组合，framebuffer 更多是引擎为了统一 RHI 心智模型而引入的组织层。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造后是空对象
|
||||
- [Initialize](Initialize.md) 会缓存 render pass、尺寸和 CPU descriptor handle
|
||||
- [Shutdown](Shutdown.md) 清空句柄数组并复位尺寸、render pass 指针
|
||||
- 析构时自动调用 [Shutdown](Shutdown.md)
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- [GetNativeHandle](GetNativeHandle.md) 永远返回 `nullptr`
|
||||
- [Initialize](Initialize.md) 不做严格校验，基本只是把传入句柄抄进内部数组
|
||||
- 如果某个 `colorAttachments[i]` 为 `nullptr`，对应 handle 会保持为零值
|
||||
- [IsValid](IsValid.md) 只检查 `m_renderPass != nullptr`
|
||||
- [HasDepthStencil](HasDepthStencil.md) 只检查 `m_depthStencilHandle.ptr != 0`
|
||||
- 对象不拥有 `RHIResourceView` 和 `D3D12RenderPass`，只是保存非 owning 引用或复制后的 handle
|
||||
|
||||
## 为什么这样设计
|
||||
|
||||
这类设计的价值在于把“API 没有对象，但引擎需要概念”的空白补上。
|
||||
|
||||
它带来的好处是：
|
||||
|
||||
- 上层 RHI 能继续使用 framebuffer / render pass 这组熟悉抽象
|
||||
- D3D12 命令列表实现可以更整洁，不必每次重新拆附件参数
|
||||
- 文档和测试可以围绕统一概念展开，跨 Vulkan / D3D12 对照时也更容易理解
|
||||
|
||||
它的代价同样明显：
|
||||
|
||||
- 这是一个纯引擎侧约定对象，不是驱动层面的强校验边界
|
||||
- 很多兼容性问题不会在创建时暴露，而是等到真正渲染时才出问题
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `colorAttachmentCount > 0` 且 `colorAttachments == nullptr` 时，当前实现会直接解引用空指针
|
||||
- 不检查 `colorAttachmentCount` 是否与 render pass 的 color attachment 数量匹配
|
||||
- 不检查 depth-stencil 附件是否与 render pass 需求匹配
|
||||
- 不检查宽高是否为 0，测试里也允许 0 尺寸对象存在
|
||||
- `GetRenderTargetHandles()` 返回的是内部数组指针，调用方需要自己配合 `GetRenderTargetCount()` 使用
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetRenderTargetHandle](GetRenderTargetHandle.md)
|
||||
- [GetRenderTargetHandles](GetRenderTargetHandles.md)
|
||||
- [GetDepthStencilHandle](GetDepthStencilHandle.md)
|
||||
- [HasDepthStencil](HasDepthStencil.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [D3D12](../D3D12.md)
|
||||
- [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
|
||||
- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)
|
||||
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
|
||||
|
||||
@@ -1,29 +1,20 @@
|
||||
# D3D12Framebuffer::~D3D12Framebuffer()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# D3D12Framebuffer::~D3D12Framebuffer
|
||||
|
||||
```cpp
|
||||
~D3D12Framebuffer() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 framebuffer 对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数直接调用 [Shutdown](Shutdown.md)
|
||||
- 不销毁任何原生 D3D12 对象，因为当前类没有持有这类对象
|
||||
- 不负责释放 render pass、纹理或资源视图
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [D3D12Framebuffer](D3D12Framebuffer.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Framebuffer::GetDepthStencilHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_CPU_DESCRIPTOR_HANDLE GetDepthStencilHandle() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前缓存的 depth-stencil CPU descriptor handle。
|
||||
|
||||
**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_depthStencilHandle`
|
||||
- 如果没有 depth-stencil 附件，返回零值 handle
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetDepthStencilHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
通常应先用 [HasDepthStencil](HasDepthStencil.md) 判断是否存在有效 DSV，再决定是否把这个 handle 传入 `OMSetRenderTargets(...)`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [HasDepthStencil](HasDepthStencil.md)
|
||||
- [GetRenderTargetHandles](GetRenderTargetHandles.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Framebuffer::GetHeight
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetHeight() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 framebuffer 当前缓存的高度。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_height`
|
||||
- 不从附件纹理重新查询真实尺寸
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetHeight(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
和 [GetWidth](GetWidth.md) 一样，这个值只是初始化时写入的元数据，不是后端校验过的真实附件高度。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetWidth](GetWidth.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,30 +1,27 @@
|
||||
# D3D12Framebuffer::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 framebuffer 的原生句柄表示。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 始终返回 `nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这正好反映了 D3D12 的现实情况：当前抽象没有对应的原生 framebuffer 句柄可返回。
|
||||
|
||||
如果你需要的是真正参与绑定的底层数据，应使用：
|
||||
|
||||
- [GetRenderTargetHandles](GetRenderTargetHandles.md)
|
||||
- [GetDepthStencilHandle](GetDepthStencilHandle.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetRenderTargetHandles](GetRenderTargetHandles.md)
|
||||
- [GetDepthStencilHandle](GetDepthStencilHandle.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Framebuffer::GetRenderPass
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12RenderPass* GetRenderPass() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回与当前 framebuffer 关联的 render pass 指针。
|
||||
|
||||
**返回：** `D3D12RenderPass*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回缓存的 `m_renderPass`
|
||||
- 这是一个非 owning 指针
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderPass(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
当前 `D3D12CommandList::BeginRenderPass(...)` 仍然显式接收 `renderPass` 参数，因此这里的 getter 更多是调试和元数据访问用途，而不是唯一的数据来源。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [IsValid](IsValid.md)
|
||||
- [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12Framebuffer::GetRenderTargetCount
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetRenderTargetCount() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前缓存的颜色附件数量。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderTargetCount(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 返回 `m_renderTargetHandles.size()`
|
||||
- 这个数量来自 [Initialize](Initialize.md) 传入的 `colorAttachmentCount`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetRenderTargetHandle](GetRenderTargetHandle.md)
|
||||
- [GetRenderTargetHandles](GetRenderTargetHandles.md)
|
||||
|
||||
@@ -1,31 +1,23 @@
|
||||
# D3D12Framebuffer::GetRenderTargetHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_CPU_DESCRIPTOR_HANDLE GetRenderTargetHandle(uint32_t index) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `index` - 参数语义详见头文件声明。
|
||||
返回指定颜色附件的 CPU descriptor handle。
|
||||
|
||||
**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `index` 越界，返回零值 handle
|
||||
- 否则返回 `m_renderTargetHandles[index]`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderTargetHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
如果你要遍历全部 RTV，优先搭配 [GetRenderTargetCount](GetRenderTargetCount.md) 使用，避免依赖零值返回做流程控制。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetRenderTargetCount](GetRenderTargetCount.md)
|
||||
- [GetRenderTargetHandles](GetRenderTargetHandles.md)
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# D3D12Framebuffer::GetRenderTargetHandles
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const D3D12_CPU_DESCRIPTOR_HANDLE* GetRenderTargetHandles() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回内部 color RTV handle 数组的起始指针。
|
||||
|
||||
**返回：** `const D3D12_CPU_DESCRIPTOR_HANDLE*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_renderTargetHandles.data()`
|
||||
- 不复制数据
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetRenderTargetHandles(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 必须配合 [GetRenderTargetCount](GetRenderTargetCount.md) 使用
|
||||
- 不要在 [Shutdown](Shutdown.md) 之后继续持有这个指针
|
||||
|
||||
## 注意事项
|
||||
|
||||
如果数组为空，`data()` 的返回值不应被解引用。调用方必须先看数量。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetRenderTargetCount](GetRenderTargetCount.md)
|
||||
- [GetRenderTargetHandle](GetRenderTargetHandle.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Framebuffer::GetWidth
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetWidth() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 framebuffer 当前缓存的宽度。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_width`
|
||||
- 不从附件纹理重新查询真实尺寸
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::GetWidth(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个值完全来自 [Initialize](Initialize.md) 的传参。即使附件本身尺寸不同，这里也不会自动纠正。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetHeight](GetHeight.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,30 +1,22 @@
|
||||
# D3D12Framebuffer::HasDepthStencil
|
||||
|
||||
判断是否具备指定状态或能力。
|
||||
|
||||
```cpp
|
||||
bool HasDepthStencil() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
判断当前 framebuffer 是否缓存了非零的 depth-stencil handle。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 判断条件是 `m_depthStencilHandle.ptr != 0`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::HasDepthStencil(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
它不检查这个 handle 是否真的仍然有效，也不检查它是否与 render pass 描述兼容。它只是一个非常轻量的“是否存在非零句柄”判断。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetDepthStencilHandle](GetDepthStencilHandle.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,36 +1,47 @@
|
||||
# D3D12Framebuffer::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool Initialize(class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) override;
|
||||
bool Initialize(RHIRenderPass* renderPass,
|
||||
uint32_t width,
|
||||
uint32_t height,
|
||||
uint32_t colorAttachmentCount,
|
||||
RHIResourceView** colorAttachments,
|
||||
RHIResourceView* depthStencilAttachment) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `renderPass` - 参数语义详见头文件声明。
|
||||
- `width` - 参数语义详见头文件声明。
|
||||
- `height` - 参数语义详见头文件声明。
|
||||
- `colorAttachmentCount` - 参数语义详见头文件声明。
|
||||
- `colorAttachments` - 参数语义详见头文件声明。
|
||||
- `depthStencilAttachment` - 参数语义详见头文件声明。
|
||||
把 render pass、尺寸和资源视图对应的 CPU descriptor handle 组织成一个可供 D3D12 命令列表使用的 framebuffer 对象。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 把 `renderPass` 直接 `static_cast` 成 `D3D12RenderPass*` 并缓存到 `m_renderPass`
|
||||
- 缓存 `width` 和 `height`
|
||||
- 按 `colorAttachmentCount` 调整 `m_renderTargetHandles` 大小
|
||||
- 对每个非空 `colorAttachments[i]`，取出 [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md) 的 CPU handle 存入数组
|
||||
- 如果 `depthStencilAttachment` 非空，则缓存它的 CPU handle；否则把 depth-stencil handle 置零
|
||||
- 始终返回 `true`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 重要事实
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个初始化过程没有创建任何 D3D12 资源，也没有把任何对象注册到驱动层。它只是把“后续 `OMSetRenderTargets(...)` 需要的句柄集合”提前整理好。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 不检查 `renderPass` 是否为空
|
||||
- 不检查 `colorAttachmentCount` 与 render pass 描述是否匹配
|
||||
- 不检查 `colorAttachments` 是否为空；如果 `colorAttachmentCount > 0` 且它是空指针，会发生非法访问
|
||||
- 不检查 view 类型是否真的是 RTV / DSV
|
||||
- 不检查附件尺寸、格式、采样数是否兼容
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 常规路径应通过 [D3D12Device](../D3D12Device/D3D12Device.md) 的 `CreateFramebuffer()` 创建
|
||||
- 不要把这里的成功返回值当成“附件组合已通过后端校验”
|
||||
- 如果需要严格兼容性约束，应在更高层或未来的创建逻辑中补验证
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetRenderTargetHandle](GetRenderTargetHandle.md)
|
||||
- [GetDepthStencilHandle](GetDepthStencilHandle.md)
|
||||
- [D3D12RenderPass](../D3D12RenderPass/D3D12RenderPass.md)
|
||||
|
||||
@@ -1,30 +1,27 @@
|
||||
# D3D12Framebuffer::IsValid
|
||||
|
||||
查询当前状态。
|
||||
|
||||
```cpp
|
||||
bool IsValid() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
判断 framebuffer 当前是否被视为“有效”。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 只检查 `m_renderPass != nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 这意味着什么
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::IsValid(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个判定非常宽松。下面这些问题都不会让它返回 `false`：
|
||||
|
||||
- 宽高是 `0`
|
||||
- 某些 render target handle 仍然是零值
|
||||
- depth-stencil 缺失或不匹配
|
||||
- render pass 与附件格式不兼容
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetRenderPass](GetRenderPass.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# D3D12Framebuffer::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Framebuffer.h`，当前页面用于固定 `D3D12Framebuffer` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
清空 framebuffer 内部缓存的句柄与元数据。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 清空 `m_renderTargetHandles`
|
||||
- 把 `m_depthStencilHandle` 复位为零值
|
||||
- 把 `m_renderPass` 设为 `nullptr`
|
||||
- 把 `m_width` 和 `m_height` 设为 `0`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Framebuffer.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Framebuffer object;
|
||||
// 根据上下文补齐参数后调用 D3D12Framebuffer::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
因为当前类不拥有底层资源，所以 `Shutdown()` 的职责只是“忘掉这些句柄和关联关系”，而不是回收 GPU 对象。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Framebuffer.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [IsValid](IsValid.md)
|
||||
- [Destructor](Destructor.md)
|
||||
|
||||
@@ -1,28 +1,20 @@
|
||||
# D3D12RenderPass::D3D12RenderPass()
|
||||
|
||||
构造对象。
|
||||
# D3D12RenderPass::D3D12RenderPass
|
||||
|
||||
```cpp
|
||||
D3D12RenderPass();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 render pass 元数据对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
}
|
||||
```
|
||||
- 构造函数体为空
|
||||
- color attachment 数量默认为 `0`
|
||||
- depth-stencil 标志默认为 `false`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [D3D12RenderPass](D3D12RenderPass.md)
|
||||
|
||||
@@ -6,36 +6,78 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/D3D12/D3D12RenderPass.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12RenderPass` public API。
|
||||
**描述**: D3D12 后端的 render pass 元数据对象，用于保存 `AttachmentDesc` 并把 RHI 的 load/store 语义映射为 D3D12 access type。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`D3D12RenderPass.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
和 [D3D12Framebuffer](../D3D12Framebuffer/D3D12Framebuffer.md) 一样，`D3D12RenderPass` 不是原生 D3D12 对象。
|
||||
|
||||
## 声明概览
|
||||
它当前承担的核心职责是：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `D3D12RenderPass` | `class` | 继承自 `RHIRenderPass` 的公开声明。 |
|
||||
- 缓存 color attachment 与 depth-stencil attachment 描述
|
||||
- 为上层 RHI 保留“render pass”这一统一概念
|
||||
- 提供若干把 `LoadAction` / `StoreAction` 翻译成 `D3D12_RENDER_PASS_*_ACCESS_TYPE` 的辅助接口
|
||||
|
||||
## 公共方法
|
||||
## 设计定位
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [D3D12RenderPass()](Constructor.md) | 构造对象。 |
|
||||
| [~D3D12RenderPass()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [GetColorAttachmentCount](GetColorAttachmentCount.md) | 获取相关状态或对象。 |
|
||||
| [GetColorAttachments](GetColorAttachments.md) | 获取相关状态或对象。 |
|
||||
| [GetDepthStencilAttachment](GetDepthStencilAttachment.md) | 获取相关状态或对象。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [GetBeginningAccessType](GetBeginningAccessType.md) | 获取相关状态或对象。 |
|
||||
| [GetEndingAccessType](GetEndingAccessType.md) | 获取相关状态或对象。 |
|
||||
| [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md) | 获取相关状态或对象。 |
|
||||
| [GetDepthEndingAccessType](GetDepthEndingAccessType.md) | 获取相关状态或对象。 |
|
||||
在 D3D12 中，渲染过程可以用传统 `OMSetRenderTargets(...) + Clear*View(...)` 路径完成，也可以逐步接近更显式的 render pass 访问语义。
|
||||
|
||||
当前 XCEngine 选的是一个折中方案：
|
||||
|
||||
- 保留 render pass 抽象，方便跨后端统一
|
||||
- 先把 attachment 元数据和访问语义整理出来
|
||||
- 但命令列表实现目前仍主要依赖手动 clear 和 `OMSetRenderTargets(...)`
|
||||
|
||||
也就是说，`D3D12RenderPass` 目前更接近“元数据和策略对象”，而不是“驱动层 render pass 实例”。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造后为空对象
|
||||
- [Initialize](Initialize.md) 复制 attachment 描述
|
||||
- [Shutdown](Shutdown.md) 清空颜色附件并复位主要状态
|
||||
- 析构时自动调用 [Shutdown](Shutdown.md)
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- [GetNativeHandle](GetNativeHandle.md) 永远返回 `nullptr`
|
||||
- [Initialize](Initialize.md) 不做输入合法性校验，基本只是复制描述
|
||||
- [GetBeginningAccessType](GetBeginningAccessType.md) / [GetEndingAccessType](GetEndingAccessType.md) 提供的是“映射结果”，不是驱动对象状态
|
||||
- `StoreAction::Resolve` 和 `StoreAction::StoreAndResolve` 当前都会被映射成 `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE_RESOLVE`
|
||||
- 深度访问辅助函数只看 `loadOp` / `storeOp`，不会把 `stencilLoadOp` / `stencilStoreOp` 融入返回值
|
||||
- 当前 [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 的 `BeginRenderPass(...)` 并没有直接使用这些 access type getter，而是手动依据附件描述执行 clear
|
||||
|
||||
## 为什么这样设计
|
||||
|
||||
这是典型的引擎抽象先行路线。
|
||||
|
||||
这么做的好处是：
|
||||
|
||||
- RHI 层在 Vulkan、D3D12、OpenGL 之间可以共享相近的渲染通道心智模型
|
||||
- 后端可以逐步演进，而不是一开始就把 D3D12 特性全部绑定死在命令列表实现里
|
||||
- 文档和测试可以直接围绕 attachment/load/store 语义展开
|
||||
|
||||
代价是当前对象的很多能力只是“描述能力”，而不是“执行能力”。调用者不能把这些 getter 理解成已经驱动 GPU 的状态。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `colorAttachmentCount > 0` 且 `colorAttachments == nullptr` 时会发生非法访问
|
||||
- 不验证格式是否合法或是否适合 D3D12 使用
|
||||
- 不生成原生 render pass 句柄
|
||||
- 深度 access helper 不表达 stencil 独立访问语义
|
||||
- ending access 的 `StoreAndResolve` 语义被简化为 `RESOLVE`
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetBeginningAccessType](GetBeginningAccessType.md)
|
||||
- [GetEndingAccessType](GetEndingAccessType.md)
|
||||
- [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md)
|
||||
- [GetDepthEndingAccessType](GetDepthEndingAccessType.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [D3D12](../D3D12.md)
|
||||
- [D3D12Framebuffer](../D3D12Framebuffer/D3D12Framebuffer.md)
|
||||
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
|
||||
- [RHIRenderPass](../../RHIRenderPass/RHIRenderPass.md)
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
# D3D12RenderPass::~D3D12RenderPass()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# D3D12RenderPass::~D3D12RenderPass
|
||||
|
||||
```cpp
|
||||
~D3D12RenderPass() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 render pass 对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数内部直接调用 [Shutdown](Shutdown.md)
|
||||
- 不释放任何原生 D3D12 句柄，因为当前类没有持有这类句柄
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [D3D12RenderPass](D3D12RenderPass.md)
|
||||
|
||||
@@ -1,31 +1,25 @@
|
||||
# D3D12RenderPass::GetBeginningAccessType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE GetBeginningAccessType(uint32_t index) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `index` - 参数语义详见头文件声明。
|
||||
把指定 color attachment 的 `LoadAction` 映射为 D3D12 的 beginning access type。
|
||||
|
||||
**返回：** `D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 越界时返回 `D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE_NO_ACCESS`
|
||||
- `LoadAction::Clear` 映射为 `CLEAR`
|
||||
- `LoadAction::Load` 映射为 `PRESERVE`
|
||||
- `LoadAction::Undefined` 以及默认分支映射为 `DISCARD`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetBeginningAccessType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个 getter 提供的是“描述映射结果”。当前命令列表实现并没有直接拿它去调用原生 D3D12 render pass API，而是自己根据附件描述执行清屏逻辑。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetEndingAccessType](GetEndingAccessType.md)
|
||||
- [GetColorAttachments](GetColorAttachments.md)
|
||||
|
||||
@@ -1,30 +1,18 @@
|
||||
# D3D12RenderPass::GetColorAttachmentCount
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetColorAttachmentCount() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 color attachment 数量。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetColorAttachmentCount(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 直接返回 `m_colorAttachmentCount`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetColorAttachments](GetColorAttachments.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12RenderPass::GetColorAttachments
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const AttachmentDesc* GetColorAttachments() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回内部 color attachment 描述数组的起始指针。
|
||||
|
||||
**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_colorAttachments.data()`
|
||||
- 不复制数据
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetColorAttachments(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
调用方应始终配合 [GetColorAttachmentCount](GetColorAttachmentCount.md) 使用，不要在数量为 `0` 时直接解引用这个指针。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetColorAttachmentCount](GetColorAttachmentCount.md)
|
||||
- [GetBeginningAccessType](GetBeginningAccessType.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# D3D12RenderPass::GetDepthBeginningAccessType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE GetDepthBeginningAccessType() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
把 depth-stencil attachment 的深度 `loadOp` 映射为 D3D12 的 beginning access type。
|
||||
|
||||
**返回：** `D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果没有 depth-stencil attachment，返回 `NO_ACCESS`
|
||||
- `LoadAction::Clear` 映射为 `CLEAR`
|
||||
- `LoadAction::Load` 映射为 `PRESERVE`
|
||||
- `LoadAction::Undefined` 以及默认分支映射为 `DISCARD`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetDepthBeginningAccessType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个接口只看 `m_depthStencilAttachment.loadOp`，不会把 `stencilLoadOp` 合并进返回值。如果你需要理解 stencil 的清除行为，应直接查看原始 attachment 描述或命令列表实现。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetDepthEndingAccessType](GetDepthEndingAccessType.md)
|
||||
- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# D3D12RenderPass::GetDepthEndingAccessType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_RENDER_PASS_ENDING_ACCESS_TYPE GetDepthEndingAccessType() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
把 depth-stencil attachment 的深度 `storeOp` 映射为 D3D12 的 ending access type。
|
||||
|
||||
**返回：** `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果没有 depth-stencil attachment，返回 `NO_ACCESS`
|
||||
- `StoreAction::Store` 映射为 `PRESERVE`
|
||||
- `StoreAction::Discard` 映射为 `DISCARD`
|
||||
- `StoreAction::Undefined` 以及默认分支映射为 `NO_ACCESS`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetDepthEndingAccessType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
和 [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md) 一样，这里只看深度 `storeOp`，不会把 `stencilStoreOp` 纳入返回值。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md)
|
||||
- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12RenderPass::GetDepthStencilAttachment
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const AttachmentDesc* GetDepthStencilAttachment() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 depth-stencil attachment 描述。
|
||||
|
||||
**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetDepthStencilAttachment(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果 `m_hasDepthStencil` 为 `true`，返回 `&m_depthStencilAttachment`
|
||||
- 否则返回 `nullptr`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetDepthBeginningAccessType](GetDepthBeginningAccessType.md)
|
||||
- [GetDepthEndingAccessType](GetDepthEndingAccessType.md)
|
||||
|
||||
@@ -1,31 +1,27 @@
|
||||
# D3D12RenderPass::GetEndingAccessType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_RENDER_PASS_ENDING_ACCESS_TYPE GetEndingAccessType(uint32_t index) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `index` - 参数语义详见头文件声明。
|
||||
把指定 color attachment 的 `StoreAction` 映射为 D3D12 的 ending access type。
|
||||
|
||||
**返回：** `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 越界时返回 `D3D12_RENDER_PASS_ENDING_ACCESS_TYPE_NO_ACCESS`
|
||||
- `StoreAction::Store` 映射为 `PRESERVE`
|
||||
- `StoreAction::Discard` 映射为 `DISCARD`
|
||||
- `StoreAction::Resolve` 映射为 `RESOLVE`
|
||||
- `StoreAction::StoreAndResolve` 当前也映射为 `RESOLVE`
|
||||
- `StoreAction::Undefined` 以及默认分支映射为 `NO_ACCESS`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetEndingAccessType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
`StoreAndResolve` 在当前接口里丢失了“同时保留与 resolve”的细粒度语义，因为这里返回的只是 access type，而不是完整 resolve 参数结构。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetBeginningAccessType](GetBeginningAccessType.md)
|
||||
- [D3D12RenderPass](D3D12RenderPass.md)
|
||||
|
||||
@@ -1,30 +1,22 @@
|
||||
# D3D12RenderPass::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 render pass 的原生句柄表示。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 始终返回 `nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这说明当前 `D3D12RenderPass` 只是引擎元数据对象，不对应可返回的原生 D3D12 render pass 句柄。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [D3D12RenderPass](D3D12RenderPass.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,33 +1,35 @@
|
||||
# D3D12RenderPass::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool Initialize(uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) override;
|
||||
bool Initialize(uint32_t colorAttachmentCount,
|
||||
const AttachmentDesc* colorAttachments,
|
||||
const AttachmentDesc* depthStencilAttachment) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `colorAttachmentCount` - 参数语义详见头文件声明。
|
||||
- `colorAttachments` - 参数语义详见头文件声明。
|
||||
- `depthStencilAttachment` - 参数语义详见头文件声明。
|
||||
复制 render pass 所需的 attachment 描述。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 把 `colorAttachmentCount` 写入 `m_colorAttachmentCount`
|
||||
- 调整 `m_colorAttachments` 大小并逐项复制 `colorAttachments`
|
||||
- 如果 `depthStencilAttachment` 非空，则复制它并把 `m_hasDepthStencil` 设为 `true`
|
||||
- 如果 `depthStencilAttachment` 为空，则只把 `m_hasDepthStencil` 设为 `false`
|
||||
- 始终返回 `true`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 当前限制
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 不检查 `colorAttachments` 是否为空
|
||||
- 不检查格式、采样数或 load/store 组合是否合法
|
||||
- 不创建任何原生 D3D12 对象
|
||||
|
||||
## 设计说明
|
||||
|
||||
这一步本质上是“保存一份附件策略描述”。真正的 clear / bind 行为要到命令列表阶段才会发生。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetColorAttachments](GetColorAttachments.md)
|
||||
- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
|
||||
- [GetBeginningAccessType](GetBeginningAccessType.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12RenderPass::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12RenderPass.h`，当前页面用于固定 `D3D12RenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
清空 render pass 内部缓存的 attachment 描述。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 清空 `m_colorAttachments`
|
||||
- 把 `m_colorAttachmentCount` 设为 `0`
|
||||
- 把 `m_hasDepthStencil` 设为 `false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12RenderPass.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12RenderPass object;
|
||||
// 根据上下文补齐参数后调用 D3D12RenderPass::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
当前实现没有显式把 `m_depthStencilAttachment` 复位为默认值，但由于 `m_hasDepthStencil` 会被清为 `false`，外部通过 [GetDepthStencilAttachment](GetDepthStencilAttachment.md) 已无法再访问这份旧描述。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12RenderPass.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# API 文档重构状态
|
||||
|
||||
**生成时间**: `2026-03-28 00:17:57`
|
||||
**生成时间**: `2026-03-28 00:24:57`
|
||||
|
||||
**来源**: `docs/api/_tools/audit_api_docs.py`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user