From 58341c9daff5f7cbe78db5c252ab5ee587b2e029 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Sun, 15 Mar 2026 17:43:35 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20D3D12=20=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/D3D12/README.md | 195 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 195 insertions(+)
 create mode 100644 tests/D3D12/README.md

diff --git a/tests/D3D12/README.md b/tests/D3D12/README.md
new file mode 100644
index 00000000..f3eb5441
--- /dev/null
+++ b/tests/D3D12/README.md
@@ -0,0 +1,195 @@
+# 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