196 lines
3.9 KiB
Markdown
196 lines
3.9 KiB
Markdown
# 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
|