# 变更记录：D3D12 设备初始化实现

**提交日期**: 2026-03-26  
**提交哈希**: `69b7352`  
**变更类型**: 功能实现

---

## 变更概述

本次提交实现了 D3D12 设备的完整初始化流程，包括调试层、DXGI 工厂创建、GPU 适配器枚举与选择、特性级别检查和设备创建。

## 修改文件

### Engine/Graphics/Direct3D12/

| 文件 | 变更说明 |
|------|----------|
| `D3D12Core.cpp` | 实现完整的 D3D12 设备初始化流程 |
| `D3D12Core.h` | 添加 `release` 模板函数 |
| `D3D12CommonHeader.h` | 添加库链接、DXCall 宏、NAME_D3D12_OBJECT 宏 |

### Engine/Graphics/

| 文件 | 变更说明 |
|------|----------|
| `Renderer.h` | 添加 Doxygen 注释 |
| `Renderer.cpp` | 添加 Doxygen 注释 |
| `GraphicsPlatformInterface.h` | 添加 Doxygen 注释 |

---

## 技术要点

### 1. 调试层启用

```cpp
#ifdef _DEBUG
{
    ComPtr<ID3D12Debug3> debug_interface;
    DXCall(D3D12GetDebugInterface(IID_PPV_ARGS(&debug_interface)));
    debug_interface->EnableDebugLayer();
    dxgi_factory_flag |= DXGI_CREATE_FACTORY_DEBUG;
}
#endif
```

调试层可捕获无效 API 调用和资源泄漏。

### 2. GPU 适配器选择

```cpp
IDXGIAdapter4* determine_main_adapter()
{
    for (u32 i{ 0 }; ...; ++i)
    {
        // 按高性能优先枚举适配器
        if (SUCCEEDED(D3D12CreateDevice(adapter, minumum_feature_level, ...)))
            return adapter;
    }
    return nullptr;
}
```

优先选择高性能 GPU，并验证 D3D12 支持。

### 3. 特性级别检查

```cpp
constexpr D3D_FEATURE_LEVEL feature_levels[4]{
    D3D_FEATURE_LEVEL_11_0,
    D3D_FEATURE_LEVEL_11_1,
    D3D_FEATURE_LEVEL_12_0,
    D3D_FEATURE_LEVEL_12_1,
};
```

获取适配器支持的最高特性级别，确保不低于最低要求 (11.0)。

### 4. 调试宏

```cpp
// DXCall 宏 - 检查 HRESULT 并输出错误信息
#define DXCall(x) if(FAILED(x)) { ... __debugbreak(); }

// NAME_D3D12_OBJECT 宏 - 为 D3D12 对象设置调试名称
#define NAME_D3D12_OBJECT(obj, name) obj->SetName(name);
```

### 5. 信息队列配置

```cpp
info_queue->SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_CORRUPTION, true);
info_queue->SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_WARNING, true);
info_queue->SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_ERROR, true);
```

在调试模式下，遇到警告或错误时自动断点。

---

## 初始化流程

```
initialize()
    │
    ├─► 启用调试层 (DEBUG 模式)
    │
    ├─► 创建 DXGI 工厂
    │
    ├─► 枚举并选择 GPU 适配器
    │       └─► 按高性能优先
    │       └─► 验证 D3D12 支持
    │
    ├─► 获取最高特性级别
    │       └─► 必须 >= 11.0
    │
    ├─► 创建 D3D12 设备
    │
    └─► 配置信息队列 (DEBUG 模式)
```

---

## 依赖

- `dxgi.lib` - DXGI 库
- `d3d12.lib` - Direct3D 12 库

---

## 后续工作

- [ ] 命令队列创建
- [ ] 交换链管理
- [ ] 描述符堆

---

## 相关文档

- [D3D12学习Wiki](../wiki/D3D12学习Wiki.md)