# render_engine_sample

**Repository Path**: Macro1995/render_engine_sample

## Basic Information

- **Project Name**: render_engine_sample
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OLP3DEngine

## 介绍

OLP3DEngine 是一款基于 OpenGL 的 3D 引擎，实现了三维可视化、交互、仿真等核心功能，同时预留与物理引擎、WPF 用户界面的对接接口，支撑 OLP 产品的虚拟仿真与可视化能力。

## 软件架构

### 分层架构

OLP3DEngine 采用分层架构设计，主要分为以下几层：

| 层级 | 描述 | 主要模块 |
|------|------|----------|
| 底层渲染层 | 基于 OpenGL 实现模型加载、光照、纹理、渲染管线管理 | Renderer |
| 核心功能层 | 封装可视化、交互、仿真等业务功能 | Scene, SceneObject, Camera, ResourceManager |
| 接口适配层 | 提供物理引擎对接接口、WPF 对接接口 | Window, WPFInterface |
| 工具层 | 包含几何建模、测量、录像等辅助工具 | ModelLoader, Common |

### 核心技术选型

| 技术 | 用途 | 版本要求 |
|------|------|----------|
| C++ | 核心开发语言 | C++17 |
| OpenGL | 图形渲染 API | OpenGL 1.5+ |
| CMake | 构建系统 | 3.16+ |
| Clang | 编译器 | 19+ |
| Ninja | 构建工具 | 最新版 |

## 代码模块说明

### 1. 渲染器模块 (Renderer)

**功能描述**：负责 OpenGL 渲染管线管理，实现模型渲染、相机控制等功能。

**主要接口**：
- `initialize(width, height)`：初始化渲染器
- `cleanup()`：清理渲染器资源
- `beginFrame()`：开始渲染帧
- `endFrame()`：结束渲染帧
- `renderMesh(mesh, transform, color)`：渲染网格
- `setViewport(width, height)`：设置视口大小
- `setClearColor(color)`：设置背景颜色

**文件位置**：
- `include/renderer/Renderer.h`
- `src/renderer/Renderer.cpp`

### 2. 模型加载器模块 (ModelLoader)

**功能描述**：负责加载各种格式的 3D 模型，支持 FBX、GLB、OBJ 等格式。

**主要接口**：
- `loadModel(filePath, meshes)`：加载模型
- `isSupportedFormat(filePath)`：检查是否支持该格式

**文件位置**：
- `include/renderer/ModelLoader.h`
- `src/renderer/ModelLoader.cpp`

### 3. 场景管理模块 (Scene)

**功能描述**：负责场景管理，包括对象添加、移除、更新和渲染。

**主要接口**：
- `addObject(object)`：添加对象到场景
- `removeObject(objectName)`：从场景移除对象
- `findObject(objectName)`：查找场景对象
- `update(deltaTime)`：更新场景
- `render(renderer)`：渲染场景
- `clear()`：清空场景
- `getCamera()`：获取相机
- `setCamera(camera)`：设置相机

**文件位置**：
- `include/core/Scene.h`
- `src/core/Scene.cpp`

### 4. 场景对象模块 (SceneObject)

**功能描述**：表示场景中的对象，包含位置、旋转、缩放等属性。

**主要接口**：
- `setPosition(position)`：设置位置
- `getPosition()`：获取位置
- `setRotation(rotation)`：设置旋转
- `getRotation()`：获取旋转
- `setScale(scale)`：设置缩放
- `getScale()`：获取缩放
- `setVisible(visible)`：设置可见性
- `isVisible()`：获取可见性
- `update(deltaTime)`：更新对象
- `render(renderer)`：渲染对象

**文件位置**：
- `include/core/SceneObject.h`
- `src/core/SceneObject.cpp`

### 5. 相机模块 (Camera)

**功能描述**：负责相机控制，包括旋转、平移、缩放等操作。

**主要接口**：
- `setPerspective(fov, aspectRatio, nearClip, farClip)`：设置透视投影
- `setOrthographic(left, right, bottom, top, nearClip, farClip)`：设置正交投影
- `getViewMatrix()`：获取视图矩阵
- `getProjectionMatrix()`：获取投影矩阵
- `rotate(deltaX, deltaY)`：旋转相机
- `pan(deltaX, deltaY)`：平移相机
- `zoom(delta)`：缩放相机
- `setPosition(position)`：设置相机位置
- `getPosition()`：获取相机位置
- `setLookAt(target)`：设置相机朝向

**文件位置**：
- `include/core/Camera.h`
- `src/core/Camera.cpp`

### 6. 资源管理模块 (ResourceManager)

**功能描述**：负责资源管理，实现模型缓存机制，避免重复加载相同模型。

**主要接口**：
- `getInstance()`：获取单例实例
- `initialize()`：初始化资源管理器
- `cleanup()`：清理资源管理器
- `loadModel(filePath, meshes)`：加载模型（带缓存）
- `getModel(filePath, meshes)`：获取已加载的模型
- `releaseModel(filePath)`：释放指定模型资源
- `releaseAllModels()`：释放所有模型资源

**文件位置**：
- `include/core/ResourceManager.h`
- `src/core/ResourceManager.cpp`

### 7. 窗口模块 (Window)

**功能描述**：负责窗口创建和事件处理。

**主要接口**：
- `initialize(width, height, title)`：初始化窗口
- `cleanup()`：清理窗口资源
- `processEvents()`：处理窗口事件
- `shouldClose()`：检查窗口是否应该关闭
- `swapBuffers()`：交换缓冲区

**文件位置**：
- `include/interface/Window.h`
- `src/interface/Window.cpp`

### 8. WPF 交互模块 (WPFInterface)

**功能描述**：提供与 WPF 界面的对接接口，实现 WPF 与 3D 引擎的交互。

**主要接口**：
- `OLP3D_Initialize()`：初始化引擎
- `OLP3D_Cleanup()`：清理引擎
- `OLP3D_RenderFrame()`：渲染一帧
- `OLP3D_AddObject()`：添加对象
- `OLP3D_RemoveObject()`：移除对象
- `OLP3D_CameraRotate()`：旋转相机
- `OLP3D_CameraPan()`：平移相机
- `OLP3D_CameraZoom()`：缩放相机

**文件位置**：
- `include/interface/WPFInterface.h`
- `src/interface/WPFInterface.cpp`

### 9. 公共模块 (Common)

**功能描述**：包含通用类型定义、工具函数等。

**主要类型**：
- `Vector3<T>`：3D 向量
- `Matrix4x4<T>`：4x4 矩阵
- `Color4`：4 通道颜色

**文件位置**：
- `include/common/types.h`
- `src/common/types.cpp`

## 安装教程

### 1. 环境准备

- 安装 Clang 编译器（版本 19+）
- 安装 CMake（版本 3.16+）
- 安装 Ninja 构建工具

### 2. 构建项目

```bash
# 创建构建目录
cmake -B build

# 构建项目
cmake --build build
```

### 3. 运行示例

```bash
# 运行基本渲染示例
examples/basic_render.exe

# 运行窗口渲染示例
examples/window_render.exe
```

## 使用说明

### 1. 基本使用流程

```cpp
// 1. 创建窗口
Window window;
window.initialize(1280, 720, "OLP3D Engine");

// 2. 创建渲染器
Renderer renderer;
renderer.initialize(1280, 720);

// 3. 创建场景
Scene scene;

// 4. 创建场景对象
auto object = std::make_shared<SceneObject>("TestObject");
object->setPosition({1.0f, 0.0f, 0.0f});
scene.addObject(object);

// 5. 主循环
while (!window.shouldClose()) {
    window.processEvents();
    
    renderer.beginFrame();
    scene.update(0.016f);
    scene.render(renderer);
    renderer.endFrame();
    
    window.swapBuffers();
}

// 6. 清理资源
renderer.cleanup();
window.cleanup();
```

### 2. 相机控制

```cpp
// 获取相机
auto camera = scene.getCamera();

// 旋转相机
camera->rotate(deltaX, deltaY);

// 平移相机
camera->pan(deltaX, deltaY);

// 缩放相机
camera->zoom(delta);
```

### 3. 模型加载

```cpp
// 使用资源管理器加载模型
std::vector<MeshData> meshes;
ResourceManager::getInstance().loadModel("model.obj", meshes);
```

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 代码规范

- 遵循 Google C++ 代码风格
- 函数/类命名清晰（如 `SceneRenderer::DrawModel`）
- 接口参数优先使用基础数据类型（int、float、数组）
- 接口返回 bool 或错误码，关键流程记录日志
- 模型采用 LOD（细节层次）渲染，复杂场景启用批处理绘制

## 性能优化

- 模型缓存机制，避免重复加载相同模型
- 高效的对象查找和管理机制
- 支持 LOD 渲染，根据距离自动调整模型细节
- 批处理渲染，减少 OpenGL 调用次数

## 未来规划

1. 集成 Assimp 库，支持更多模型格式
2. 实现现代 OpenGL 渲染，使用 VAO/VBO/Shader
3. 添加物理引擎支持
4. 实现更多几何建模和测量工具
5. 支持场景录制和回放功能

## 联系方式

- 项目负责人：
- 技术支持：
- 邮箱：
- 仓库地址：

## 许可证

MIT License

## 版本历史

- v1.0：初始版本，实现基本渲染功能

## 特技

1. 使用 Readme_XXX.md 来支持不同的语言，例如 Readme_en.md, Readme_zh.md
2. 详细的代码注释，方便理解和扩展
3. 模块化设计，便于维护和扩展
4. 高性能渲染，支持复杂场景


可以参考项目 Hazel 中的实现：https://github.com/TheCherno/Hazel