256 lines
7.1 KiB
Markdown
256 lines
7.1 KiB
Markdown
# D3D12 后端测试进展报告
|
||
|
||
## 一、概述
|
||
|
||
本报告记录 XCEngine D3D12 后端测试框架的开发进展。测试框架基于 Google Test 构建，旨在为 D3D12 各组件提供全面、规范的自动化测试覆盖。
|
||
|
||
## 二、测试目录结构
|
||
|
||
```
|
||
tests/RHI/D3D12/
|
||
├── CMakeLists.txt # 测试构建配置
|
||
├── fixtures/
|
||
│ ├── D3D12TestFixture.h # 基础测试夹具
|
||
│ └── D3D12TestFixture.cpp # 夹具实现
|
||
├── test_device.cpp # D3D12Device 测试
|
||
├── test_command_queue.cpp # D3D12CommandQueue 测试
|
||
├── test_command_allocator.cpp # D3D12CommandAllocator 测试
|
||
├── test_command_list.cpp # D3D12CommandList 测试
|
||
├── test_buffer.cpp # D3D12Buffer 测试
|
||
├── test_texture.cpp # D3D12Texture 测试
|
||
├── test_descriptor_heap.cpp # D3D12DescriptorHeap 测试
|
||
├── test_pipeline_state.cpp # D3D12PipelineState 测试
|
||
├── test_root_signature.cpp # D3D12RootSignature 测试
|
||
├── test_fence.cpp # D3D12Fence 测试
|
||
├── test_shader.cpp # D3D12Shader 测试
|
||
└── test_views.cpp # RTV/DSV/SRV/UAV 测试
|
||
```
|
||
|
||
## 三、测试夹具设计
|
||
|
||
### 3.1 D3D12TestFixture
|
||
|
||
测试夹具为每个测试用例提供独立的 D3D12 资源环境：
|
||
|
||
- **D3D12 设备**：每个测试独立创建，避免 GPU 状态污染
|
||
- **命令队列**：用于命令执行和同步
|
||
- **命令分配器**：管理命令内存
|
||
- **命令列表**：录制图形命令
|
||
- **GPU 等待机制**：确保命令执行完成后才清理资源
|
||
|
||
```cpp
|
||
class D3D12TestFixture : public ::testing::Test {
|
||
protected:
|
||
void SetUp() override;
|
||
void TearDown() override;
|
||
|
||
ID3D12Device* GetDevice();
|
||
ID3D12CommandQueue* GetCommandQueue();
|
||
ID3D12GraphicsCommandList* GetCommandList();
|
||
ID3D12CommandAllocator* GetCommandAllocator();
|
||
|
||
void WaitForGPU();
|
||
};
|
||
```
|
||
|
||
### 3.2 设计决策
|
||
|
||
**为什么每个测试独立创建设备？**
|
||
|
||
初始设计使用静态共享设备，但测试发现执行命令列表后 GPU 状态变化会导致后续测试的 SetUp 失败。通过让每个测试创建独立的设备、命令队列、分配器和命令列表，有效解决了资源状态污染问题。
|
||
|
||
## 四、测试覆盖详情
|
||
|
||
### 4.1 测试统计
|
||
|
||
| 组件 | 测试数量 | 状态 |
|
||
|------|----------|------|
|
||
| Device | 6 | ✓ 通过 |
|
||
| Fence | 5 | ✓ 通过 |
|
||
| CommandQueue | 3 | ✓ 通过 |
|
||
| CommandAllocator | 4 | ✓ 通过 |
|
||
| CommandList | 3 | ✓ 通过 |
|
||
| Buffer | 6 | ✓ 通过 |
|
||
| Texture | 5 | ✓ 通过 |
|
||
| DescriptorHeap | 6 | ✓ 通过 |
|
||
| PipelineState | 3 | ✓ 通过 |
|
||
| RootSignature | 3 | ✓ 通过 |
|
||
| Shader | 4 | ✓ 通过 |
|
||
| Views | 5 | ✓ 通过 |
|
||
| **总计** | **54** | **全部通过** |
|
||
|
||
### 4.2 各组件测试详情
|
||
|
||
#### D3D12Device (6个测试)
|
||
- 创建设备成功
|
||
- 获取命令队列成功
|
||
- 检查功能级别
|
||
- 获取描述符增量大小
|
||
- 检查 Shader 模型支持
|
||
- 检查资源绑定层级
|
||
- 检查平铺资源层级
|
||
|
||
#### D3D12Fence (5个测试)
|
||
- 创建围栏成功
|
||
- 获取初始完成值
|
||
- Signal 和 Wait
|
||
- 设置事件完成回调
|
||
- 多次 Signal
|
||
|
||
#### D3D12CommandQueue (3个测试)
|
||
- 创建设备成功
|
||
- 获取时间戳频率
|
||
- 执行命令列表
|
||
|
||
#### D3D12CommandAllocator (4个测试)
|
||
- 占位测试
|
||
- 重置分配器
|
||
- 多次重置
|
||
- 不同类型分配器
|
||
|
||
#### D3D12CommandList (3个测试)
|
||
- 占位测试
|
||
- 关闭命令列表
|
||
- 获取命令列表类型
|
||
|
||
#### D3D12Buffer (6个测试)
|
||
- 占位测试
|
||
- 创建默认堆 Buffer
|
||
- 创建上传堆 Buffer
|
||
- 获取 GPU 虚拟地址
|
||
- Map/Unmap 操作
|
||
- 对齐要求
|
||
|
||
#### D3D12Texture (5个测试)
|
||
- 占位测试
|
||
- 创建 2D 纹理
|
||
- 创建 3D 纹理
|
||
- 创建多 Mip 级别纹理
|
||
- 创建纹理数组
|
||
|
||
#### D3D12DescriptorHeap (6个测试)
|
||
- 占位测试
|
||
- 创建 CBV_SRV_UAV 堆
|
||
- 创建 Sampler 堆
|
||
- 创建 RTV 堆
|
||
- 创建 DSV 堆
|
||
- 获取描述符增量大小
|
||
|
||
#### D3D12PipelineState (3个测试)
|
||
- 占位测试
|
||
- 图形管线描述符默认值
|
||
- 计算管线描述符默认值
|
||
|
||
#### D3D12RootSignature (3个测试)
|
||
- 占位测试
|
||
- 创建空根签名
|
||
- 创建带 CBV 参数的根签名
|
||
|
||
#### D3D12Shader (4个测试)
|
||
- 占位测试
|
||
- 顶点着色器配置
|
||
- 像素着色器配置
|
||
- 计算着色器配置
|
||
|
||
#### Views (5个测试)
|
||
- 占位测试
|
||
- 创建 RTV 描述符堆
|
||
- 创建 DSV 描述符堆
|
||
- 创建 CBV 描述符堆
|
||
- RTV 描述符句柄增量
|
||
|
||
## 五、构建与运行
|
||
|
||
### 5.1 构建命令
|
||
|
||
```bash
|
||
cd build
|
||
cmake --build . --target d3d12_engine_tests
|
||
```
|
||
|
||
### 5.2 运行测试
|
||
|
||
```bash
|
||
./build/tests/RHI/D3D12/Debug/d3d12_engine_tests.exe
|
||
```
|
||
|
||
### 5.3 测试输出示例
|
||
|
||
```
|
||
[==========] Running 54 tests from 1 test suite.
|
||
[----------] Global test environment set-up.
|
||
[----------] 54 tests from D3D12TestFixture
|
||
[ RUN ] D3D12TestFixture.Buffer_Placeholder
|
||
[ OK ] D3D12TestFixture.Buffer_Placeholder (365 ms)
|
||
...
|
||
[----------] Global test environment tear-down
|
||
[==========] 54 tests from 1 test suite ran.
|
||
[ PASSED ] 54 tests.
|
||
```
|
||
|
||
## 六、已知问题与解决方案
|
||
|
||
### 6.1 GPU 状态污染问题
|
||
|
||
**问题描述**：初始设计使用静态共享 Device，执行命令列表后 GPU 状态变化导致后续测试 SetUp 失败。
|
||
|
||
**解决方案**：改为每个测试在 SetUp 中独立创建所有 D3D12 资源，TearDown 中完整清理。
|
||
|
||
### 6.2 ID3D12CommandList vs ID3D12GraphicsCommandList
|
||
|
||
**问题描述**：D3D12 API 中，`ID3D12CommandList` 是接口基类，实际创建的是 `ID3D12GraphicsCommandList`。
|
||
|
||
**解决方案**：测试夹具中使用 `ID3D12GraphicsCommandList` 类型以调用 Reset/Close 等方法。
|
||
|
||
### 6.3 常量地址问题
|
||
|
||
**问题描述**：不能直接对常量取地址，如 `&D3D_FEATURE_LEVEL_12_0`。
|
||
|
||
**解决方案**：使用静态数组存储常量，然后取数组元素地址。
|
||
|
||
## 七、未来工作
|
||
|
||
### 7.1 待实现功能
|
||
|
||
1. **类型转换测试** (`test_types.cpp`)
|
||
- D3D12Enum 枚举转换
|
||
- D3D12Types 类型转换
|
||
|
||
### 7.2 集成测试（已完成）
|
||
|
||
**integration/** 目录包含完整的端到端渲染测试：
|
||
- `main.cpp`: 主程序入口
|
||
- `Res/`: 着色器、纹理、模型资源
|
||
- `run.bat`: 运行脚本
|
||
- `compare_ppm.py`: 截图对比工具
|
||
- `GT.ppm`: Golden Image 参考图
|
||
|
||
**状态**: ✅ 已修复 API 变更问题
|
||
|
||
**API 变更修复**:
|
||
- D3D12Device::Initialize 现在需要 RHIDeviceDesc 参数
|
||
- CommandQueue::Signal 现在使用 RHIFence* 接口
|
||
- Logger::Debug/FileLogSink 现在使用 Containers::String
|
||
- SwapChain::Initialize 现在返回 bool
|
||
- CommandList::Reset 不再需要参数
|
||
- SetRenderTargets 改为 SetRenderTargetsHandle
|
||
|
||
### 7.3 高级测试场景
|
||
|
||
- SwapChain 测试（需要窗口环境）
|
||
- 复杂渲染管线测试
|
||
- 多线程同步测试
|
||
- 显存压力测试
|
||
|
||
## 八、总结
|
||
|
||
D3D12 后端测试框架已完成核心组件的全面测试覆盖，共 54 个测试用例全部通过。测试框架采用 Google Test，支持持续集成自动化测试。集成测试已完成 API 适配修复。
|
||
|
||
---
|
||
|
||
**报告日期**：2026年3月19日
|
||
**测试框架版本**：1.1
|
||
**单元测试数**：54
|
||
**单元测试通过率**：100%
|
||
**集成测试**：✅ 已修复
|