refactor: reorganize docs into plan/ and add skills/
This commit is contained in:
178
docs/api/rhi/d3d12/d3d12-buffer.md
Normal file
178
docs/api/rhi/d3d12/d3d12-buffer.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# D3D12Buffer
|
||||
|
||||
DirectX 12 缓冲区的 D3D12 实现，封装了 `ID3D12Resource` (buffer 类型)。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
|
||||
```
|
||||
|
||||
## 继承关系
|
||||
|
||||
```
|
||||
RHIBuffer (interface)
|
||||
└── D3D12Buffer (implementation)
|
||||
```
|
||||
|
||||
## 公共成员函数
|
||||
|
||||
### 构造函数与析构函数
|
||||
|
||||
#### `D3D12Buffer()`
|
||||
默认构造函数。
|
||||
|
||||
#### `~D3D12Buffer() override`
|
||||
析构函数，确保调用 `Shutdown()`。
|
||||
|
||||
### 初始化
|
||||
|
||||
#### `bool Initialize(ID3D12Device* device, uint64_t size, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON, D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT)`
|
||||
创建新缓冲区。
|
||||
- `device`: D3D12 设备
|
||||
- `size`: 缓冲区大小（字节）
|
||||
- `initialState`: 初始资源状态
|
||||
- `heapType`: 堆类型 (DEFAULT, UPLOAD, READBACK)
|
||||
- 返回: 初始化是否成功
|
||||
|
||||
#### `bool InitializeFromExisting(ID3D12Resource* resource)`
|
||||
从现有 D3D12 资源初始化。
|
||||
- `resource`: 已存在的 `ID3D12Resource` 指针
|
||||
|
||||
#### `bool InitializeWithData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* data, uint64_t size, D3D12_RESOURCE_STATES finalState)`
|
||||
创建缓冲区并从内存数据初始化内容。
|
||||
- `device`: D3D12 设备
|
||||
- `commandList`: 命令列表（用于复制数据）
|
||||
- `data`: 初始数据指针
|
||||
- `size`: 数据大小
|
||||
- `finalState`: 数据复制完成后的目标状态
|
||||
|
||||
#### `void Shutdown() override`
|
||||
释放缓冲区资源。
|
||||
|
||||
### 数据操作
|
||||
|
||||
#### `void UpdateData(const void* data, uint64_t size)`
|
||||
更新缓冲区数据（需要 UPLOAD 堆类型）。
|
||||
|
||||
#### `void SetData(const void* data, size_t size, size_t offset = 0) override`
|
||||
设置缓冲区数据。
|
||||
|
||||
#### `void* Map() override`
|
||||
映射缓冲区内存到 CPU 可访问。
|
||||
|
||||
#### `void Unmap() override`
|
||||
解除缓冲区内存映射。
|
||||
|
||||
### 资源信息
|
||||
|
||||
#### `ID3D12Resource* GetResource() const`
|
||||
获取底层 `ID3D12Resource` 指针。
|
||||
|
||||
#### `D3D12_RESOURCE_DESC GetDesc() const`
|
||||
获取资源描述。
|
||||
|
||||
#### `D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const`
|
||||
获取 GPU 虚拟地址。
|
||||
|
||||
#### `uint64_t GetGPUAddress() const`
|
||||
获取 GPU 地址（等同于 `GetGPUVirtualAddress`）。
|
||||
|
||||
#### `uint64_t GetSize() const override`
|
||||
获取缓冲区大小。
|
||||
|
||||
#### `ResourceStates GetState() const`
|
||||
获取当前资源状态。
|
||||
|
||||
#### `void SetState(ResourceStates state)`
|
||||
设置资源状态。
|
||||
|
||||
### 接口实现
|
||||
|
||||
#### `void* GetNativeHandle() override { return m_resource.Get(); }`
|
||||
返回原生句柄。
|
||||
|
||||
#### `const std::string& GetName() const override`
|
||||
获取对象名称。
|
||||
|
||||
#### `void SetName(const std::string& name) override`
|
||||
设置对象名称。
|
||||
|
||||
#### `uint32_t GetStride() const override`
|
||||
获取顶点步长。
|
||||
|
||||
#### `BufferType GetBufferType() const override`
|
||||
获取缓冲区类型。
|
||||
|
||||
#### `void SetStride(uint32_t stride) override`
|
||||
设置顶点步长。
|
||||
|
||||
#### `void SetBufferType(BufferType type) override`
|
||||
设置缓冲区类型。
|
||||
|
||||
## 内部成员
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `m_resource` | `ComPtr<ID3D12Resource>` | D3D12 资源对象 |
|
||||
| `m_state` | `ResourceStates` | 当前资源状态 |
|
||||
| `m_name` | `std::string` | 对象名称 |
|
||||
| `m_stride` | `uint32_t` | 顶点步长 |
|
||||
| `m_bufferType` | `BufferType` | 缓冲区类型 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 创建顶点缓冲区
|
||||
|
||||
```cpp
|
||||
D3D12Buffer vertexBuffer;
|
||||
struct Vertex { float pos[3]; float uv[2]; };
|
||||
|
||||
if (vertexBuffer.Initialize(
|
||||
device->GetDevice(),
|
||||
sizeof(Vertex) * vertexCount,
|
||||
D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER,
|
||||
D3D12_HEAP_TYPE_DEFAULT))
|
||||
{
|
||||
vertexBuffer.SetName(L"VertexBuffer");
|
||||
vertexBuffer.SetStride(sizeof(Vertex));
|
||||
vertexBuffer.SetBufferType(BufferType::Vertex);
|
||||
}
|
||||
```
|
||||
|
||||
### 创建并初始化索引缓冲区
|
||||
|
||||
```cpp
|
||||
D3D12Buffer indexBuffer;
|
||||
uint16_t indices[] = { 0, 1, 2, ... };
|
||||
|
||||
D3D12CommandList cmdList;
|
||||
cmdList.Initialize(device->GetDevice());
|
||||
|
||||
indexBuffer.InitializeWithData(
|
||||
device->GetDevice(),
|
||||
cmdList.GetCommandList(),
|
||||
indices,
|
||||
sizeof(indices),
|
||||
D3D12_RESOURCE_STATE_INDEX_BUFFER);
|
||||
|
||||
cmdList.Close();
|
||||
```
|
||||
|
||||
### 更新 UPLOAD 缓冲区
|
||||
|
||||
```cpp
|
||||
D3D12Buffer uploadBuffer;
|
||||
uploadBuffer.Initialize(device, bufferSize, D3D12_RESOURCE_STATE_GENERIC_READ, D3D12_HEAP_TYPE_UPLOAD);
|
||||
|
||||
void* mapped = uploadBuffer.Map();
|
||||
memcpy(mapped, data, dataSize);
|
||||
uploadBuffer.Unmap();
|
||||
```
|
||||
|
||||
## 备注
|
||||
|
||||
- `D3D12_HEAP_TYPE_DEFAULT`: GPU 专用显存，适合渲染使用
|
||||
- `D3D12_HEAP_TYPE_UPLOAD`: CPU 可写 GPU 可读的堆，用于上传数据
|
||||
- `D3D12_HEAP_TYPE_READBACK`: CPU 可读 GPU 回读数据的堆
|
||||
- 创建后立即使用需注意资源状态转换
|
||||
Reference in New Issue
Block a user