# D3D12 测试文档

> **版本**: 1.0
> **日期**: 2026-03-15

---

## 1. 概述

D3D12 测试是 XCEngine 渲染硬件接口 (RHI) 的集成测试，用于验证 DirectX 12 渲染管线的正确性。

---

## 2. 测试内容

### 2.1 渲染管线测试

| 测试项 | 说明 |
|--------|------|
| 设备初始化 | D3D12 设备、交换链、命令队列创建 |
| 渲染目标 | 颜色缓冲、深度缓冲创建与绑定 |
| 着色器编译 | 顶点着色器、像素着色器编译 |
| 资源绑定 | 常量缓冲、纹理、描述符堆 |
| 渲染输出 | 三角形渲染到屏幕 |

### 2.2 截图测试

程序在第 30 帧自动截图，并与基准图 `GT.ppm` 进行像素级对比。

---

## 3. 构建与运行

### 3.1 构建

```bash
# 创建构建目录
mkdir build && cd build

# 配置 CMake
cmake .. -A x64

# 编译
cmake --build . --config Debug --target D3D12
```

### 3.2 运行

```bash
# 方式一：直接运行可执行文件
./build/tests/D3D12/Debug/D3D12.exe

# 方式二：运行测试脚本（自动截图并对比）
./build/tests/D3D12/Debug/run.bat
```

---

## 4. 测试流程

```
1. 初始化 D3D12 设备
   ├── 创建 DXGIFactory
   ├── 创建 ID3D12Device
   └── 创建命令队列

2. 创建交换链
   ├── 创建描述符堆 (RTV/DSV)
   ├── 创建渲染目标视图
   └── 创建深度模板缓冲

3. 加载资源
   ├── 编译着色器
   ├── 创建根签名
   ├── 创建 PSO
   └── 加载纹理

4. 渲染循环
   ├── 等待 GPU 完成
   ├── 重置命令分配器
   ├── 绑定资源
   ├── 绘制三角形
   └── .present()

5. 截图验证 (第 30 帧)
   ├── 读取渲染目标到 CPU
   ├── 保存为 PPM 格式
   └── 与 GT.ppm 对比
```

---

## 5. 文件结构

```
tests/D3D12/
├── CMakeLists.txt      # 构建配置
├── main.cpp           # 测试程序入口
├── run.bat            # 运行脚本
├── compare_ppm.py     # 图片对比脚本
├── Res/               # 资源目录
│   ├── Image/         # 纹理图片
│   ├── Model/        # 模型文件
│   └── Shader/       # 着色器
└── stbi/             # stb_image 库
```

---

## 6. 基准图

- **GT.ppm**: 正确渲染的参考截图 (1280x720)
- **screenshot.ppm**: 程序渲染的实际截图
- **对比阈值**: 5 (像素差异容忍度)

---

## 7. 调试

### 7.1 启用 Debug Layer

在代码中设置：
```cpp
bool enableDebugLayer = true;
gDevice.Initialize(enableDebugLayer);
```

### 7.2 日志输出

程序使用 XCEngine Logger 系统，日志输出到：
- 控制台 (ConsoleLogSink)
- 文件 (FileLogSink): `D3D12_engine_log.txt`

### 7.3 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 纯黑画面 | 着色器编译失败 | 检查着色器错误日志 |
| 无纹理 | 纹理路径错误 | 确认 Res/Image/ 目录 |
| 截图失败 | GPU 未完成渲染 | 等待 fence 信号 |

---

## 8. 修改测试参数

### 8.1 修改截图帧数

编辑 `main.cpp`:
```cpp
if (frameCount == 30) {  // 修改此值
    SaveScreenshot("screenshot.ppm", 1280, 720);
    PostQuitMessage(0);
}
```

### 8.2 修改分辨率

```cpp
if (frameCount == 30) {
    SaveScreenshot("screenshot.ppm", 1280, 720);  // 修改分辨率
    PostQuitMessage(0);
}
```

---

## 9. 添加新测试

1. 在 `main.cpp` 中添加测试逻辑
2. 重新编译
3. 运行并验证

---

## 10. 持续集成

测试脚本可集成到 CI 流程：

```yaml
# 在 CI 中运行
- name: Build D3D12
  run: cmake --build build --config Debug --target D3D12

- name: Run Test
  run: ./build/tests/D3D12/Debug/run.bat
```

---

## 11. 注意事项

1. **GUI 程序**: D3D12.exe 是 Windows GUI 程序，需要图形界面运行
2. **GPU 要求**: 需要支持 DirectX 12 的显卡
3. **分辨率**: 默认 1280x720
4. **平台**: 仅支持 Windows