XCEngine/docs/api/rhi/d3d12/d3d12-buffer.md

D3D12Buffer

DirectX 12 缓冲区的 D3D12 实现，封装了 ID3D12Resource (buffer 类型)。

头文件

#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	缓冲区类型

使用示例

创建顶点缓冲区

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);
}

创建并初始化索引缓冲区

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 缓冲区

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 回读数据的堆
• 创建后立即使用需注意资源状态转换