# OpenSceneGraph

**Repository Path**: icivic/openscenegraph

## Basic Information

- **Project Name**: OpenSceneGraph
- **Description**: OpenSceneGraph (OSG) 是一个高性能的开源3D图形渲染引擎，用于实时可视化大型复杂场景。它提供了一系列工具和库，用于创建、管理和渲染3D图形应用程序，广泛应用于模拟、游戏、可视化和科学计算等领域。  OSG 3.6.5 是该项目的一个稳定版本，具有良好的性能和广泛的平台支持，适合各种3D应用开发。
- **Primary Language**: C++
- **License**: LGPL-2.1
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-01-14
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenSceneGraph (OSG) 3.6.5

## 项目介绍

OpenSceneGraph (OSG) 是一个高性能的开源3D图形渲染引擎，用于实时可视化大型复杂场景。它提供了一系列工具和库，用于创建、管理和渲染3D图形应用程序，广泛应用于模拟、游戏、可视化和科学计算等领域。

OSG 3.6.5 是该项目的一个稳定版本，具有良好的性能和广泛的平台支持，适合各种3D应用开发。

## 主要功能特性

### 1. 高性能渲染
- 基于OpenGL的高效渲染实现
- 支持大规模场景管理
- 优化的几何体渲染管道
- 支持多线程渲染

### 2. 场景图形核心
- 灵活的场景图数据结构
- 丰富的节点类型（Group, Geode, Transform等）
- 高效的遍历机制
- 支持PagedLOD和LOD节点实现细节层次

### 3. 几何和材质
- 支持多种几何类型（Points, Lines, Triangles等）
- 丰富的材质和纹理支持
- 着色器支持（GLSL）
- 支持光照、阴影和雾化效果

### 4. 输入设备支持
- 鼠标、键盘事件处理
- 支持多种输入设备（游戏杆、VR控制器等）
- 内置的相机控制机制

### 5. 数据加载和插件系统
- 支持多种3D模型格式（OSG, 3DS, OBJ, COLLADA等）
- 支持多种图像格式（PNG, JPEG, TIFF, BMP等）
- 可扩展的插件系统

### 6. 跨平台支持
- 支持Windows、Linux和macOS
- 统一的API，简化跨平台开发

## 主要模块

### 1. 核心模块
- **OpenThreads**: 跨平台线程库
- **osg**: 核心场景图库
- **osgUtil**: 场景图工具和算法
- **osgDB**: 数据加载和插件系统
- **osgGA**: 图形应用支持

### 2. 可视化模块
- **osgViewer**: 3D视图和渲染窗口
- **osgText**: 3D文本渲染
- **osgShadow**: 阴影实现
- **osgFX**: 特效实现
- **osgParticle**: 粒子系统

### 3. 扩展模块
- **osgTerrain**: 地形渲染
- **osgVolume**: 体渲染
- **osgSim**: 模拟支持
- **osgAnimation**: 动画系统

## 编译环境和依赖

### 操作系统
- Windows 10/11
- Linux
- macOS

### 编译工具
- MSYS2 MinGW64 (Windows)
- GCC (Linux/macOS)
- Visual Studio (Windows, 可选)

### 依赖库
- OpenGL
- FontConfig
- 可选：FreeType, libpng, libjpeg, libtiff等

## 编译步骤（Windows + MSYS2 MinGW64）

### 1. 安装MSYS2和依赖

1. 下载并安装MSYS2：https://www.msys2.org/
2. 打开MSYS2 MinGW64终端
3. 更新系统包：
   ```bash
   pacman -Syu
   ```
4. 安装编译依赖：
   ```bash
   pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-make
   pacman -S mingw-w64-x86_64-opengl mingw-w64-x86_64-fontconfig
   ```

### 2. 配置CMake

```bash
mkdir -p build_new
cd build_new
cmake -G "MinGW Makefiles" \
    -DCMAKE_C_COMPILER="C:/msys64/mingw64/bin/cc.exe" \
    -DCMAKE_CXX_COMPILER="C:/msys64/mingw64/bin/c++.exe" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CXX_FLAGS="-Wno-deprecated-copy -Wno-overloaded-virtual -Wno-narrowing -D_SILENCE_CXX17_BYTE_DEPRECATION_WARNING -DWIN32_LEAN_AND_MEAN -DNOMINMAX" \
    -DBUILD_OSG_PLUGINS=OFF \
    -DBUILD_OSG_APPLICATIONS=OFF \
    -DBUILD_DOCUMENTATION=OFF \
    ../
```

### 3. 执行编译

```bash
C:/msys64/mingw64/bin/mingw32-make.exe -j8
```

## 编译过程中遇到的问题和解决方案

### 问题1：C++17兼容性问题
**症状**：编译时出现关于`std::byte`的错误，或"ISO C++17 does not allow 'register' storage class specifier"警告
**解决方案**：
- 添加编译标志 `-D_SILENCE_CXX17_BYTE_DEPRECATION_WARNING` 解决std::byte与Windows SDK中byte定义冲突
- 添加 `-Wno-narrowing` 禁用缩小转换警告
- 添加 `-Wno-deprecated` 或 `-Wno-register` 禁用register关键字警告

### 问题2：Windows SDK头文件冲突
**症状**：编译时出现关于宏定义冲突的错误，如"NOMINMAX"相关错误
**解决方案**：
- 添加 `-DWIN32_LEAN_AND_MEAN` 简化Windows头文件
- 添加 `-DNOMINMAX` 禁用Windows SDK中的min/max宏定义

### 问题3：插件构建错误
**症状**：编译插件时出现链接错误，如curl插件链接失败
**解决方案**：
- 禁用插件构建：`-DBUILD_OSG_PLUGINS=OFF`
- 或安装相应的依赖库，如curl

### 问题4：编译器警告过多
**症状**：编译过程中出现大量警告，影响编译体验
**解决方案**：
- 添加 `-Wno-deprecated-copy -Wno-overloaded-virtual` 禁用过时的编译器警告
- 或使用 `-w` 禁用所有警告（不推荐）

### 问题5：构建目录冲突
**症状**：重新编译时出现CMake配置错误
**解决方案**：
- 创建新的构建目录，如`build_new`
- 清理旧的构建目录后重新配置

## 编译结果

编译成功后，在`build_new/bin`目录下会生成以下核心库文件：
- `libOpenThreads.dll`
- `libosg.dll`
- `libosgDB.dll`
- `libosgFX.dll`
- `libosgGA.dll`
- `libosgParticle.dll`
- `libosgShadow.dll`
- `libosgTerrain.dll`
- `libosgText.dll`
- `libosgUtil.dll`
- `libosgViewer.dll`

## 安装和使用

### 安装步骤

编译成功后，可以使用以下命令安装OSG：

```bash
C:/msys64/mingw64/bin/mingw32-make.exe install
```

### 安装目录结构

编译成功后，OSG库将安装到指定的安装目录中：
- **头文件**：`install/include/osg`、`install/include/osgDB`等
- **库文件**：`install/lib`（静态库）和 `install/bin`（动态库）
- **示例代码**：`install/examples`（如果启用）

## 安装过程中遇到的问题和解决方案

### 问题1：默认安装路径需要管理员权限
**症状**：执行`mingw32-make install`时提示无法创建目录"C:/Program Files/OpenSceneGraph/.."
**解决方案**：
- 重新配置CMake，指定一个不需要管理员权限的安装路径
- 例如：`cmake -DCMAKE_INSTALL_PREFIX="../install" .`
- 然后重新执行`mingw32-make install`

### 问题2：安装过程中缺少依赖
**症状**：安装时提示缺少某些头文件或库文件
**解决方案**：
- 确保所有必要的依赖库都已安装
- 对于MSYS2，可以使用`pacman -S mingw-w64-x86_64-<package>`安装缺失的依赖

### 问题3：安装后找不到库文件
**症状**：编译使用OSG的项目时提示找不到OSG库
**解决方案**：
- 确保安装路径已正确添加到系统环境变量中
- 或在CMake项目中使用`-DOSG_DIR="<install_path>/cmake"`指定OSG安装路径
- 确保链接器能找到动态库文件（添加到PATH或复制到项目目录）

### 在项目中使用OSG

1. **包含头文件**：
   ```cpp
   #include <osg/Node>
   #include <osgViewer/Viewer>
   ```

2. **链接库**：
   - 确保OSG库目录在链接路径中
   - 链接所需的OSG库

3. **示例代码**：
   ```cpp
   #include <osgViewer/Viewer>
   #include <osgDB/ReadFile>

   int main() {
       // 创建Viewer对象
       osgViewer::Viewer viewer;
       
       // 加载模型文件
       osg::ref_ptr<osg::Node> root = osgDB::readNodeFile("cessna.osg");
       
       // 设置场景根节点
       viewer.setSceneData(root);
       
       // 运行渲染循环
       return viewer.run();
   }
   ```

## 示例应用

OSG 提供了丰富的示例应用，可以在`examples`目录下找到。这些示例演示了OSG的各种功能，包括：
- 基本场景图创建
- 模型加载和渲染
- 相机控制
- 特效实现
- 粒子系统
- 阴影效果

## 许可证

OSG 采用LGPL许可证发布，详见`LICENSE.txt`文件。

## 资源和支持

- **官方网站**：http://www.openscenegraph.org/
- **GitHub仓库**：https://github.com/openscenegraph/OpenSceneGraph
- **文档**：http://www.openscenegraph.org/index.php/documentation
- **论坛**：http://www.openscenegraph.org/index.php/support
- **邮件列表**：https://lists.openscenegraph.org/

## 贡献

欢迎通过GitHub提交问题报告和拉取请求来贡献代码。请遵循项目的贡献指南。

## 版本历史

OSG 3.6.5 是一个稳定版本，包含了许多bug修复和性能改进。建议从旧版本升级的用户查阅官方发布说明。

## 结语

OpenSceneGraph 3.6.5 是一个功能强大、性能优良的3D渲染引擎，适合各种3D应用开发。通过本文的编译指南和问题解决方案，您应该能够顺利在Windows环境下使用MSYS2 MinGW64编译和使用OSG库。

OSG的学习曲线可能较陡，但一旦掌握，它将成为您开发高性能3D应用的强大工具。建议初学者从官方示例开始学习，逐步掌握OSG的核心概念和使用方法。

祝您使用OSG开发出优秀的3D应用！