XCEngine/docs/api/d3d12/d3d12.md

# 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` | 命令列表封装，录制图形和计算命令 |
| [D3D12CommandAllocator](d3d12-command-allocator.md) | `D3D12CommandAllocator.h` | 命令分配器，管理命令列表内存 |

### 同步与查询

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12Fence](d3d12-fence.md) | `D3D12Fence.h` | GPU/CPU 同步围栏 |
| [D3D12QueryHeap](d3d12-query-heap.md) | `D3D12QueryHeap.h` | 查询堆，用于性能计数器和遮挡查询 |

### 资源

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

### 渲染状态

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12Shader](d3d12-shader.md) | `D3D12Shader.h` | 着色器编译与管理 |
| [D3D12PipelineState](d3d12-pipeline-state.md) | `D3D12PipelineState.h` | 图形管道状态对象 |
| [D3D12RootSignature](d3d12-root-signature.md) | `D3D12RootSignature.h` | 根签名，定义着色器参数布局 |

### 描述符与视图

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12DescriptorHeap](d3d12-descriptor-heap.md) | `D3D12DescriptorHeap.h` | 描述符堆，管理渲染目标、深度模板、SRV、UAV 等 |
| [D3D12Sampler](d3d12-sampler.md) | `D3D12Sampler.h` | 采样器状态 |
| [D3D12RenderTargetView](d3d12-render-target-view.md) | `D3D12RenderTargetView.h` | 渲染目标视图 |
| [D3D12DepthStencilView](d3d12-depth-stencil-view.md) | `D3D12DepthStencilView.h` | 深度模板视图 |
| [D3D12ShaderResourceView](d3d12-shader-resource-view.md) | `D3D12ShaderResourceView.h` | 着色器资源视图 |
| [D3D12UnorderedAccessView](d3d12-unordered-access-view.md) | `D3D12UnorderedAccessView.md` | 无序访问视图 |
| [D3D12ConstantBufferView](d3d12-constant-buffer-view.md) | `D3D12ConstantBufferView.md` | 常量缓冲区视图 |

### 工具

| 组件 | 文件 | 描述 |
|------|------|------|
| [D3D12Screenshot](d3d12-screenshot.md) | `D3D12Screenshot.h` | 截图工具 |
| [D3D12Common](d3d12-common.md) | `D3D12Common.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 模块总览](../module.md) - RHI 抽象层概述
- [RHIEnums](../rhi-enums.md) - RHI 枚举定义
- [RHITypes](../rhi-types.md) - RHI 类型定义
- [D3D12 后端测试设计](../../plan/D3D12后端测试设计.md) - D3D12 测试设计文档