XCEngine/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md

RHIDevice::CreateBuffer

命名空间: XCEngine::RHI

类型: method

头文件: XCEngine/RHI/RHIDevice.h

签名

virtual RHIBuffer* CreateBuffer(const BufferDesc& desc) = 0;

virtual RHIBuffer* CreateBuffer(
    const BufferDesc& desc,
    const void* initialData,
    size_t initialDataSize,
    ResourceStates finalState = ResourceStates::GenericRead);

作用

创建 RHIBuffer。基础重载只创建资源本体；带初始数据的重载额外负责把给定字节流写入缓冲，并把资源切换到目标状态。

默认实现语义

抽象基类只把第一种重载保留为纯虚接口。第二种重载在基类里已经提供了统一默认实现，流程如下：

1. 如果没有初始数据，直接转发到 CreateBuffer(desc)。
2. 如果 initialDataSize > desc.size，返回 nullptr。
3. 创建基础缓冲。
4. 通过 RHIBuffer::SetData 写入初始数据。
5. 如果缓冲比初始数据更大，则把剩余区域补零。
6. 调用 SetState(finalState)，让返回对象带着上层期望的资源状态离开工厂。

这意味着“带初始化数据的创建”在抽象层已经成为正式契约，而不是某个后端的私有便利函数。

设计意图

这个重载的价值不是取代完整的上传系统，而是给渲染器、资源加载器和测试代码一个统一、直接的入口：

• 小型静态常量缓冲和顶点数据可以一步创建完成。
• 各后端都能保留自己的最佳实现空间。
• 上层不需要为“先建空缓冲，再手动上传”重复铺设样板逻辑。

商业引擎底层通常都会保留这种“便捷初始化路径”，因为它能降低资源引导阶段的复杂度；真正的大规模流式上传则仍然会走专门的上传器和队列系统。

后端实现差异

• D3D12Device 已经重写该重载，使用上传缓冲和拷贝命令完成初始化，而不是依赖默认的 SetData 路径。
• 其他设备实现可以继续继承默认语义，也可以在需要时重写以获得更好的性能或更严格的状态控制。

使用建议

• 适合启动期、测试、工具链或中小型静态数据。
• 不要把它当成高频 streaming API。
• 调用方仍然负责对象生命周期管理：成功返回后需要在合适时机 Shutdown() 并销毁缓冲。

相关文档

• RHIDevice
• RHIBuffer
• D3D12Device::CreateBuffer