# opengl-test-tool

**Repository Path**: toolfox/opengl-test-tool

## Basic Information

- **Project Name**: opengl-test-tool
- **Description**: 基于OpenGL的测试工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenGL 3D 平台

基于 OpenGL 的 3D 绘制 App 平台，使用 C++17 和 CMake 构建。

## 功能特性

- ✅ OpenGL 3.3 Core Profile 渲染
- ✅ GLFW 窗口管理
- ✅ GLAD 2 OpenGL 函数加载
- ✅ GLM 数学库
- ✅ Dear ImGui 用户界面
- ✅ spdlog 日志系统
- ✅ Breakpad 崩溃捕获与 dump 分析
- ✅ 着色器管理系统
- ✅ 顶点数组和缓冲区封装
- ✅ 3D 摄像机控制
- ✅ 基础几何体绘制

## 项目结构

```
UITestPool/
├── CMakeLists.txt              # CMake 构建配置
├── src/                        # 源代码
│   ├── main.cpp                # 程序入口
│   ├── core/                   # 核心模块
│   │   ├── Application.h/cpp   # 应用程序主类
│   │   ├── Window.h/cpp        # 窗口封装
│   │   └── Input.h/cpp         # 输入处理
│   ├── renderer/               # 渲染模块
│   │   ├── Renderer.h/cpp      # 渲染器接口
│   │   ├── Shader.h/cpp        # 着色器管理
│   │   ├── VertexArray.h/cpp   # 顶点数组
│   │   ├── Buffer.h/cpp        # 缓冲区
│   │   └── Camera.h/cpp        # 摄像机
│   └── utils/                  # 工具模块
│       ├── Log.h/cpp           # 日志工具 (spdlog)
│       └── CrashHandler.h/cpp  # 崩溃处理器 (Breakpad)
├── scripts/                    # 脚本工具
│   ├── init_submodules.sh      # 初始化 submodule
│   ├── build_breakpad.sh       # 编译 Breakpad 客户端库
│   └── analyze_crash.sh        # 分析 crash dump 文件
├── docs/                       # 文档
│   ├── BREAKPAD_SETUP.md       # Breakpad 集成指南
│   ├── CPP_CODING_STANDARD.md  # C++ 编码规范
│   └── SUBMODULE_GUIDE.md      # Submodule 使用指南
├── resources/                  # 资源文件
│   └── shaders/                # 着色器文件
│       ├── basic.vert          # 基础顶点着色器
│       └── basic.frag          # 基础片段着色器
└── third_party/                # 第三方库
    ├── glfw/                   # GLFW 窗口管理
    ├── glad/                   # GLAD 2 OpenGL 加载器
    ├── glm/                    # GLM 数学库
    ├── imgui/                  # Dear ImGui 用户界面
    ├── spdlog/                 # spdlog 日志库
    └── breakpad/               # Google Breakpad 崩溃捕获
```

## 构建说明

### 前置要求

- CMake 3.16+
- C++17 兼容的编译器 (GCC, Clang, MSVC)
- OpenGL 3.3+ 支持
- Git (用于 submodule 管理)
- SSH 密钥配置 (用于下载依赖)

### 获取项目 (包含 Submodule)

#### 方法 1: 克隆时初始化 Submodule (推荐)

```bash
git clone --recurse-submodules git@github.com:your-username/UITestPool.git
cd UITestPool
```

#### 方法 2: 克隆后手动初始化

```bash
# 克隆项目
git clone git@github.com:your-username/UITestPool.git
cd UITestPool

# 初始化 submodule
git submodule init
git submodule update
```

#### 方法 3: 使用初始化脚本 (最简单)

```bash
# 克隆项目
git clone git@github.com:your-username/UITestPool.git
cd UITestPool

# 运行初始化脚本
./scripts/init_submodules.sh
```

### 编译步骤

1. **克隆项目**
```bash
cd UITestPool
```

2. **创建构建目录**
```bash
mkdir build
cd build
```

3. **配置 CMake**
```bash
cmake ..
```

4. **编译项目**
```bash
cmake --build .
```

5. **运行程序**
```bash
# macOS/Linux
./bin/UITestPool

# Windows
bin\UITestPool.exe
```

## 依赖管理

项目使用 **Git Submodule** 管理以下依赖 (通过 SSH 协议):

- **GLFW** (3.3.8) - 窗口管理 (git@github.com:glfw/glfw.git)
- **GLM** (1.0.1) - 数学库 (git@github.com:g-truc/glm.git)
- **Dear ImGui** (v1.90.1) - 用户界面 (git@github.com:ocornut/imgui.git)
- **spdlog** (1.x) - 高性能日志库 (git@github.com:gabime/spdlog.git)
- **Google Breakpad** - 崩溃捕获与 dump 分析 (git@github.com:google/breakpad.git)
- **GLAD 2** - OpenGL 函数加载 (本地生成，支持 OpenGL 3.3 Core)

### Submodule 优势

1. **版本控制**: 精确控制每个库的版本和提交
2. **离线开发**: 一次下载后可离线使用，无需网络
3. **本地修改**: 可以对库进行本地修改和调试
4. **清晰依赖**: 所有依赖在 `.gitmodules` 中明确列出
5. **SSH 下载**: 使用 SSH 协议，更安全，支持私有仓库

### 首次使用

确保已配置 SSH 密钥并添加到 GitHub:

```bash
# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "your_email@example.com"

# 添加公钥到 GitHub (https://github.com/settings/keys)
```

### 依赖后备方案

如果 submodule 未初始化，CMake 会尝试使用 FetchContent 通过 SSH 自动下载作为后备。

详细使用说明请参考 [Submodule 使用指南](docs/SUBMODULE_GUIDE.md)

## 使用说明

### 键盘控制

- **W** - 相机向前移动
- **S** - 相机向后移动
- **A** - 相机向左移动
- **D** - 相机向右移动

### 鼠标控制

- **按住左键移动** - 控制视角方向
- **滚轮** - 缩放视野

## 扩展开发

### 添加新的渲染功能

1. 在 `renderer/` 目录创建新的渲染类
2. 在 `Application::OnRender()` 中调用渲染逻辑
3. 使用着色器系统创建自定义渲染效果

### 添加用户界面

在 `OnImGuiRender()` 方法中添加 ImGui 代码:

```cpp
void OnImGuiRender() override {
    ImGui::Begin("My Window");
    ImGui::Text("Hello, ImGui!");
    ImGui::End();
}
```

## 故障排除

### 构建问题

1. **依赖下载失败**: 确保网络连接正常，可以尝试手动下载依赖
2. **OpenGL 版本错误**: 确保系统支持 OpenGL 3.3+
3. **链接错误**: 检查是否正确安装了系统依赖库

### macOS 特定问题

- 需要安装 Xcode Command Line Tools
- 可能需要设置 CMake 的 macOS 部署目标
- Breakpad 需要编译客户端库：`./scripts/build_breakpad.sh`

### 崩溃分析

程序崩溃时会自动生成 dump 文件到 `build/crash/` 目录。使用分析脚本解析：

```bash
# 分析最新的 crash dump
./scripts/analyze_crash.sh analyze-latest

# 列出所有 dump 文件
./scripts/analyze_crash.sh list

# 分析指定 dump 文件
./scripts/analyze_crash.sh analyze build/crash/xxx.dmp
```

详见 [Breakpad 集成指南](docs/BREAKPAD_SETUP.md)。

### Linux 特定问题

安装必要的系统库:

```bash
# Ubuntu/Debian
sudo apt-get install libglfw3-dev libgl1-mesa-dev libxi-dev

# Fedora
sudo dnf install glfw-devel mesa-libGL-devel libXi-devel
```

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request!

## 联系方式

如有问题或建议，请提交 Issue。