# 3d-engine

**Repository Path**: xhcmh/3d-engine

## Basic Information

- **Project Name**: 3d-engine
- **Description**: No description available
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D Engine

一个基于 Qt6 和 OpenGL 4.3 的现代 3D 引擎项目。

## 📋 项目概述

这是一个从零开始构建的 3D 游戏引擎，主要用于学习和实践计算机图形学、物理模拟和游戏引擎架构。

## 🛠️ 技术栈

- **GUI框架**: Qt6
- **图形API**: OpenGL 4.3 Core
- **数学库**: GLM (OpenGL Mathematics)
- **模型加载**: Assimp (待集成)
- **物理引擎**: Bullet Physics (待集成)
- **构建系统**: CMake 3.16+

## 📦 系统要求

- C++17 编译器 (MSVC 2019+, GCC 9+, Clang 10+)
- Qt6 (6.2 或更高版本)
- OpenGL 4.3+ 支持
- CMake 3.16+

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd 3d-engine
```

### 2. 安装依赖

请参考 [docs/03-环境搭建.md](docs/03-环境搭建.md) 获取详细的依赖安装指南。

### 3. 配置和编译

#### Windows (使用 Visual Studio)

```bash
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release
```

#### Windows (使用 MinGW)

```bash
mkdir build
cd build
cmake .. -G "MinGW Makefiles"
cmake --build .
```

#### Linux / macOS

```bash
mkdir build
cd build
cmake ..
make -j4
```

### 4. 运行

```bash
./bin/3DEngine        # Linux/macOS
.\bin\3DEngine.exe    # Windows
```

### 5. 运行测试程序

项目包含多个测试程序，用于验证各个系统的功能：

```bash
# 进入构建目录
cd build/bin

# 运行材质纹理系统测试 ⭐ 推荐
./MaterialTest        # Linux/macOS
MaterialTest.exe      # Windows

# 其他测试程序
./MathTest           # 数学库测试
./RenderTest         # 渲染系统测试
./CameraTest         # 摄像机系统测试
./LightTest          # 光照系统测试
```

详细的编译和测试指南请参考 [BUILD_MATERIAL_TEST.md](BUILD_MATERIAL_TEST.md)

## 📚 文档

完整文档请查看 [docs](docs/) 目录：

### 基础文档
- [项目概览](docs/01-项目概览.md)
- [开发路线图](docs/02-开发路线图.md)
- [环境搭建](docs/03-环境搭建.md)
- [项目架构](docs/04-项目架构.md)
- [编码规范](docs/05-编码规范.md)
- [快速开始指南](docs/快速开始指南.md)

### 系统文档
- [数学库设计](docs/06-数学库设计.md)
- [渲染系统](docs/07-渲染系统.md)
- [摄像机系统](docs/08-摄像机系统.md)
- [光照系统](docs/09-光照系统.md)
- [材质纹理系统](docs/10-材质纹理系统.md) ⭐ 新增
- [材质纹理系统实现说明](docs/材质纹理系统实现说明.md) ⭐ 新增

### API 文档
- [渲染系统 API](src/render/README.md)
- [摄像机系统 API](src/camera/README.md)
- [光照系统 API](src/light/README.md)
- [纹理系统 API](src/texture/README.md) ⭐ 新增
- [材质系统 API](src/material/README.md) ⭐ 新增

## 📁 项目结构

```
3d-engine/
├── CMakeLists.txt          # CMake 配置文件
├── README.md               # 项目说明
├── BUILD_MATERIAL_TEST.md  # 材质测试编译指南
├── src/                    # 源代码
│   ├── main.cpp            # 主入口
│   ├── math/               # 数学库
│   ├── render/             # 渲染系统
│   ├── camera/             # 摄像机系统
│   ├── light/              # 光照系统
│   ├── texture/            # 纹理系统 ⭐
│   ├── material/           # 材质系统 ⭐
│   ├── test_math.cpp       # 数学库测试
│   ├── test_render.cpp     # 渲染系统测试
│   ├── test_camera.cpp     # 摄像机测试
│   ├── test_light.cpp      # 光照测试
│   └── test_material.cpp   # 材质测试 ⭐
├── include/                # 公共头文件
├── assets/                 # 资源文件
│   └── shaders/            # GLSL 着色器
├── external/               # 第三方库
│   └── glm/                # GLM 数学库
├── docs/                   # 文档
└── build/                  # 构建目录 (Git忽略)
```

## 🎯 开发状态

- [x] 项目初始化
- [x] CMake 构建系统
- [x] Qt6 + OpenGL 基础框架
- [x] 数学库集成 (GLM)
- [x] 渲染系统（Buffer、Shader、Mesh、Renderer）
- [x] 摄像机系统（FPS、Orbit）
- [x] 光照系统（方向光、点光源、聚光灯）
- [x] 材质纹理系统（Texture、Material、PBR）⭐ 新增
- [ ] 模型加载（Assimp）
- [ ] 物理引擎集成（Bullet）
- [ ] 场景管理
- [ ] 编辑器工具

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

[MIT License](LICENSE)

## 📧 联系方式

如有问题，请通过 Issue 联系。