From 05c4dfb5eb4b478cf05d0e1d5b6982c5264c6aa6 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Tue, 17 Mar 2026 02:49:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20D3D12=20=E6=B5=8B?= =?UTF-8?q?=E8=AF=95=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB?= =?UTF-8?q?=E5=8A=A0=E6=9E=84=E5=BB=BA=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/D3D12后端测试设计.md | 244 ++++++++++++++++++++++++++++++++++---- 1 file changed, 223 insertions(+), 21 deletions(-) diff --git a/docs/D3D12后端测试设计.md b/docs/D3D12后端测试设计.md index c0a7bd7b..ec03b89b 100644 --- a/docs/D3D12后端测试设计.md +++ b/docs/D3D12后端测试设计.md @@ -24,27 +24,112 @@ ## 2. 测试目录结构 +### 2.1 资源目录（保留现有 tests/D3D12） + +现有 `tests/D3D12` 目录保留，作为测试资源文件来源： + ``` tests/D3D12/ -├── CMakeLists.txt # 构建配置（需改造为 Google Test） -├── fixtures/ -│ └── D3D12TestFixture.h # 基础测试夹具 -├── 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_swap_chain.cpp # D3D12SwapChain 测试（需窗口） -├── test_shader.cpp # D3D12Shader 测试 -├── test_views.cpp # RTV/DSV/SRV/UAV 测试 -└── test_screenshot.cpp # 渲染结果测试 +├── Res/ # 测试资源文件（供新测试框架使用） +│ ├── Shader/ +│ │ ├── test_vs.hlsl # 测试用顶点着色器 +│ │ ├── test_ps.hlsl # 测试用像素着色器 +│ │ ├── test_gs.hlsl # 测试用几何着色器 +│ │ ├── test_cs.hlsl # 测试用计算着色器 +│ │ └── test_pattern.hlsl # 图案化测试着色器 +│ ├── Texture/ +│ │ ├── test_256x256.png # 测试用 2D 纹理 +│ │ └── test_cube.dds # 测试用立方体纹理 +│ └── Golden/ +│ ├── clear_color_gt.ppm # 清除颜色基准图像 +│ ├── pattern_checker_gt.ppm # 棋盘格基准图像 +│ └── gradient_gt.ppm # 渐变基准图像 +├── main.cpp # 现有渲染示例（保留） +├── CMakeLists.txt # 现有构建配置（保留） +└── ... # 其他现有文件（保留） ``` +### 2.2 新测试框架目录 + +在 `engine/src/RHI/D3D12/` 下创建新的测试模块： + +``` +engine/src/RHI/D3D12/ +├── test/ # 新测试目录 +│ ├── CMakeLists.txt # 测试构建配置 +│ ├── fixtures/ +│ │ ├── D3D12TestFixture.h # 基础测试夹具 +│ │ ├── D3D12ResourceFixture.h # 资源测试夹具 +│ │ └── D3D12LeakCheckFixture.h # # 泄漏检测夹具 +│ ├── 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 测试 +│ ├── test_types.cpp # 类型转换测试 +│ └── test_screenshot.cpp # 截图功能测试 +│ +├── D3D12Device.cpp # 现有源文件 +├── D3D12CommandQueue.cpp # 现有源文件 +└── ... # 其他现有源文件 +``` + +### 2.3 构建配置说明 + +新的测试框架通过 CMake 添加到引擎构建中： + +```cmake +# engine/CMakeLists.txt 中添加 +if(BUILD_D3D12_TESTS) + enable_testing() + add_subdirectory(src/RHI/D3D12/test) +endif() +``` + +```cmake +# engine/src/RHI/D3D12/test/CMakeLists.txt +cmake_minimum_required(VERSION 3.15) + +project(D3D12EngineTests) + +set(CMAKE_CXX_STANDARD 17) + +# 查找 Google Test +find_package(GTest REQUIRED) + +# 测试源文件 +set(TEST_SOURCES + test_device.cpp + test_command_queue.cpp + test_buffer.cpp + # ... 其他测试文件 +) + +add_executable(d3d12_engine_tests ${TEST_SOURCES}) + +target_link_libraries(d3d12_engine_tests PRIVATE + d3d12 + dxgi + d3dcompiler + XCEngine + GTest::gtest + GTest::gtest_main +) + +# 设置资源目录路径 +target_compile_definitions(d3d12_engine_tests PRIVATE + TEST_RESOURCES_DIR="${CMAKE_SOURCE_DIR}/../../tests/D3D12/Res" +) + +add_test(NAME D3D12EngineTests COMMAND d3d12_engine_tests) + ## 3. 测试夹具设计 ### 3.1 基础夹具 @@ -1356,17 +1441,17 @@ TEST(D3D12Enum, ToD3D12_ResourceStates_All) { ## 12. 测试数据文件 -测试所需资源文件应放在 `tests/D3D12/Res/` 目录： +测试所需资源文件从 `tests/D3D12/Res/` 目录获取： ``` tests/D3D12/Res/ -├── Shaders/ +├── Shader/ │ ├── test_vs.hlsl # 测试用顶点着色器 │ ├── test_ps.hlsl # 测试用像素着色器 │ ├── test_gs.hlsl # 测试用几何着色器 │ ├── test_cs.hlsl # 测试用计算着色器 │ └── test_pattern.hlsl # 图案化测试着色器 -├── Textures/ +├── Texture/ │ ├── test_256x256.png # 测试用 2D 纹理 │ └── test_cube.dds # 测试用立方体纹理 └── Golden/ @@ -1375,10 +1460,127 @@ tests/D3D12/Res/ └── gradient_gt.ppm # 渐变基准图像 ``` +### 12.1 在测试中引用资源 + +```cpp +// 通过编译定义获取资源路径 +#ifndef TEST_RESOURCES_DIR +#define TEST_RESOURCES_DIR "tests/D3D12/Res" +#endif + +TEST(D3D12Shader, CompileFromFile_VertexShader) { + D3D12Shader shader; + + // 构建资源路径 + std::wstring shaderPath = std::wstring(TEST_RESOURCES_DIR) + L"/Shader/test_vs.hlsl"; + + bool result = shader.CompileFromFile(shaderPath.c_str(), "main", "vs_5_1"); + + ASSERT_TRUE(result); +} + --- -## 13. 后续改进 +## 13. 构建计划与执行流程 +本文档描述的测试框架将按照以下计划逐步构建，每完成一个步骤即进行测试、提交并推送。 + +### 13.1 构建计划总览 + +| 步骤 | 文件 | 内容 | 验证方式 | +|------|------|------|----------| +| **步骤 1: 基础设施搭建** | +| 1.1 | `engine/src/RHI/D3D12/test/CMakeLists.txt` | 测试构建配置 | CMake 配置检查 | +| 1.2 | `engine/src/RHI/D3D12/test/fixtures/D3D12TestFixture.h` | 基础测试夹具 | 编译通过 | +| **步骤 2: 核心组件测试** | +| 2.1 | `test_device.cpp` | D3D12Device 初始化、适配器枚举、特性查询 | 运行测试 | +| 2.2 | `test_fence.cpp` | D3D12Fence 同步、Signal/Wait | 运行测试 | +| **步骤 3: 命令系统测试** | +| 3.1 | `test_command_queue.cpp` | 队列创建、执行命令、同步 | 运行测试 | +| 3.2 | `test_command_allocator.cpp` | 分配器创建、重置 | 运行测试 | +| 3.3 | `test_command_list.cpp` | 命令录制、资源屏障、绘制 | 运行测试 | +| **步骤 4: 资源测试** | +| 4.1 | `test_buffer.cpp` | Buffer 创建、Map/Unmap、数据上传 | 运行测试 | +| 4.2 | `test_texture.cpp` | 纹理创建、深度模板 | 运行测试 | +| 4.3 | `test_descriptor_heap.cpp` | 描述符堆创建、句柄获取 | 运行测试 | +| **步骤 5: 渲染管线测试** | +| 5.1 | `test_shader.cpp` | Shader 编译 | 运行测试 | +| 5.2 | `test_root_signature.cpp` | 根签名创建、参数 | 运行测试 | +| 5.3 | `test_pipeline_state.cpp` | PSO 创建 | 运行测试 | +| **步骤 6: 视图测试** | +| 6.1 | `test_views.cpp` | RTV/DSV/SRV/UAV/CBV | 运行测试 | + +### 13.2 执行流程 + +每完成一个步骤，按以下流程操作： + +```bash +# 1. 编译项目 +cmake --build build --config Debug + +# 2. 运行测试 +ctest --test-dir build -C Debug --output-on-failure + +# 3. 提交更改 +git add . +git commit -m "test: 添加 D3D12 Device 测试" + +# 4. 推送更改 +git push +``` + +### 13.3 CMake 集成方式 + +采用方案 A：在 `tests/CMakeLists.txt` 中添加子目录引用。 + +在 `tests/CMakeLists.txt` 中添加： +```cmake +# 在现有 add_subdirectory 行之后添加 +add_subdirectory(D3D12) +``` + +创建 `tests/D3D12/CMakeLists.txt` 用于将 `engine/src/RHI/D3D12/test` 添加到构建： +```cmake +# tests/D3D12/CMakeLists.txt +cmake_minimum_required(VERSION 3.15) + +project(D3D12Integration) + +# 将 engine 测试目录添加到父级 CMake +add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../../engine/src/RHI/D3D12/test ${CMAKE_BINARY_DIR}/D3D12_test) +``` + +### 13.4 测试夹具代码结构 + +基础测试夹具 `D3D12TestFixture.h` 提供以下功能： + +- 全局 D3D12 设备（所有测试共享） +- 每测试周期的命令队列、分配器、命令列表 +- GPU 等待辅助方法 +- 资源清理保证 + +### 13.5 资源路径配置 + +测试资源从 `tests/D3D12/Res/` 获取，通过 CMake 编译定义传递路径： + +```cmake +target_compile_definitions(d3d12_tests PRIVATE + TEST_RESOURCES_DIR="${CMAKE_SOURCE_DIR}/tests/D3D12/Res" +) +``` + +### 13.6 注意事项 + +1. **测试隔离**：每个测试用例应独立创建所需的资源 +2. **资源清理**：在 TearDown 中确保等待 GPU 完成后释放资源 +3. **调试层**：建议在 Debug 构建设中启用 D3D12 Debug Layer +4. **窗口依赖**：SwapChain 等需要窗口的测试放在最后 + +--- + +## 14. 后续改进 + +- [ ] 在 `engine/src/RHI/D3D12/test/` 创建测试夹具文件 - [ ] 实现 Phase 1 核心基础设施测试 - [ ] 实现 Phase 2 资源管理测试 - [ ] 实现 Phase 3 渲染管线测试