xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Add D3D12 API documentation

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 19:43:28 +08:00
parent 05a57addc7
commit 60d11f3109
41 changed files with 1073 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/api/d3d12/d3d12-buffer.md Normal file
View File

@@ -0,0 +1,38 @@
# D3D12Buffer
**命名空间**: `XCEngine::RHI`
**类型**: `class`
**头文件**: `XCEngine/RHI/D3D12/D3D12Buffer.h`
**描述**: DirectX 12 缓冲区资源封装类，支持顶点、索引、常量等类型的缓冲区
## 概述
D3D12Buffer 是 DirectX 12 缓冲区资源的封装类，继承自 RHIBuffer 接口。支持多种缓冲区类型，包括顶点缓冲区、索引缓冲区、常量缓冲区等。提供了内存映射接口以支持 CPU 端数据更新。
## 公共方法
| 方法 | 描述 |
|------|------|
| `D3D12Buffer()` | 默认构造函数 |
| `~D3D12Buffer()` | 虚析构函数 |
| [Initialize](d3d12-buffer-initialize.md) | 初始化缓冲区 |
| [InitializeFromExisting](d3d12-buffer-initialize-from-existing.md) | 从现有资源初始化 |
| [InitializeWithData](d3d12-buffer-initialize-with-data.md) | 初始化并上传数据 |
| [Shutdown](d3d12-buffer-shutdown.md) | 关闭缓冲区 |
| [GetResource](d3d12-buffer-get-resource.md) | 获取底层资源指针 |
| [GetDesc](d3d12-buffer-get-desc.md) | 获取资源描述 |
| [GetGPUVirtualAddress](d3d12-buffer-get-gpu-virtual-address.md) | 获取 GPU 虚拟地址 |
| [UpdateData](d3d12-buffer-update-data.md) | 更新数据 |
| [GetState](d3d12-buffer-get-state.md) | 获取资源状态 |
| [SetState](d3d12-buffer-set-state.md) | 设置资源状态 |
| [Map](d3d12-buffer-map.md) | 映射内存 |
| [Unmap](d3d12-buffer-unmap.md) | 取消映射 |
| [SetData](d3d12-buffer-set-data.md) | 设置数据 |
## 相关文档
- [D3D12 模块概览](d3d12.md) - D3D12 模块总览
- [RHIBuffer](../rhi-buffer.md) - RHI 缓冲区基类

16
docs/api/d3d12/d3d12-command-list-clear-depth-stencil.md Normal file
View File

@@ -0,0 +1,16 @@
# D3D12CommandList::ClearDepthStencil
清除深度模板缓冲区。
```cpp
void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) override;
```
**参数：**
- `depthStencil` - 深度模板目标指针
- `depth` - 深度值
- `stencil` - 模板值
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

15
docs/api/d3d12/d3d12-command-list-clear-render-target.md Normal file
View File

@@ -0,0 +1,15 @@
# D3D12CommandList::ClearRenderTarget
清除渲染目标。
```cpp
void ClearRenderTarget(void* renderTarget, const float color[4]) override;
```
**参数：**
- `renderTarget` - 渲染目标指针
- `color` - 清除颜色 RGBA
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

13
docs/api/d3d12/d3d12-command-list-close.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12CommandList::Close
关闭命令列表，结束录制。
```cpp
void Close() override;
```
关闭命令列表后不能再录制命令，可以提交到命令队列执行。
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

15
docs/api/d3d12/d3d12-command-list-copy-resource.md Normal file
View File

@@ -0,0 +1,15 @@
# D3D12CommandList::CopyResource
复制资源。
```cpp
void CopyResource(void* dst, void* src) override;
```
**参数：**
- `dst` - 目标资源指针
- `src` - 源资源指针
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

16
docs/api/d3d12/d3d12-command-list-dispatch.md Normal file
View File

@@ -0,0 +1,16 @@
# D3D12CommandList::Dispatch
分发计算任务。
```cpp
void Dispatch(uint32_t x, uint32_t y, uint32_t z) override;
```
**参数：**
- `x` - X 方向线程组数量
- `y` - Y 方向线程组数量
- `z` - Z 方向线程组数量
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

18
docs/api/d3d12/d3d12-command-list-draw-indexed.md Normal file
View File

@@ -0,0 +1,18 @@
# D3D12CommandList::DrawIndexed
绘制索引图元。
```cpp
void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) override;
```
**参数：**
- `indexCount` - 索引数量
- `instanceCount` - 实例数量，默认为 1
- `startIndex` - 起始索引位置
- `baseVertex` - 基础顶点位置
- `startInstance` - 起始实例位置
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

17
docs/api/d3d12/d3d12-command-list-draw.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12CommandList::Draw
绘制调用。
```cpp
void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) override;
```
**参数：**
- `vertexCount` - 顶点数量
- `instanceCount` - 实例数量，默认为 1
- `startVertex` - 起始顶点位置
- `startInstance` - 起始实例位置
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

18
docs/api/d3d12/d3d12-command-list-initialize.md Normal file
View File

@@ -0,0 +1,18 @@
# D3D12CommandList::Initialize
初始化命令列表。
```cpp
bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct, ID3D12CommandAllocator* allocator = nullptr);
```
**参数：**
- `device` - DirectX 12 设备指针
- `type` - 命令队列类型，默认为 Direct
- `allocator` - 可选的命令分配器
**返回：** `bool` - 初始化成功返回 true
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

13
docs/api/d3d12/d3d12-command-list-reset.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12CommandList::Reset
重置命令列表以重新录制命令。
```cpp
void Reset() override;
```
将命令列表重置到初始状态，可重新录制命令。通常与 Close 配合使用实现命令列表重用。
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

16
docs/api/d3d12/d3d12-command-list-set-render-targets.md Normal file
View File

@@ -0,0 +1,16 @@
# D3D12CommandList::SetRenderTargets
设置渲染目标。
```cpp
void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) override;
```
**参数：**
- `count` - 渲染目标数量
- `renderTargets` - 渲染目标指针数组
- `depthStencil` - 可选的深度模板目标
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

11
docs/api/d3d12/d3d12-command-list-shutdown.md Normal file
View File

@@ -0,0 +1,11 @@
# D3D12CommandList::Shutdown
关闭命令列表并释放资源。
```cpp
void Shutdown() override;
```
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

18
docs/api/d3d12/d3d12-command-list-transition-barrier.md Normal file
View File

@@ -0,0 +1,18 @@
# D3D12CommandList::TransitionBarrier
设置资源状态转换屏障。
```cpp
void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) override;
```
**参数：**
- `resource` - 目标资源指针
- `stateBefore` - 转换前的资源状态
- `stateAfter` - 转换后的资源状态
**线程安全：** ❌ 非线程安全，应在单线程中调用
## 相关文档
- [D3D12CommandList 总览](d3d12-command-list.md)

112
docs/api/d3d12/d3d12-command-list.md Normal file
View File

@@ -0,0 +1,112 @@
# D3D12CommandList
**命名空间**: `XCEngine::RHI`
**类型**: `class`
**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h`
**描述**: DirectX 12 命令列表封装类，负责录制图形和计算命令
## 概述
D3D12CommandList 是 DirectX 12 命令列表的封装类，继承自 RHICommandList 接口。它负责录制所有图形渲染命令，包括状态设置、绘制调用、资源状态转换、复制操作等。D3D12CommandList 支持命令列表重置和关闭以实现命令重用，内部维护资源状态跟踪以优化状态转换屏障。
该类是渲染管线的核心，负责将所有渲染操作命令化并提交到 GPU 执行。
## 公共方法
| 方法 | 描述 |
|------|------|
| `D3D12CommandList()` | 默认构造函数 |
| `~D3D12CommandList()` | 虚析构函数 |
| [Initialize](d3d12-command-list-initialize.md) | 初始化命令列表 |
| [Shutdown](d3d12-command-list-shutdown.md) | 关闭命令列表 |
| [Reset](d3d12-command-list-reset.md) | 重置命令列表 |
| [Close](d3d12-command-list-close.md) | 关闭命令列表 |
| [GetCommandList](d3d12-command-list-get-command-list.md) | 获取底层命令列表指针 |
| [TransitionBarrier](d3d12-command-list-transition-barrier.md) | 设置资源转换屏障 |
| [UAVBarrier](d3d12-command-list-uav-barrier.md) | 设置 UAV 屏障 |
| [AliasBarrier](d3d12-command-list-alias-barrier.md) | 设置别名屏障 |
| [SetPipelineState](d3d12-command-list-set-pipeline-state.md) | 设置管道状态 |
| [SetViewport](d3d12-command-list-set-viewport.md) | 设置视口 |
| [SetViewports](d3d12-command-list-set-viewports.md) | 设置多个视口 |
| [SetScissorRect](d3d12-command-list-set-scissor-rect.md) | 设置裁剪矩形 |
| [SetScissorRects](d3d12-command-list-set-scissor-rects.md) | 设置多个裁剪矩形 |
| [SetPrimitiveTopology](d3d12-command-list-set-primitive-topology.md) | 设置图元拓扑 |
| [SetRenderTargets](d3d12-command-list-set-render-targets.md) | 设置渲染目标 |
| [SetVertexBuffer](d3d12-command-list-set-vertex-buffer.md) | 设置顶点缓冲区 |
| [SetVertexBuffers](d3d12-command-list-set-vertex-buffers.md) | 设置多个顶点缓冲区 |
| [SetIndexBuffer](d3d12-command-list-set-index-buffer.md) | 设置索引缓冲区 |
| [SetStencilRef](d3d12-command-list-set-stencil-ref.md) | 设置模板参考值 |
| [SetDepthStencilState](d3d12-command-list-set-depth-stencil-state.md) | 设置深度模板状态 |
| [SetBlendState](d3d12-command-list-set-blend-state.md) | 设置混合状态 |
| [SetBlendFactor](d3d12-command-list-set-blend-factor.md) | 设置混合因子 |
| [SetDepthBias](d3d12-command-list-set-depth-bias.md) | 设置深度偏移 |
| [Draw](d3d12-command-list-draw.md) | 绘制调用 |
| [DrawIndexed](d3d12-command-list-draw-indexed.md) | 绘制索引图元 |
| [DrawInstancedIndirect](d3d12-command-list-draw-instanced-indirect.md) | 间接实例绘制 |
| [DrawIndexedInstancedIndirect](d3d12-command-list-draw-indexed-instanced-indirect.md) | 间接索引实例绘制 |
| [Clear](d3d12-command-list-clear.md) | 清除缓冲区 |
| [ClearRenderTarget](d3d12-command-list-clear-render-target.md) | 清除渲染目标 |
| [ClearDepthStencil](d3d12-command-list-clear-depth-stencil.md) | 清除深度模板 |
| [CopyResource](d3d12-command-list-copy-resource.md) | 复制资源 |
| [CopyBuffer](d3d12-command-list-copy-buffer.md) | 复制缓冲区 |
| [CopyTexture](d3d12-command-list-copy-texture.md) | 复制纹理 |
| [BeginQuery](d3d12-command-list-begin-query.md) | 开始查询 |
| [EndQuery](d3d12-command-list-end-query.md) | 结束查询 |
| [ResolveQueryData](d3d12-command-list-resolve-query-data.md) | 解析查询数据 |
| [Dispatch](d3d12-command-list-dispatch.md) | 分发计算任务 |
| [DispatchIndirect](d3d12-command-list-dispatch-indirect.md) | 间接分发计算任务 |
| [ExecuteBundle](d3d12-command-list-execute-bundle.md) | 执行命令束 |
## 使用示例
```cpp
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
using namespace XCEngine::RHI;
// 创建命令列表
D3D12CommandList commandList;
commandList.Initialize(device, CommandQueueType::Direct);
// 开始录制命令
commandList.Reset();
// 设置渲染目标
commandList.SetRenderTargets(1, &renderTargetView, nullptr);
float clearColor[] = { 0.0f, 0.0f, 0.0f, 1.0f };
commandList.ClearRenderTarget(renderTargetView, clearColor);
// 设置视口
Viewport viewport = { 0.0f, 0.0f, 1280.0f, 720.0f, 0.0f, 1.0f };
commandList.SetViewport(viewport);
// 设置图元拓扑
commandList.SetPrimitiveTopology(PrimitiveTopology::TriangleList);
// 绑定顶点缓冲区
commandList.SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex));
// 绑定索引缓冲区
commandList.SetIndexBuffer(indexBuffer, 0, Format::R32_UInt);
// 绑定管道状态
commandList.SetPipelineState(pipelineState);
// 绘制
commandList.DrawIndexed(indexCount, 1, 0, 0, 0);
// 关闭命令列表
commandList.Close();
// 提交到命令队列
commandQueue->ExecuteCommandListsInternal(1, &cmdList);
```
## 相关文档
- [D3D12 模块概览](d3d12.md) - D3D12 模块总览
- [RHICommandList](../rhi-command-list.md) - RHI 命令列表基类
- [D3D12CommandQueue](d3d12-command-queue.md) - 命令队列

63
docs/api/d3d12/d3d12-command-queue.md Normal file
View File

@@ -0,0 +1,63 @@
# D3D12CommandQueue
**命名空间**: `XCEngine::RHI`
**类型**: `class`
**头文件**: `XCEngine/RHI/D3D12/D3D12CommandQueue.h`
**描述**: DirectX 12 命令队列封装类，负责提交命令列表到 GPU 执行
## 概述
D3D12CommandQueue 是 DirectX 12 命令队列的封装类，继承自 RHICommandQueue 接口。它负责将录制好的命令列表提交到 GPU 执行，支持 GPU/CPU 同步操作，如信号、等待等。命令队列是渲染管线的核心组件，所有渲染命令都通过命令队列提交到 GPU。
## 公共方法
| 方法 | 描述 |
|------|------|
| `D3D12CommandQueue()` | 默认构造函数 |
| `~D3D12CommandQueue()` | 虚析构函数 |
| [Initialize](d3d12-command-queue-initialize.md) | 初始化命令队列 |
| [Shutdown](d3d12-command-queue-shutdown.md) | 关闭命令队列 |
| [ExecuteCommandLists](d3d12-command-queue-execute-command-lists.md) | 执行命令列表 |
| [Signal](d3d12-command-queue-signal.md) | 设置围栏信号 |
| [Wait](d3d12-command-queue-wait.md) | 等待围栏 |
| [GetCompletedValue](d3d12-command-queue-get-completed-value.md) | 获取已完成值 |
| [WaitForIdle](d3d12-command-queue-wait-for-idle.md) | 等待空闲 |
| [GetType](d3d12-command-queue-get-type.md) | 获取队列类型 |
| [GetTimestampFrequency](d3d12-command-queue-get-timestamp-frequency.md) | 获取时间戳频率 |
| [GetCommandQueue](d3d12-command-queue-get-command-queue.md) | 获取底层队列指针 |
| [WaitForPreviousFrame](d3d12-command-queue-wait-for-previous-frame.md) | 等待前一帧完成 |
## 使用示例
```cpp
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
using namespace XCEngine::RHI;
// 创建命令队列
D3D12CommandQueue commandQueue;
commandQueue.Initialize(device, CommandQueueType::Direct);
// 执行命令列表
ID3D12CommandList* lists[] = { commandList->GetCommandList() };
commandQueue.ExecuteCommandListsInternal(1, lists);
// 信号同步
commandQueue.Signal(fence, frameIndex);
commandQueue.WaitForPreviousFrame();
// 等待空闲
commandQueue.WaitForIdle();
// 关闭
commandQueue.Shutdown();
```
## 相关文档
- [D3D12 模块概览](d3d12.md) - D3D12 模块总览
- [D3D12CommandList](d3d12-command-list.md) - 命令列表
- [D3D12Fence](d3d12-fence.md) - 围栏同步

18
docs/api/d3d12/d3d12-device-check-feature-support.md Normal file
View File

@@ -0,0 +1,18 @@
# D3D12Device::CheckFeatureSupport
检查设备是否支持特定功能特性。
```cpp
bool CheckFeatureSupport(D3D12_FEATURE feature, void* featureSupportData, uint32_t featureSupportDataSize);
```
**参数：**
- `feature` - 要检查的功能特性
- `featureSupportData` - 存储结果的缓冲区
- `featureSupportDataSize` - 缓冲区大小
**返回：** `bool` - 支持返回 true，否则返回 false
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

17
docs/api/d3d12/d3d12-device-compile-shader.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CompileShader
编译着色器。
```cpp
RHIShader* CompileShader(const ShaderCompileDesc& desc) override;
```
**参数：**
- `desc` - 着色器编译描述
**返回：** `RHIShader*` - 创建的着色器指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Shader](d3d12-shader.md)

17
docs/api/d3d12/d3d12-device-create-buffer.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateBuffer
创建缓冲区资源。
```cpp
RHIBuffer* CreateBuffer(const BufferDesc& desc) override;
```
**参数：**
- `desc` - 缓冲区描述结构体
**返回：** `RHIBuffer*` - 创建的缓冲区指针，失败返回 nullptr
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Buffer](d3d12-buffer.md)

17
docs/api/d3d12/d3d12-device-create-command-list.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateCommandList
创建命令列表。
```cpp
RHICommandList* CreateCommandList(const CommandListDesc& desc) override;
```
**参数：**
- `desc` - 命令列表描述结构体
**返回：** `RHICommandList*` - 创建的命令列表指针，失败返回 nullptr
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12CommandList](d3d12-command-list.md)

17
docs/api/d3d12/d3d12-device-create-command-queue-impl.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateCommandQueueImpl
内部创建命令队列。
```cpp
D3D12CommandQueue* CreateCommandQueueImpl(const CommandQueueDesc& desc);
```
**参数：**
- `desc` - 命令队列描述
**返回：** `D3D12CommandQueue*` - 创建的命令队列指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12CommandQueue](d3d12-command-queue.md)

17
docs/api/d3d12/d3d12-device-create-command-queue.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateCommandQueue
创建命令队列。
```cpp
RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override;
```
**参数：**
- `desc` - 命令队列描述
**返回：** `RHICommandQueue*` - 创建的命令队列指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12CommandQueue](d3d12-command-queue.md)

17
docs/api/d3d12/d3d12-device-create-fence.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateFence
创建围栏。
```cpp
RHIFence* CreateFence(const FenceDesc& desc) override;
```
**参数：**
- `desc` - 围栏描述
**返回：** `RHIFence*` - 创建的围栏指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Fence](d3d12-fence.md)

17
docs/api/d3d12/d3d12-device-create-pipeline-state.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreatePipelineState
创建管道状态对象。
```cpp
RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) override;
```
**参数：**
- `desc` - 管道状态描述
**返回：** `RHIPipelineState*` - 创建的管道状态指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12PipelineState](d3d12-pipeline-state.md)

17
docs/api/d3d12/d3d12-device-create-sampler.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateSampler
创建采样器。
```cpp
RHISampler* CreateSampler(const SamplerDesc& desc) override;
```
**参数：**
- `desc` - 采样器描述
**返回：** `RHISampler*` - 创建的采样器指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Sampler](d3d12-sampler.md)

17
docs/api/d3d12/d3d12-device-create-swap-chain.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateSwapChain
创建交换链。
```cpp
RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) override;
```
**参数：**
- `desc` - 交换链描述结构体
**返回：** `RHISwapChain*` - 创建的交换链指针，失败返回 nullptr
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12SwapChain](d3d12-swap-chain.md)

17
docs/api/d3d12/d3d12-device-create-texture.md Normal file
View File

@@ -0,0 +1,17 @@
# D3D12Device::CreateTexture
创建纹理资源。
```cpp
RHITexture* CreateTexture(const TextureDesc& desc) override;
```
**参数：**
- `desc` - 纹理描述结构体
**返回：** `RHITexture*` - 创建的纹理指针，失败返回 nullptr
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Texture](d3d12-texture.md)

13
docs/api/d3d12/d3d12-device-enumerate-adapters.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::EnumerateAdapters
枚举所有可用的显示适配器。
```cpp
std::vector<AdapterInfo> EnumerateAdapters();
```
**返回：** `std::vector<AdapterInfo>` - 所有适配器的信息列表
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-adapter-info.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetAdapterInfo
获取当前适配器信息。
```cpp
const AdapterInfo& GetAdapterInfo() const { return m_adapterInfo; }
```
**返回：** `const AdapterInfo&` - 适配器信息引用
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-capabilities.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetCapabilities
获取设备能力。
```cpp
const RHICapabilities& GetCapabilities() const override;
```
**返回：** `const RHICapabilities&` - 设备能力引用
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

16
docs/api/d3d12/d3d12-device-get-descriptor-handle-increment-size.md Normal file
View File

@@ -0,0 +1,16 @@
# D3D12Device::GetDescriptorHandleIncrementSize
获取指定类型描述符堆的增量大小。
```cpp
UINT GetDescriptorHandleIncrementSize(DescriptorHeapType type) const;
```
**参数：**
- `type` - 描述符堆类型
**返回：** `UINT` - 描述符增量大小（字节）
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-device-info.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetDeviceInfo
获取设备信息。
```cpp
const RHIDeviceInfo& GetDeviceInfo() const override;
```
**返回：** `const RHIDeviceInfo&` - 设备信息引用
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-device.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetDevice
获取底层 ID3D12Device 指针。
```cpp
ID3D12Device* GetDevice() const { return m_device.Get(); }
```
**返回：** `ID3D12Device*` - DirectX 12 设备指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-factory.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetFactory
获取底层 IDXGIFactory4 指针。
```cpp
IDXGIFactory4* GetFactory() const { return m_factory.Get(); }
```
**返回：** `IDXGIFactory4*` - DXGI 工厂指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-native-device.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetNativeDevice
获取原生设备指针。
```cpp
void* GetNativeDevice() override;
```
**返回：** `void*` - 原生设备指针
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-get-native-handle.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::GetNativeHandle
获取原生句柄。
```cpp
void* GetNativeHandle() const;
```
**返回：** `void*` - 原生句柄
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

45
docs/api/d3d12/d3d12-device-initialize.md Normal file
View File

@@ -0,0 +1,45 @@
# D3D12Device::Initialize
初始化 DirectX 12 设备。
```cpp
bool Initialize(const RHIDeviceDesc& desc) override;
```
根据提供的设备描述配置创建设备对象、DXGI 工厂和 Direct3D 12 设备。此方法会枚举指定的适配器，获取其信息，并初始化调试层（如果启用）。
**参数：**
- `desc` - 设备描述结构体，包含启用调试层、GPU 验证、适配器索引、窗口句柄、分辨率等配置
**返回：** `bool` - 初始化成功返回 true，否则返回 false
**线程安全：** ❌ 非线程安全，应在单线程中调用
**注意：**
- 如果 `desc.enableDebugLayer` 为 true，将启用 DirectX 12 调试层
- 如果 `desc.enableGPUValidation` 为 true，将启用 GPU 验证
- 适配器索引无效时会自动回退到默认适配器
**示例：**
```cpp
RHIDeviceDesc desc;
desc.enableDebugLayer = true;
desc.enableGPUValidation = true;
desc.adapterIndex = 0;
desc.windowHandle = hwnd;
desc.width = 1920;
desc.height = 1080;
desc.appName = L"MyApp";
D3D12Device device;
if (!device.Initialize(desc)) {
MessageBox(L"Failed to initialize D3D12 device");
return false;
}
```
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Device::Shutdown](d3d12-device-shutdown.md)

13
docs/api/d3d12/d3d12-device-is-device-removed.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::IsDeviceRemoved
检查设备是否已被移除。
```cpp
bool IsDeviceRemoved() const { return m_isDeviceRemoved; }
```
**返回：** `bool` - 设备已移除返回 true
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

13
docs/api/d3d12/d3d12-device-set-device-removed.md Normal file
View File

@@ -0,0 +1,13 @@
# D3D12Device::SetDeviceRemoved
标记设备已被移除。
```cpp
void SetDeviceRemoved() { m_isDeviceRemoved = true; }
```
通常在设备丢失或移除时调用。
## 相关文档
- [D3D12Device 总览](d3d12-device.md)

20
docs/api/d3d12/d3d12-device-shutdown.md Normal file
View File

@@ -0,0 +1,20 @@
# D3D12Device::Shutdown
关闭设备并释放所有相关资源。
```cpp
void Shutdown() override;
```
关闭设备连接，释放 DXGI 工厂、设备和适配器接口。调用此方法后，设备将处于未初始化状态，可以重新调用 Initialize 重新初始化。
**线程安全：** ❌ 非线程安全，确保在所有相关资源释放后再调用
**注意：**
- 调用前应确保所有命令队列已执行完毕
- 所有通过此设备创建的资源应在此之前已释放
## 相关文档
- [D3D12Device 总览](d3d12-device.md)
- [D3D12Device::Initialize](d3d12-device-initialize.md)

133
docs/api/d3d12/d3d12-device.md Normal file
View File

@@ -0,0 +1,133 @@
# D3D12Device
**命名空间**: `XCEngine::RHI`
**类型**: `class`
**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h`
**描述**: DirectX 12 图形设备封装类，负责创建和管理所有 DirectX 12 图形对象
## 概述
D3D12Device 是 DirectX 12 的核心设备类，封装了 ID3D12Device 接口。它负责枚举显示适配器、创建命令队列、缓冲区、纹理、描述符堆、管道状态对象等所有图形资源。D3D12Device 继承自 RHIDevice 接口，提供跨后端的统一设备管理抽象。
该类支持可选的调试层和 GPU 验证功能，便于开发阶段的问题诊断。
## 适配器信息结构体
### AdapterInfo
存储适配器详细信息的结构体。
| 成员 | 类型 | 描述 |
|------|------|------|
| `description` | `std::wstring` | 适配器描述名称 |
| `dedicatedVideoMemory` | `uint64_t` | 专用视频内存大小（字节） |
| `dedicatedSystemMemory` | `uint64_t` | 专用系统内存大小（字节） |
| `sharedSystemMemory` | `uint64_t` | 共享系统内存大小（字节） |
| `vendorId` | `uint32_t` | 硬件供应商 ID |
| `deviceId` | `uint32_t` | 设备 ID |
| `isSoftware` | `bool` | 是否为软件适配器 |
## 公共方法
| 方法 | 描述 |
|------|------|
| `D3D12Device()` | 默认构造函数 |
| `~D3D12Device()` | 虚析构函数 |
| [Initialize](d3d12-device-initialize.md) | 初始化设备 |
| [Shutdown](d3d12-device-shutdown.md) | 关闭设备并释放资源 |
| [GetDevice](d3d12-device-get-device.md) | 获取底层 ID3D12Device 指针 |
| [GetFactory](d3d12-device-get-factory.md) | 获取底层 IDXGIFactory4 指针 |
| [GetAdapterInfo](d3d12-device-get-adapter-info.md) | 获取当前适配器信息 |
| [EnumerateAdapters](d3d12-device-enumerate-adapters.md) | 枚举所有可用适配器 |
| [GetDescriptorHandleIncrementSize](d3d12-device-get-descriptor-handle-increment-size.md) | 获取描述符增量大小 |
| [CheckFeatureSupport](d3d12-device-check-feature-support.md) | 检查功能特性支持 |
| [SetDeviceRemoved](d3d12-device-set-device-removed.md) | 标记设备已移除 |
| [IsDeviceRemoved](d3d12-device-is-device-removed.md) | 检查设备是否已移除 |
| [CreateBuffer](d3d12-device-create-buffer.md) | 创建缓冲区资源 |
| [CreateTexture](d3d12-device-create-texture.md) | 创建纹理资源 |
| [CreateSwapChain](d3d12-device-create-swap-chain.md) | 创建交换链 |
| [CreateCommandList](d3d12-device-create-command-list.md) | 创建命令列表 |
| [CreateCommandQueue](d3d12-device-create-command-queue.md) | 创建命令队列 |
| [CompileShader](d3d12-device-compile-shader.md) | 编译着色器 |
| [CreatePipelineState](d3d12-device-create-pipeline-state.md) | 创建管道状态对象 |
| [CreateFence](d3d12-device-create-fence.md) | 创建围栏 |
| [CreateSampler](d3d12-device-create-sampler.md) | 创建采样器 |
| [GetCapabilities](d3d12-device-get-capabilities.md) | 获取设备能力 |
| [GetDeviceInfo](d3d12-device-get-device-info.md) | 获取设备信息 |
| [GetNativeDevice](d3d12-device-get-native-device.md) | 获取原生设备指针 |
| [GetNativeHandle](d3d12-device-get-native-handle.md) | 获取原生句柄 |
| [CreateCommandQueueImpl](d3d12-device-create-command-queue-impl.md) | 内部创建命令队列 |
| [CreateCommandListImpl](d3d12-device-create-command-list-impl.md) | 内部创建命令列表 |
| [CreateCommandAllocator](d3d12-device-create-command-allocator.md) | 内部创建命令分配器 |
| [CreateDescriptorHeap](d3d12-device-create-descriptor-heap.md) | 内部创建描述符堆 |
| [CreateQueryHeap](d3d12-device-create-query-heap.md) | 内部创建查询堆 |
| [CreateRootSignature](d3d12-device-create-root-signature.md) | 内部创建根签名 |
| [CreateRenderTargetView](d3d12-device-create-render-target-view.md) | 创建渲染目标视图 |
| [CreateDepthStencilView](d3d12-device-create-depth-stencil-view.md) | 创建深度模板视图 |
| [CreateShaderResourceView](d3d12-device-create-shader-resource-view.md) | 创建着色器资源视图 |
| [CreateUnorderedAccessView](d3d12-device-create-unordered-access-view.md) | 创建无序访问视图 |
| [CreateConstantBufferView](d3d12-device-create-constant-buffer-view.md) | 创建常量缓冲区视图 |
## 使用示例
```cpp
#include <XCEngine/RHI/D3D12/D3D12Device.h>
using namespace XCEngine::RHI;
// 创建设备实例
D3D12Device device;
// 配置设备参数
RHIDeviceDesc desc;
desc.enableDebugLayer = true; // 启用调试层
desc.enableGPUValidation = true; // 启用 GPU 验证
desc.adapterIndex = 0; // 使用第一个适配器
desc.windowHandle = hwnd; // 窗口句柄
desc.width = 1280;
desc.height = 720;
desc.appName = L"XCEngine App";
// 初始化设备
if (!device.Initialize(desc)) {
// 处理初始化失败
return false;
}
// 获取设备信息
const RHIDeviceInfo& info = device.GetDeviceInfo();
printf("GPU: %ls\n", info.description.c_str());
// 获取设备能力
const RHICapabilities& caps = device.GetCapabilities();
printf("MaxTextureSize: %u\n", caps.maxTextureSize);
// 创建命令队列
CommandQueueDesc queueDesc;
queueDesc.queueType = static_cast<uint32_t>(CommandQueueType::Direct);
queueDesc.priority = 0;
queueDesc.nodeMask = 0;
queueDesc.flags = 0;
D3D12CommandQueue* commandQueue = device.CreateCommandQueueImpl(queueDesc);
// 创建缓冲区
BufferDesc bufferDesc;
bufferDesc.size = 1024 * 1024; // 1MB
bufferDesc.stride = 0;
bufferDesc.bufferType = static_cast<uint32_t>(BufferType::Vertex);
bufferDesc.flags = 0;
RHIBuffer* buffer = device.CreateBuffer(bufferDesc);
// 设备关闭
device.Shutdown();
```
## 相关文档
- [D3D12 模块概览](d3d12.md) - D3D12 模块总览
- [RHIDevice](../rhi-device.md) - RHI 设备基类
- [D3D12CommandQueue](d3d12-command-queue.md) - 命令队列
- [D3D12Buffer](d3d12-buffer.md) - 缓冲区资源

142
docs/api/d3d12/d3d12.md Normal file
View File

@@ -0,0 +1,142 @@
# 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 测试设计文档