ssdfasd
394bec9db6
- Create TEST_SPEC.md with OpenGL test hierarchy and specifications - Add section and inline comments to main.cpp explaining: - Window size calculation with AdjustWindowRect - glFinish before screenshot for GPU sync - Target frame count warm-up period - Shutdown order (reverse of initialization)
251 lines
5.8 KiB
Markdown
251 lines
5.8 KiB
Markdown
# OpenGL 测试专项规范
|
||
|
||
本文档是 XCEngine 测试规范的 OpenGL 专项补充。
|
||
|
||
**前置阅读**: [tests/TEST_SPEC.md](../TEST_SPEC.md) - 通用测试规范
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 OpenGL 测试特点
|
||
|
||
| 特点 | 说明 |
|
||
|------|------|
|
||
| 平台依赖 | Windows WGL 实现，Win32 原生 API |
|
||
| 窗口依赖 | 集成测试需要 GUI 窗口 |
|
||
| GPU 状态 | 测试间可能有 GPU 状态污染 |
|
||
| 无 GLFW | 已移除 GLFW 依赖，使用 Win32 WGL API |
|
||
|
||
### 1.2 测试层级
|
||
|
||
| 层级 | 位置 | 执行方式 | 框架 |
|
||
|------|------|----------|------|
|
||
| 单元测试 | `tests/RHI/OpenGL/unit/` | CTest | Google Test |
|
||
| 集成测试 | `tests/RHI/OpenGL/integration/` | CTest + Python | Python wrapper |
|
||
|
||
---
|
||
|
||
## 2. 单元测试规范
|
||
|
||
### 2.1 Fixture 设计
|
||
|
||
每个测试独立创建 OpenGL 上下文，避免 GPU 状态污染：
|
||
|
||
```cpp
|
||
class OpenGLTestFixture : public ::testing::Test {
|
||
protected:
|
||
void SetUp() override; // 创建窗口、初始化 OpenGL 上下文
|
||
void TearDown() override; // 清理资源、销毁上下文
|
||
|
||
HWND GetHWND();
|
||
HDC GetHDC();
|
||
HGLRC GetGLRC();
|
||
void MakeCurrent();
|
||
};
|
||
```
|
||
|
||
### 2.2 测试前缀对应
|
||
|
||
| 类名 | 测试前缀 |
|
||
|------|---------|
|
||
| OpenGLDevice | Device |
|
||
| OpenGLSwapChain | SwapChain |
|
||
| OpenGLBuffer | Buffer |
|
||
| OpenGLTexture | Texture |
|
||
| OpenGLShader | Shader |
|
||
| OpenGLCommandList | CommandList |
|
||
| OpenGLPipelineState | PipelineState |
|
||
| OpenGLRenderTargetView | RTV |
|
||
| OpenGLDepthStencilView | DSV |
|
||
| OpenGLFence | Fence |
|
||
| OpenGLSampler | Sampler |
|
||
| OpenGLVertexArray | VertexArray |
|
||
|
||
---
|
||
|
||
## 3. 集成测试规范
|
||
|
||
### 3.1 目录结构
|
||
|
||
每个集成测试独占一个子文件夹，资源相互隔离：
|
||
|
||
```
|
||
integration/
|
||
├── CMakeLists.txt # 构建配置
|
||
├── run_integration_test.py # 公共测试运行脚本
|
||
├── compare_ppm.py # PPM 图像比对脚本
|
||
├── minimal/ # 最小化测试
|
||
│ ├── main.cpp
|
||
│ ├── GT.ppm
|
||
│ ├── CMakeLists.txt
|
||
│ └── run.bat
|
||
└── ... # 其他测试
|
||
```
|
||
|
||
### 3.2 Python Wrapper
|
||
|
||
**位置**: `tests/RHI/OpenGL/integration/run_integration_test.py`
|
||
|
||
**职责**:
|
||
1. 启动 OpenGL exe
|
||
2. 等待进程完成
|
||
3. 检查输出文件 (PPM 截图)
|
||
4. 调用 `compare_ppm.py` 比对 Golden Image
|
||
5. 返回 0(成功)/1(失败)
|
||
|
||
### 3.3 CTest 注册格式
|
||
|
||
```cmake
|
||
add_test(NAME OpenGL_Minimal_Integration
|
||
COMMAND ${Python3_EXECUTABLE} $<TARGET_FILE_DIR:OpenGL_Minimal>/run_integration_test.py
|
||
$<TARGET_FILE:OpenGL_Minimal>
|
||
minimal.ppm
|
||
${CMAKE_CURRENT_SOURCE_DIR}/minimal/GT.ppm
|
||
5
|
||
WORKING_DIRECTORY $<TARGET_FILE_DIR:OpenGL_Minimal>
|
||
)
|
||
```
|
||
|
||
### 3.4 Golden Image 规范
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 格式 | PPM (P6) |
|
||
| 命名 | `GT.ppm` 或 `GT_<test_name>.ppm` |
|
||
| 阈值 | 默认 5% |
|
||
| 存储位置 | `tests/RHI/OpenGL/integration/<test_name>/` |
|
||
|
||
### 3.5 Golden Image 生成流程
|
||
|
||
1. 在干净硬件环境运行集成测试
|
||
2. 截图保存为 `minimal.ppm`
|
||
3. 人工验证截图正确性
|
||
4. 提交到版本控制作为 GT
|
||
|
||
### 3.6 当前集成测试
|
||
|
||
| 测试名 | Golden Image | 状态 |
|
||
|--------|-------------|------|
|
||
| OpenGL_Minimal_Integration | `minimal/GT.ppm` | ✅ 通过 |
|
||
|
||
---
|
||
|
||
## 4. 测试执行
|
||
|
||
### 4.1 单元测试
|
||
|
||
```bash
|
||
# 方式 1: 使用统一脚本
|
||
python scripts/run_tests.py --unit-only
|
||
|
||
# 方式 2: 直接使用 CTest
|
||
cd build/tests/RHI/OpenGL/unit
|
||
ctest -C Debug --output-on-failure
|
||
```
|
||
|
||
### 4.2 集成测试
|
||
|
||
```bash
|
||
# 方式 1: 使用统一脚本
|
||
python scripts/run_tests.py --integration
|
||
|
||
# 方式 2: 直接使用 CTest
|
||
cd build/tests/RHI/OpenGL/integration
|
||
ctest -C Debug --output-on-failure
|
||
```
|
||
|
||
### 4.3 构建和测试
|
||
|
||
```bash
|
||
# 构建
|
||
cmake --build . --target OpenGL_Minimal --config Debug
|
||
|
||
# 运行测试
|
||
python scripts/run_tests.py --build
|
||
```
|
||
|
||
---
|
||
|
||
## 5. CI 集成
|
||
|
||
### 5.1 GitHub Actions 配置
|
||
|
||
```yaml
|
||
name: OpenGL Tests
|
||
on: [push, pull_request]
|
||
|
||
jobs:
|
||
test:
|
||
runs-on: windows-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Configure CMake
|
||
run: cmake -B build -DCMAKE_BUILD_TYPE=Debug
|
||
|
||
- name: Build OpenGL Tests
|
||
run: cmake --build build --target OpenGL_Minimal --config Debug
|
||
|
||
- name: Run Unit Tests
|
||
run: cd build/tests/RHI/OpenGL/unit && ctest -C Debug --output-on-failure
|
||
|
||
- name: Run Integration Tests
|
||
run: python scripts/run_tests.py --integration
|
||
```
|
||
|
||
### 5.2 CI 模式
|
||
|
||
`--ci` 模式会跳过需要 GUI 的集成测试:
|
||
```bash
|
||
python scripts/run_tests.py --ci # 仅运行单元测试
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 文件结构
|
||
|
||
```
|
||
tests/RHI/OpenGL/
|
||
├── CMakeLists.txt
|
||
├── TEST_SPEC.md # 本文档 (OpenGL 专项)
|
||
├── unit/
|
||
│ ├── CMakeLists.txt
|
||
│ ├── fixtures/
|
||
│ │ ├── OpenGLTestFixture.h
|
||
│ │ └── OpenGLTestFixture.cpp
|
||
│ └── test_device.cpp
|
||
└── integration/
|
||
├── CMakeLists.txt
|
||
├── run_integration_test.py # 公共脚本
|
||
├── compare_ppm.py # 公共脚本
|
||
└── minimal/ # 最小化测试
|
||
├── main.cpp
|
||
├── GT.ppm
|
||
├── CMakeLists.txt
|
||
└── run.bat
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 已知问题
|
||
|
||
### 7.1 窗口尺寸问题
|
||
|
||
**问题**: `SetWindowPos` 的尺寸参数在 `WS_OVERLAPPEDWINDOW` 风格下是完整窗口尺寸（包含 chrome、边框），而不是客户区尺寸。
|
||
|
||
**修复**: 使用 `AdjustWindowRect` 计算完整尺寸后再传给 `SetWindowPos`。
|
||
|
||
---
|
||
|
||
## 8. 规范更新记录
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|------|------|------|
|
||
| 1.0 | 2026-03-20 | 初始版本，移除 GLFW 依赖后的重构版本 |
|
||
|
||
---
|
||
|
||
**规范版本**: 1.0
|
||
**最后更新**: 2026-03-20
|
||
**前置文档**: [tests/TEST_SPEC.md](../TEST_SPEC.md) |