# OpenGL 测试文档

> **版本**: 1.0
> **日期**: 2026-03-16

---

## 1. 概述

OpenGL 测试是 XCEngine 渲染硬件接口 (RHI) 的集成测试，用于验证 OpenGL 渲染管线的正确性。

---

## 2. 测试内容

### 2.1 渲染管线测试

| 测试项 | 说明 |
|--------|------|
| 窗口初始化 | GLFW 窗口、OpenGL 上下文创建 |
| GLAD 初始化 | OpenGL 函数加载 |
| 着色器编译 | 顶点着色器、片段着色器编译 |
| 模型加载 | 使用 Assimp 加载背包模型 |
| 纹理加载 | 加载 diffuse/specular 纹理 |
| 渲染输出 | PBR 渲染到屏幕 |

### 2.2 截图测试

程序在第 30 帧自动截图，并与基准图 `GT.ppm` 进行像素级对比。

---

## 3. 构建与运行

### 3.1 构建

```bash
# 创建构建目录
mkdir build && cd build

# 配置 CMake
cmake .. -A x64

# 编译
cmake --build . --config Debug --target XCRender
```

### 3.2 运行

```bash
# 方式一：直接运行可执行文件
./build/tests/OpenGL/Debug/XCRender.exe

# 方式二：运行测试脚本（自动截图并对比）
./build/tests/OpenGL/Debug/run.bat
```

---

## 4. 测试流程

```
1. 初始化 GLFW
   ├── 创建窗口
   └── 创建 OpenGL 上下文

2. 初始化 GLAD
   └── 加载 OpenGL 函数

3. 加载资源
   ├── 编译着色器
   ├── 加载模型 (Assimp)
   └── 加载纹理 (stb_image)

4. 渲染循环
   ├── 清空帧缓冲
   ├── 设置 Uniforms
   ├── 绘制模型
   └── 交换缓冲区

5. 截图验证 (第 30 帧)
   ├── 读取帧缓冲 (glReadPixels)
   ├── 保存为 PPM 格式
   └── 与 GT.ppm 对比
```

---

## 5. 文件结构

```
tests/OpenGL/
├── CMakeLists.txt      # 构建配置
├── main.cpp           # 测试程序入口
├── run.bat            # 运行脚本
├── compare_ppm.py     # 图片对比脚本
├── Res/               # 资源目录
│   ├── models/        # 模型文件 (backpack)
│   └── shaders/       # 着色器
└── package/          # 第三方库
    ├── include/       # 头文件 (GLFW, GLAD, Assimp, GLM, stb_image)
    └── lib/          # 库文件
```

---

## 6. 基准图

- **GT.ppm**: 正确渲染的参考截图 (1280x720)
- **screenshot.ppm**: 程序渲染的实际截图
- **对比阈值**: 5 (像素差异容忍度)

---

## 7. 调试

### 7.1 日志输出

程序使用 XCEngine Logger 系统，日志输出到：
- 控制台 (ConsoleLogSink)
- 文件 (FileLogSink): `OpenGL_engine_log.txt`

### 7.2 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 黑色画面 | 着色器编译失败 | 检查着色器错误日志 |
| 无纹理 | 纹理路径错误 | 确认 res/models/ 目录 |
| 模型未显示 | Assimp 加载失败 | 检查模型文件是否存在 |

---

## 8. 技术细节

- **分辨率**: 1280x720
- **OpenGL 版本**: 3.3 Core Profile
- **依赖库**: GLFW, GLAD, Assimp, GLM, stb_image
- **平台**: Windows

---

## 9. 与 D3D12 测试对比

| 特性 | D3D12 | OpenGL |
|------|-------|--------|
| 分辨率 | 1280x720 | 1280x720 |
| 截图帧 | 30 | 30 |
| 模型 | Sphere.lhsm | backpack.obj |
| 日志系统 | XCEngine Logger | XCEngine Logger |