# RHIDevice

**命名空间**: `XCEngine::RHI`

**类型**: `class (abstract)`

**头文件**: `XCEngine/RHI/RHIDevice.h`

**描述**: `RHI` 设备抽象，负责初始化后端、暴露能力信息，并作为绝大多数资源、命令与管线对象的统一创建入口。

## 角色概述

`RHIDevice` 在当前架构里承担的是“设备即工厂”的职责。渲染器不需要分别依赖 buffer 工厂、texture 工厂、pipeline 工厂和 descriptor 工厂，而是统一通过一个设备对象创建后端资源。这种做法和很多商业级引擎底层渲染架构一致，优点是上层入口集中、后端差异被压缩在实现层，代价是 `RHIDevice` 接口面会比较大。

## 为什么这样设计

- 上层渲染代码只需要依赖一套 `RHI` 入口，不必按后端分叉创建流程。
- `BufferDesc`、`TextureDesc`、`GraphicsPipelineDesc` 这些描述结构可以直接作为跨后端契约。
- 同一个创建请求可以在不同后端走不同实现细节，例如直接 CPU 写入、上传缓冲复制、延迟编译或立即创建。

这和 Unity SRP、Unreal RHI 一类设计的核心思路一致：高层描述保持统一，真正的后端差异放在设备和资源实现里消化。

## 生命周期

### 初始化

`Initialize(const RHIDeviceDesc&)` 负责建立后端上下文，并填充能力与设备信息。当前设备描述主要控制调试层、GPU 验证和适配器选择，说明引擎仍然把设备创建视为底层、工程化的初始化步骤，而不是面向最终用户的复杂配置界面。

### 关闭

`Shutdown()` 负责释放设备级状态。当前 `RHI` 仍然以显式 `Shutdown()` 为主，而不是完全依赖析构自动回收，因此调用方应把“显式关闭后再销毁对象”视为标准用法。

## 缓冲创建模型

`CreateBuffer` 现在有两种形态，且它们表达的是两种不同层级的需求：

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

### 基础重载

`CreateBuffer(const BufferDesc&)` 只负责创建资源本体，不附带初始化数据。具体放在哪种堆、初始状态是什么、后端如何实现，都由具体设备类决定。

### 带初始数据的重载

这个重载是最近补进来的便捷契约，目的是让上层可以用一条调用完成“创建 + 上传初始内容 + 进入目标状态”。基类默认实现会：

1. 在 `initialData == nullptr` 或大小为 `0` 时退化到基础重载。
2. 拒绝 `initialDataSize > desc.size` 的非法输入。
3. 先创建基础缓冲。
4. 对前半段调用 `SetData(initialData, initialDataSize)`。
5. 如果 `desc.size` 更大，则把剩余区间补零。
6. 最后把资源状态设置为 `finalState`。

这个默认实现强调的是统一语义，而不是最优性能。它适合小型静态数据、启动期资源或测试代码，不适合高频流式上传。

## 后端差异

- `D3D12Device` 对带初始数据的 `CreateBuffer` 做了专门重写，会显式创建上传缓冲、录制拷贝命令并做状态转换。
- 其他后端当前只需要满足统一契约，不一定都实现了同等级别的上传路径优化。

这正是抽象层的价值所在：上层只说“我要一个带初始内容的缓冲”，至于后端是 CPU 直写、上传队列复制还是暂时退化实现，都留给设备实现层。

## 所有权与使用约定

当前 `RHI` 仍然大量返回裸指针，调用方负责：

1. 在使用结束前调用对象自己的 `Shutdown()`。
2. 在确认资源不再被引用后显式 `delete`。

因此文档和代码都不应把这层接口描述成“天然 RAII 安全”的现代封装。它更接近商业引擎底层后端常见的显式生命周期模型。

## 公开方法

- [Initialize](Initialize.md)
- [Shutdown](Shutdown.md)
- [CreateBuffer](CreateBuffer.md)
- [CreateTexture](CreateTexture.md)
- [CreateSwapChain](CreateSwapChain.md)
- [CreateCommandList](CreateCommandList.md)
- [CreateCommandQueue](CreateCommandQueue.md)
- [CreateShader](CreateShader.md)
- [CreatePipelineState](CreatePipelineState.md)
- [CreatePipelineLayout](CreatePipelineLayout.md)
- [CreateFence](CreateFence.md)
- [CreateSampler](CreateSampler.md)
- [CreateRenderPass](CreateRenderPass.md)
- [CreateFramebuffer](CreateFramebuffer.md)
- [CreateDescriptorPool](CreateDescriptorPool.md)
- [CreateDescriptorSet](CreateDescriptorSet.md)
- [CreateVertexBufferView](CreateVertexBufferView.md)
- [CreateIndexBufferView](CreateIndexBufferView.md)
- [CreateRenderTargetView](CreateRenderTargetView.md)
- [CreateDepthStencilView](CreateDepthStencilView.md)
- [CreateShaderResourceView](CreateShaderResourceView.md)
- [CreateUnorderedAccessView](CreateUnorderedAccessView.md)
- [GetCapabilities](GetCapabilities.md)
- [GetDeviceInfo](GetDeviceInfo.md)
- [GetNativeDevice](GetNativeDevice.md)

## 相关指南

- [Devices, Queues, Command Lists, And Resource Creation](../../../_guides/RHI/Devices-Queues-CommandLists-And-Resource-Creation.md)

## 相关文档

- [当前模块](../RHI.md)
- [RHIBuffer](../RHIBuffer/RHIBuffer.md)
- [RHIFactory](../RHIFactory/RHIFactory.md)
- [RHICommandQueue](../RHICommandQueue/RHICommandQueue.md)
- [RHICommandList](../RHICommandList/RHICommandList.md)
- [RHICapabilities](../RHICapabilities/RHICapabilities.md)
- [RHITypes](../RHITypes/RHITypes.md)
- [API 总索引](../../../main.md)