XCEngine/tests/D3D12/AGENT.md

D3D12 测试文档

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

---

1. 概述

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

---

2. 测试内容

2.1 渲染管线测试

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

2.2 截图测试

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

---

3. 构建与运行

3.1 构建

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

# 配置 CMake
cmake .. -A x64

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

3.2 运行

# 方式一：直接运行可执行文件
./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

在代码中设置：

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:

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

8.2 修改分辨率

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

---

9. 添加新测试

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

---

10. 持续集成

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

# 在 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