xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): refine D3D12 buffer docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-27 23:49:37 +08:00
parent 6d0a61e70d
commit d38c991688
26 changed files with 343 additions and 471 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Constructor.md
View File

@@ -1,28 +1,23 @@
# D3D12Buffer::D3D12Buffer() # D3D12Buffer::D3D12Buffer
构造对象。
```cpp ```cpp
D3D12Buffer(); D3D12Buffer();
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 构造一个空的 D3D12 缓冲区对象。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 构造函数本身没有显式逻辑。
- 依赖类内默认值:
```cpp - `m_state = ResourceStates::Common`
#include <XCEngine/RHI/D3D12/D3D12Buffer.h> - `m_name` 为空字符串
- `m_stride = 0`
void Example() { - `m_bufferType = BufferType::Vertex`
XCEngine::RHI::D3D12Buffer object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [Initialize](Initialize.md)
- [返回模块目录](../D3D12.md) - [D3D12Buffer](D3D12Buffer.md)

101
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/D3D12Buffer.md
View File

@@ -6,48 +6,77 @@
**头文件**: `XCEngine/RHI/D3D12/D3D12Buffer.h` **头文件**: `XCEngine/RHI/D3D12/D3D12Buffer.h`
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Buffer` public API。 **描述**: D3D12 后端的缓冲区资源封装，持有 `ID3D12Resource` 并附带引擎侧状态、步长、名称和缓冲类型元数据。
## 概述 ## 概览
`D3D12Buffer.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `D3D12Buffer` 和 [D3D12Texture](../D3D12Texture/D3D12Texture.md) 属于同一层级的资源包装器: 它持有一个真实的 `ID3D12Resource`，同时保存 RHI 层需要的附加元数据。
## 声明概览 在当前实现里，这个类承担两类工作:
| 声明 | 类型 | 说明 | - 创建或包装底层 D3D12 buffer resource
|------|------|------| - 为上层系统暴露 GPU 地址、步长、缓冲类型、映射接口和本地状态缓存
| `D3D12Buffer` | `class` | 继承自 `RHIBuffer` 的公开声明。 |
## 公共方法 ## 设计定位
| 方法 | 描述 | 如果从商业引擎角度看，当前 `D3D12Buffer` 的实现更偏“简单可用”而不是“峰值性能路径”:
|------|------|
| [D3D12Buffer()](Constructor.md) | 构造对象。 | - `D3D12Device::CreateBuffer()` 会把 constant / vertex / index buffer 都放到 `UPLOAD` heap
| [~D3D12Buffer()](Destructor.md) | 销毁对象并释放相关资源。 | - 这样 `SetData()` / `Map()` 使用起来简单
| [Initialize](Initialize.md) | 初始化内部状态。 | - 代价是它不像经典的“upload staging -> default heap resident buffer”方案那样追求 GPU 访问效率
| [InitializeFromExisting](InitializeFromExisting.md) | 初始化内部状态。 |
| [InitializeWithData](InitializeWithData.md) | 初始化内部状态。 | 这类设计在引擎早中期阶段很常见，但文档必须把这种取舍写明。
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
| [GetResource](GetResource.md) | 获取相关状态或对象。 | ## 生命周期
| [GetDesc](GetDesc.md) | 获取相关状态或对象。 |
| [GetGPUVirtualAddress](GetGPUVirtualAddress.md) | 获取相关状态或对象。 | - 构造后为空对象。
| [UpdateData](UpdateData.md) | 更新运行时状态。 | - 可通过 [Initialize](Initialize.md)、[InitializeFromExisting](InitializeFromExisting.md)、[InitializeWithData](InitializeWithData.md) 获得底层资源。
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | - [Shutdown](Shutdown.md) 只会 `Reset()` 掉 `m_resource`。
| [GetState](GetState.md) | 获取相关状态或对象。 | - 析构时自动调用 `Shutdown()`。
| [SetState](SetState.md) | 设置相关状态或配置。 |
| [GetGPUAddress](GetGPUAddress.md) | 获取相关状态或对象。 | ## 线程语义
| [GetSize](GetSize.md) | 获取相关状态或对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 | - 当前实现没有锁。
| [SetName](SetName.md) | 设置相关状态或配置。 | - D3D12 资源引用本身可跨线程传递，但本地元数据接口和映射写入流程不应被当作并发安全 API。
| [GetStride](GetStride.md) | 获取相关状态或对象。 |
| [GetBufferType](GetBufferType.md) | 获取相关状态或对象。 | ## 当前实现的真实行为
| [SetStride](SetStride.md) | 设置相关状态或配置。 |
| [SetBufferType](SetBufferType.md) | 设置相关状态或配置。 | - [Initialize](Initialize.md) 创建 committed buffer，但不会同步 `m_state`。
| [Map](Map.md) | 公开方法，详见头文件声明。 | - [InitializeFromExisting](InitializeFromExisting.md) 即使传入 `nullptr` 也返回 `true`。
| [Unmap](Unmap.md) | 公开方法，详见头文件声明。 | - [InitializeWithData](InitializeWithData.md) 会录制上传和 barrier，但不会更新 `m_state`。
| [SetData](SetData.md) | 设置相关状态或配置。 | - [Shutdown](Shutdown.md) 只重置 `m_resource`，不会清空 `m_state`、`m_name`、`m_stride`、`m_bufferType`。
- [GetDesc](GetDesc.md)、[GetGPUVirtualAddress](GetGPUVirtualAddress.md)、[GetGPUAddress](GetGPUAddress.md)、[GetSize](GetSize.md) 都会直接或间接解引用 `m_resource`，因此在资源为空时并不安全。
## 为什么这样设计
当前实现显然优先照顾了“让 RHI 层和测试先跑起来”的目标:
- CPU 可写的 upload buffer 很容易和 `SetData()` 配合
- `GetGPUVirtualAddress()` 又足够支持 CBV / VBV / IBV 视图创建
对用户来说，关键理解是:
- 这不是最终形态的高性能 D3D12 缓冲管理系统
- 它更像一个对统一 RHI 友好的、相对直接的资源封装层
## 当前限制
- 多个 getter 在 `m_resource == nullptr` 时不安全。
- 状态缓存依赖外部调用者维护。
- `InitializeWithData()` 内部临时上传资源当前没有在函数尾部显式释放。
- `SetName()` 只写本地字符串，不会把名称传给 D3D12 调试对象。
## 关键方法
- [Initialize](Initialize.md)
- [InitializeWithData](InitializeWithData.md)
- [Map](Map.md)
- [SetData](SetData.md)
- [GetGPUVirtualAddress](GetGPUVirtualAddress.md)
- [Shutdown](Shutdown.md)
## 相关文档 ## 相关文档
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 - [D3D12](../D3D12.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [D3D12Texture](../D3D12Texture/D3D12Texture.md)
- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Destructor.md
View File

@@ -1,29 +1,19 @@
# D3D12Buffer::~D3D12Buffer() # D3D12Buffer::~D3D12Buffer
销毁对象并释放相关资源。
```cpp ```cpp
~D3D12Buffer() override; ~D3D12Buffer() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 销毁对象并释放内部 `ID3D12Resource` 引用。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 析构函数内部调用 [Shutdown](Shutdown.md)。
- 只重置 `m_resource`，不额外清理本地元数据。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 对象离开作用域时会自动触发析构。
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [Shutdown](Shutdown.md)
- [返回模块目录](../D3D12.md) - [GetState](GetState.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetBufferType.md
View File

@@ -1,30 +1,20 @@
# D3D12Buffer::GetBufferType # D3D12Buffer::GetBufferType
获取相关状态或对象。
```cpp ```cpp
BufferType GetBufferType() const override; BufferType GetBufferType() const override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回该缓冲区记录的逻辑类型。
**返回：** `BufferType` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接返回缓存的 `m_bufferType`。
- 构造默认值是 `BufferType::Vertex`。
```cpp - `D3D12Device::CreateBuffer()` 会在创建成功后显式调用 [SetBufferType](SetBufferType.md)。
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetBufferType(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [SetBufferType](SetBufferType.md)
- [返回模块目录](../D3D12.md) - [Initialize](Initialize.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetDesc.md
View File

@@ -1,30 +1,24 @@
# D3D12Buffer::GetDesc # D3D12Buffer::GetDesc
获取相关状态或对象。
```cpp ```cpp
D3D12_RESOURCE_DESC GetDesc() const; D3D12_RESOURCE_DESC GetDesc() const;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回底层缓冲资源描述。
**返回：** `D3D12_RESOURCE_DESC` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接调用 `m_resource->GetDesc()`。
- 没有空指针保护。
```cpp ## 使用建议
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 仅在资源已初始化时调用。
XCEngine::RHI::D3D12Buffer object; - 如果对象可能已经 `Shutdown()`，应先通过 [GetResource](GetResource.md) 判空。
// 根据上下文补齐参数后调用 D3D12Buffer::GetDesc(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetResource](GetResource.md)
- [返回模块目录](../D3D12.md) - [GetSize](GetSize.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUAddress.md
View File

@@ -1,30 +1,20 @@
# D3D12Buffer::GetGPUAddress # D3D12Buffer::GetGPUAddress
获取相关状态或对象。
```cpp ```cpp
uint64_t GetGPUAddress() const; uint64_t GetGPUAddress() const;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 以 `uint64_t` 形式返回底层 GPU 虚拟地址。
**返回：** `uint64_t` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接返回 `m_resource->GetGPUVirtualAddress()`。
- 没有空指针保护。
```cpp - 其语义与 [GetGPUVirtualAddress](GetGPUVirtualAddress.md) 相同，只是返回类型更通用。
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetGPUAddress(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetGPUVirtualAddress](GetGPUVirtualAddress.md)
- [返回模块目录](../D3D12.md) - [GetNativeHandle](GetNativeHandle.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUVirtualAddress.md
View File

@@ -1,30 +1,20 @@
# D3D12Buffer::GetGPUVirtualAddress # D3D12Buffer::GetGPUVirtualAddress
获取相关状态或对象。
```cpp ```cpp
D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const; D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回底层缓冲区的 D3D12 GPU 虚拟地址。
**返回：** `D3D12_GPU_VIRTUAL_ADDRESS` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接调用 `m_resource->GetGPUVirtualAddress()`。
- 当前多个后端实现会用它创建 CBV / VBV / IBV 或设置绘制视图。
```cpp - 没有空指针保护。
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetGPUVirtualAddress(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetGPUAddress](GetGPUAddress.md)
- [返回模块目录](../D3D12.md) - [GetResource](GetResource.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetName.md
View File

@@ -1,30 +1,19 @@
# D3D12Buffer::GetName # D3D12Buffer::GetName
获取相关状态或对象。
```cpp ```cpp
const std::string& GetName() const override; const std::string& GetName() const override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回该缓冲区的引擎侧名称。
**返回：** `const std::string&` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接返回 `m_name`。
- [Shutdown](Shutdown.md) 不会清空该字段。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetName(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [SetName](SetName.md)
- [返回模块目录](../D3D12.md) - [Shutdown](Shutdown.md)

24
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetNativeHandle.md
View File

@@ -1,30 +1,18 @@
# D3D12Buffer::GetNativeHandle # D3D12Buffer::GetNativeHandle
获取相关状态或对象。
```cpp ```cpp
void* GetNativeHandle() override; void* GetNativeHandle() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回底层原生缓冲资源指针。
**返回：** `void*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 直接返回 `m_resource.Get()`。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetNativeHandle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetResource](GetResource.md)
- [返回模块目录](../D3D12.md) - [GetGPUVirtualAddress](GetGPUVirtualAddress.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetResource.md
View File

@@ -1,30 +1,19 @@
# D3D12Buffer::GetResource # D3D12Buffer::GetResource
获取相关状态或对象。
```cpp ```cpp
ID3D12Resource* GetResource() const; ID3D12Resource* GetResource() const;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回底层 `ID3D12Resource*`。
**返回：** `ID3D12Resource*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 已初始化时返回有效指针。
- 否则返回 `nullptr`。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetResource(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetDesc](GetDesc.md)
- [返回模块目录](../D3D12.md) - [GetNativeHandle](GetNativeHandle.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetSize.md
View File

@@ -1,30 +1,19 @@
# D3D12Buffer::GetSize # D3D12Buffer::GetSize
获取相关状态或对象。
```cpp ```cpp
uint64_t GetSize() const override; uint64_t GetSize() const override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回缓冲区大小。
**返回：** `uint64_t` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 实际实现是 `GetDesc().Width`。
- 因为 [GetDesc](GetDesc.md) 没有空指针保护，所以该接口在资源为空时也不安全。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetSize(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetDesc](GetDesc.md)
- [返回模块目录](../D3D12.md) - [Initialize](Initialize.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetState.md
View File

@@ -1,30 +1,24 @@
# D3D12Buffer::GetState # D3D12Buffer::GetState
获取相关状态或对象。
```cpp ```cpp
ResourceStates GetState() const; ResourceStates GetState() const;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回引擎侧缓存的资源状态。
**返回：** `ResourceStates` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接返回 `m_state`。
- 初始化函数通常不会自动同步它。
```cpp ## 使用建议
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 不应把该返回值直接等同于底层 D3D12 资源的真实状态。
XCEngine::RHI::D3D12Buffer object; - 如果你手工做了 barrier 或通过特殊初始化路径创建资源，通常还需要显式 [SetState](SetState.md)。
// 根据上下文补齐参数后调用 D3D12Buffer::GetState(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [SetState](SetState.md)
- [返回模块目录](../D3D12.md) - [InitializeWithData](InitializeWithData.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetStride.md
View File

@@ -1,30 +1,19 @@
# D3D12Buffer::GetStride # D3D12Buffer::GetStride
获取相关状态或对象。
```cpp ```cpp
uint32_t GetStride() const override; uint32_t GetStride() const override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回该缓冲区记录的元素步长。
**返回：** `uint32_t` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接返回 `m_stride`。
- 设备工厂会在创建成功后调用 [SetStride](SetStride.md)。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::GetStride(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [SetStride](SetStride.md)
- [返回模块目录](../D3D12.md) - [GetBufferType](GetBufferType.md)

55
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Initialize.md
View File

@@ -1,34 +1,47 @@
# D3D12Buffer::Initialize # D3D12Buffer::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(ID3D12Device* device, uint64_t size, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON, D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT); bool Initialize(
ID3D12Device* device,
uint64_t size,
D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON,
D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建一个 committed buffer resource。
- `device` - 参数语义详见头文件声明。
- `size` - 参数语义详见头文件声明。
- `initialState` - 参数语义详见头文件声明。
- `heapType` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 参数说明
**示例：** - `device`: D3D12 设备。
- `size`: 缓冲区大小，单位为字节。
- `initialState`: 创建时的底层资源状态。
- `heapType`: 使用的堆类型。
```cpp ## 返回值
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - `CreateCommittedResource()` 成功时返回 `true`。
XCEngine::RHI::D3D12Buffer object; - 失败时返回 `false`。
// 根据上下文补齐参数后调用 D3D12Buffer::Initialize(...)。
(void)object; ## 当前实现行为
}
``` - 构造一个 `D3D12_RESOURCE_DIMENSION_BUFFER` 描述。
- 使用 `bufferDesc.Width = size`。
- `Layout` 固定为 `D3D12_TEXTURE_LAYOUT_ROW_MAJOR`。
- `Flags` 固定为 `D3D12_RESOURCE_FLAG_NONE`。
- 调用 `CreateCommittedResource()` 创建资源。
- 创建成功后不会同步:
- `m_state`
- `m_stride`
- `m_bufferType`
## 设计说明
- 当前工厂层会在外部再补写步长和类型。
- 这说明初始化函数负责“创建资源”，而对象元数据完整性依赖更高层调用者。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [SetStride](SetStride.md)
- [返回模块目录](../D3D12.md) - [SetBufferType](SetBufferType.md)

35
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeFromExisting.md
View File

@@ -1,31 +1,32 @@
# D3D12Buffer::InitializeFromExisting # D3D12Buffer::InitializeFromExisting
初始化内部状态。
```cpp ```cpp
bool InitializeFromExisting(ID3D12Resource* resource); bool InitializeFromExisting(ID3D12Resource* resource);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 用一个已有的 `ID3D12Resource` 包装当前对象。
- `resource` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 当前实现始终返回 `true`，即使 `resource == nullptr`。
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 仅把 `resource` 赋给内部 `ComPtr`。
XCEngine::RHI::D3D12Buffer object; - 不会推导或更新:
// 根据上下文补齐参数后调用 D3D12Buffer::InitializeFromExisting(...)。 - `m_state`
(void)object; - `m_stride`
} - `m_bufferType`
``` - `m_name`
## 使用建议
- 调用后应自行验证 [GetResource](GetResource.md) 是否为空。
- 如果上层需要正确的类型和步长元数据，应显式调用 [SetStride](SetStride.md) / [SetBufferType](SetBufferType.md)。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetResource](GetResource.md)
- [返回模块目录](../D3D12.md) - [SetBufferType](SetBufferType.md)

52
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeWithData.md
View File

@@ -1,35 +1,43 @@
# D3D12Buffer::InitializeWithData # D3D12Buffer::InitializeWithData
初始化内部状态。
```cpp ```cpp
bool InitializeWithData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* data, uint64_t size, D3D12_RESOURCE_STATES finalState); bool InitializeWithData(
ID3D12Device* device,
ID3D12GraphicsCommandList* commandList,
const void* data,
uint64_t size,
D3D12_RESOURCE_STATES finalState);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建一个带初始数据的默认堆缓冲区，并录制上传拷贝命令。
- `device` - 参数语义详见头文件声明。
- `commandList` - 参数语义详见头文件声明。
- `data` - 参数语义详见头文件声明。
- `size` - 参数语义详见头文件声明。
- `finalState` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 前置条件
**示例：** - `device`、`commandList` 和 `data` 必须有效。
```cpp ## 返回值
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 资源创建和命令录制成功时返回 `true`。
XCEngine::RHI::D3D12Buffer object; - 任一步骤失败时返回 `false`。
// 根据上下文补齐参数后调用 D3D12Buffer::InitializeWithData(...)。
(void)object; ## 当前实现行为
}
``` - 创建一个默认堆 buffer，初始状态为 `COPY_DEST`。
- 通过 `GetCopyableFootprints()` 计算拷贝 footprint。
- 再创建一个 upload heap 临时缓冲。
- 把 `data` 全量复制到该上传缓冲。
- 录制 `CopyBufferRegion()`。
- 录制从 `COPY_DEST` 到 `finalState` 的 transition barrier。
## 重要限制
- 当前函数不会把 `m_state` 更新为 `finalState`。
- 函数内部创建的临时上传资源当前使用原始指针保存，并没有在函数尾部显式释放。
- 该函数只负责录制命令，不负责提交命令列表或等待 GPU 完成。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetState](GetState.md)
- [返回模块目录](../D3D12.md) - [SetState](SetState.md)

28
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Map.md
View File

@@ -1,30 +1,26 @@
# D3D12Buffer::Map # D3D12Buffer::Map
公开方法，详见头文件声明。
```cpp ```cpp
void* Map() override; void* Map() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 映射底层缓冲区并返回 CPU 指针。
**返回：** `void*` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 构造 `D3D12_RANGE readRange = { 0, 0 }`。
- 调用 `m_resource->Map(0, &readRange, &data)`。
- 返回映射得到的指针。
- 不检查 `Map()` 的 `HRESULT`。
```cpp ## 使用建议
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 该接口更适合 upload / readback heap 资源。
XCEngine::RHI::D3D12Buffer object; - 如果底层资源不可映射，当前实现不会提供错误信息，返回指针可能为空。
// 根据上下文补齐参数后调用 D3D12Buffer::Map(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [Unmap](Unmap.md)
- [返回模块目录](../D3D12.md) - [SetData](SetData.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetBufferType.md
View File

@@ -1,31 +1,19 @@
# D3D12Buffer::SetBufferType # D3D12Buffer::SetBufferType
设置相关状态或配置。
```cpp ```cpp
void SetBufferType(BufferType type) override; void SetBufferType(BufferType type) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 设置该缓冲区的逻辑类型元数据。
- `type` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接把 `m_bufferType` 设为传入值。
- 不会修改底层资源本身。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::SetBufferType(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetBufferType](GetBufferType.md)
- [返回模块目录](../D3D12.md) - [Initialize](Initialize.md)

38
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetData.md
View File

@@ -1,33 +1,33 @@
# D3D12Buffer::SetData # D3D12Buffer::SetData
设置相关状态或配置。
```cpp ```cpp
void SetData(const void* data, size_t size, size_t offset = 0) override; void SetData(const void* data, size_t size, size_t offset = 0) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一段 CPU 数据写入当前缓冲区指定偏移处。
- `data` - 参数语义详见头文件声明。
- `size` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数说明
**示例：** - `data`: 源数据指针。
- `size`: 写入字节数。
- `offset`: 写入偏移。
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 构造 `D3D12_RANGE writeRange = { offset, offset + size }`。
XCEngine::RHI::D3D12Buffer object; - 调用 `Map()` 获取底层指针。
// 根据上下文补齐参数后调用 D3D12Buffer::SetData(...)。 - 执行 `memcpy(pBuffer + offset, data, size)`。
(void)object; - 调用 `Unmap()`。
}
``` ## 重要限制
- 没有越界检查。
- 没有检查 `Map()` 是否成功。
- 对默认堆资源直接调用该接口并不可靠；当前实现更适合 CPU 可见堆。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [Map](Map.md)
- [返回模块目录](../D3D12.md) - [UpdateData](UpdateData.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetName.md
View File

@@ -1,31 +1,19 @@
# D3D12Buffer::SetName # D3D12Buffer::SetName
设置相关状态或配置。
```cpp ```cpp
void SetName(const std::string& name) override; void SetName(const std::string& name) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 设置该缓冲区的引擎侧名称。
- `name` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 仅把名称保存到 `m_name`。
- 不会调用 `ID3D12Object::SetName()`。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::SetName(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetName](GetName.md)
- [返回模块目录](../D3D12.md) - [D3D12Buffer](D3D12Buffer.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetState.md
View File

@@ -1,31 +1,19 @@
# D3D12Buffer::SetState # D3D12Buffer::SetState
设置相关状态或配置。
```cpp ```cpp
void SetState(ResourceStates state); void SetState(ResourceStates state);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 手工同步引擎侧缓存的资源状态。
- `state` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接写入 `m_state`。
- 不会自动插入 D3D12 barrier。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::SetState(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetState](GetState.md)
- [返回模块目录](../D3D12.md) - [InitializeWithData](InitializeWithData.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetStride.md
View File

@@ -1,31 +1,19 @@
# D3D12Buffer::SetStride # D3D12Buffer::SetStride
设置相关状态或配置。
```cpp ```cpp
void SetStride(uint32_t stride) override; void SetStride(uint32_t stride) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 设置缓冲区元素步长元数据。
- `stride` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接写入 `m_stride`。
- 不会验证该步长是否与真实数据布局一致。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::SetStride(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [GetStride](GetStride.md)
- [返回模块目录](../D3D12.md) - [GetBufferType](GetBufferType.md)

29
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Shutdown.md
View File

@@ -1,30 +1,27 @@
# D3D12Buffer::Shutdown # D3D12Buffer::Shutdown
关闭并清理内部状态。
```cpp ```cpp
void Shutdown() override; void Shutdown() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 释放内部 `ID3D12Resource` 引用。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 仅调用 `m_resource.Reset()`。
- 不会重置:
- `m_state`
- `m_name`
- `m_stride`
- `m_bufferType`
```cpp ## 使用建议
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - `Shutdown()` 后不要继续调用 [GetDesc](GetDesc.md)、[GetSize](GetSize.md)、[GetGPUVirtualAddress](GetGPUVirtualAddress.md) 这类依赖 `m_resource` 的接口。
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::Shutdown(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [Destructor](Destructor.md)
- [返回模块目录](../D3D12.md) - [GetResource](GetResource.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Unmap.md
View File

@@ -1,30 +1,19 @@
# D3D12Buffer::Unmap # D3D12Buffer::Unmap
公开方法，详见头文件声明。
```cpp ```cpp
void Unmap() override; void Unmap() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 结束当前缓冲区映射。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接调用 `m_resource->Unmap(0, nullptr)`。
- 不检查 `m_resource` 是否为空。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() {
XCEngine::RHI::D3D12Buffer object;
// 根据上下文补齐参数后调用 D3D12Buffer::Unmap(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [Map](Map.md)
- [返回模块目录](../D3D12.md) - [SetData](SetData.md)

36
docs/api/XCEngine/RHI/D3D12/D3D12Buffer/UpdateData.md
View File

@@ -1,32 +1,32 @@
# D3D12Buffer::UpdateData # D3D12Buffer::UpdateData
更新运行时状态。
```cpp ```cpp
void UpdateData(const void* data, uint64_t size); void UpdateData(const void* data, uint64_t size);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一段数据覆盖写入缓冲区起始位置。
- `data` - 参数语义详见头文件声明。
- `size` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数说明
**示例：** - `data`: 源数据指针。
- `size`: 写入字节数。
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
void Example() { - 构造 `D3D12_RANGE range = { 0, size }`。
XCEngine::RHI::D3D12Buffer object; - 调用 `Map()` 获取指针。
// 根据上下文补齐参数后调用 D3D12Buffer::UpdateData(...)。 - 执行 `memcpy(pBuffer, data, size)`。
(void)object; - 调用 `Unmap()`。
}
``` ## 重要限制
- 没有检查映射是否成功。
- 不适合对不可 CPU 写入的堆类型使用。
- 该接口总是从偏移 `0` 开始写入，无法指定任意目标偏移。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Buffer.md) - [SetData](SetData.md)
- [返回模块目录](../D3D12.md) - [Map](Map.md)

2
docs/api/_meta/rebuild-status.md
View File

@@ -1,6 +1,6 @@
# API 文档重构状态 # API 文档重构状态
**生成时间**: `2026-03-27 23:42:53` **生成时间**: `2026-03-27 23:48:52`
**来源**: `docs/api/_tools/audit_api_docs.py` **来源**: `docs/api/_tools/audit_api_docs.py`