XCEngine/tests/OpenGL/README.md

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 构建

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

# 配置 CMake
cmake .. -A x64

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

3.2 运行

# 方式一：直接运行可执行文件
./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