# D3D12 模块概览

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

**类型**: `module`

**描述**: DirectX 12 渲染硬件接口实现模块，提供与 DirectX 12 API 的完整绑定

## 概述

D3D12 模块是 XCEngine 渲染硬件接口（RHI）的 DirectX 12 后端实现。该模块封装了 DirectX 12 的核心功能，包括设备管理、命令系统、资源管理、描述符堆管理、管道状态对象等。通过 RHI 抽象层，开发者可以使用统一的 API 接口无缝切换 DirectX 12 和 OpenGL 等不同图形后端。

D3D12 模块遵循 DirectX 12 的设计理念，提供低开销的渲染命令提交机制，支持多线程命令录制、描述符堆、显式资源状态管理等现代图形 API 特性。

## 模块内容

### 设备与适配器

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12Device](d3d12-device.md) | `D3D12Device.h` | DirectX 12 设备封装，管理适配器、创建图形对象 |
| `AdapterInfo` | `D3D12Device.h` | 适配器信息结构体，包含显存、供应商等 |

### 命令系统

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12CommandQueue](d3d12-command-queue.md) | `D3D12CommandQueue.h` | 命令队列封装，提交命令列表到 GPU |
| [D3D12CommandList](d3d12-command-list.md) | `D3D12CommandList.h` | 命令列表封装，录制图形和计算命令 |

### 资源

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12Buffer](d3d12-buffer.md) | `D3D12Buffer.h` | 缓冲区资源（顶点、索引、常量等） |
| [D3D12Texture](d3d12-texture.md) | `D3D12Texture.h` | 纹理资源（1D/2D/3D/立方体） |
| [D3D12SwapChain](d3d12-swap-chain.md) | `D3D12SwapChain.h` | 交换链，管理帧缓冲 |



## 类型映射

D3D12 模块提供从 RHI 抽象类型到 DirectX 12 类型的映射函数：

| RHI 类型 | D3D12 类型 |
|----------|-------------|
| `Format` | `DXGI_FORMAT` |
| `ResourceStates` | `D3D12_RESOURCE_STATES` |
| `DescriptorHeapType` | `D3D12_DESCRIPTOR_HEAP_TYPE` |
| `CommandQueueType` | `D3D12_COMMAND_LIST_TYPE` |
| `PrimitiveTopology` | `D3D12_PRIMITIVE_TOPOLOGY` |
| `FilterMode` | `D3D12_FILTER` |
| `TextureAddressMode` | `D3D12_TEXTURE_ADDRESS_MODE` |
| `ComparisonFunc` | `D3D12_COMPARISON_FUNC` |
| `FillMode` | `D3D12_FILL_MODE` |
| `CullMode` | `D3D12_CULL_MODE` |

## 使用示例

```cpp
#include <XCEngine/RHI/D3D12/D3D12Device.h>
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
#include <XCEngine/RHI/D3D12/D3D12SwapChain.h>

using namespace XCEngine::RHI;

// 创建设备
D3D12Device device;
RHIDeviceDesc desc;
desc.enableDebugLayer = true;
desc.windowHandle = hwnd;
desc.width = 1280;
desc.height = 720;
device.Initialize(desc);

// 获取命令队列和命令列表
D3D12CommandQueue* commandQueue = device.CreateCommandQueueImpl(CommandQueueDesc{CommandQueueType::Direct, 0, 0, 0});
D3D12CommandList* commandList = device.CreateCommandListImpl(CommandListDesc{CommandQueueType::Direct, 0});

// 渲染循环
commandList->Reset();
commandList->SetRenderTargets(1, &renderTarget, nullptr);
commandList->ClearRenderTarget(renderTarget, clearColor);
commandList->DrawIndexed(indexCount, 1, 0, 0, 0);
commandList->Close();

commandQueue->ExecuteCommandListsInternal(1, &cmdList);
commandQueue->Signal(fence, frameIndex);
swapChain->Present(1, 0);

// 设备关闭
device.Shutdown();
```

## 线程安全

- **D3D12Device**: 单线程访问，由应用程序控制
- **D3D12CommandQueue**: 支持多线程命令提交
- **D3D12CommandList**: 应在单线程录制，可在多线程提交
- **D3D12Fence**: 线程安全，内部使用事件同步

## 相关文档

- [RHI 模块总览](../rhi/rhi.md) - RHI 抽象层概述