简介这是一份基于OSG与Qt的集成开发示例工程源自GitHub经作者在VS201764位环境下调试通过可直接运行。资源面向需要将OSG三维渲染能力嵌入Qt界面程序的开发者覆盖视图渲染、场景交互、模型加载与视角控制等常见功能模块。压缩包仅2.88MB共含72个文件以源码与工程配置为主17个cpp实现业务逻辑14个h头文件声明接口5个ui文件定义界面布局另有工程文件、资源文件及编译中间产物目录结构清晰便于对照学习。已有2347人学习下载适配具有一定C与Qt基础、希望快速掌握两者结合方式的中高级开发者。工程几乎囊括了OSG与Qt结合所需的主要功能点并提供了调试版本只需修改本机环境变量即可运行通过阅读源码与界面定义可系统理解OSGWidget、视图核心等模块的协作方式是一份能直接上手的实践范本。 OSG 和 Qt 的结合我一直觉得是被低估的组合。一边是 Qt 成熟的桌面界面和交互控件一边是 OSG 强大的三维场景管理两者都开源而且都有跨平台基因用 VS2017 的 64 位工具集把它们整合进同一套工程一句话说就是“用 Qt 做皮用 OSG 做骨”。我那时接到一个桌面仿真项目要求窗口左侧是导航菜单和属性面板右侧是三维场景还要支持鼠标拖拽、缩放、旋转模型。最初我脑子里第一反应是“直接用一个 OSG 独立窗口 Qt 主界面”但这样做窗口嵌套、消息传递会非常别扭尤其想要实现“场景内点击后联动右侧面板刷新数据”这种需求时两边各管各的窗口代码结构立刻就会乱。后来我改成让 OSG 渲染进 QOpenGLWidget所有东西都放进 Qt 的父子窗口体系里一分钟的工夫复杂度直接降了一个数量级。这篇文章不是教你从零学 OSG也不是 Qt 入门教材而是给那种已经会用 VS2017 写 C想在同一个窗口里把 OSG 场景和 Qt 控件揉在一起的人提供一个 64 位环境下能直接落地的方案。你会看到环境怎么搭、CMake 怎么写、渲染循环怎么对接、以及我在实际调试中踩过的几个很隐蔽的坑。代码风格偏向“抄了就能跑”但我会尽量把每个关键步骤背后的原因也讲清楚。1. 项目整体设计与思路拆解1.1 为什么要做 OSG Qt VS2017OSGOpenSceneGraph本身是一个场景图库主要管三维场景的组织、几何体绘制、模型加载、相机调度这些事。Qt 负责的是窗口框架、对话框、菜单栏、状态栏、事件循环这些偏业务的东西。两者如果各干各的做演示程序没问题但放到真实的桌面工具软件里几乎没有项目敢接受“三维窗口独立弹出和主界面毫无关系”这种形态。我当时在做的仿真工具核心诉求是左侧操作参数右侧实时看到三维结果并且交互要双向在三维场景里点击一个对象左侧属性表马上显示该对象的信息。这就要求两个库共享一个窗口、共享一个事件循环。VS2017 作为编译环境是因为团队里现有的中间件、第三方库全都围绕这一代 MSVC 工具集编译我不太可能为了 OSG 单独换一套开发环境。64 位则不用多解释模型数据一大单个三维场景占几个 GB 内存很常见32 位进程直接写不下去何况 OSG 在 Release 模式下对多线程的支持也需要一个完整的内存空间。1.2 技术路线选择osgQt 还是 QOpenGLWidget网上提到 OSG 和 Qt 结合大概率会看到两个方向旧一点的资料会直接用osgQt库里的QGLWidget子类把 OSG 渲染绑定到一个继承自 Qt 的窗口上新一点的方案是自己写一个QOpenGLWidget子类在initializeGL/paintGL里把 OSG 的 Viewer 接进来。我选择的是后面这条路线原因有两点。第一osgQt在 OSG 3.6 版本里已经不是默认编译组件需要额外打开 CMake 选项如果编译时没注意后面整个工程都会卡在“找不到 osgQt 依赖”上第二基于QGLWidget的老写法在很多地方依赖已经过时的 OpenGL 固定管线接口放到 VS2017 Qt 5.12 环境下容易出现兼容性问题而QOpenGLWidget是 Qt 官方主推的新式 OpenGL 集成方式生命周期管理、上下文切换都比老类清晰得多。所以就算osgQt看起来“开箱即用”我也建议多花二十分钟自己封装一个QOpenGLWidget。1.3 为什么一定是 64 位标题里专门强调“64位”因为在 VS2017 里新建工程默认的活动解决方案平台是 Win32很多人第一时间没切到 x64结果链接时就会报一堆“无法解析的外部符号”。而且 Qt 官方针对 VS2017 发布的二进制包是有明确区分的msvc2017指 32 位msvc2017_64才是 64 位。如果下载错了 Qt 版本哪怕代码写得再对链接阶段也会因为库架构不一致而失败。另外OSG 在 64 位下对内存映射和模型加载的稳定性明显更好。你可以把 64 位理解成把仓库从单车道改成了八车道平时看不出区别一旦摄像头扫描的点云、地形切片、纹理贴图一起加载差别就非常真实。后面所有命令、路径、库文件我都默认使用 64 位版本。2. 环境准备与依赖编译2.1 依赖清单与版本对照为了避免“版本匹配”这种最浪费时间的问题我把自己最终跑通的组合直接列出来。严格按这个组合来可以少碰很多莫名其妙的错误。依赖项版本建议说明Visual StudioVS2017 v15.9安装“使用 C 的桌面开发”工作负载工具集对应 v141兼容性最稳Qt5.12.2选择 msvc2017_64 预编译包不要选 MinGW 版本VS 无法直接使用CMake3.16 及以上专门用于编译 OSG 和生成 VS 工程OSG3.6.5 源码包同时包含 OpenThreads、osgDB、osgViewer 等模块第三方库zlib、libpng、libjpeg、freetype、gdal 等按需如果不做地形和图片格式扩展可以先不装OSG 会自动跳过这里特别提醒一句Qt 的安装路径不要带中文、不要带空格最好也不要放在 Program Files 这种受保护目录下。OSG 源码解压路径同理。我用的是D:/Qt/5.12.2/msvc2017_64和D:/OSG/build所有 CMake 配置都能一步到位省去了大量权限问题。2.2 OSG 源码编译的 CMake 配置OSG 编译过程不复杂但容易在选项上翻车。我的做法是用 CMake GUI 打开 OSG 源码目录设置构建目录为D:/OSG/build。点击 Configure选择“Visual Studio 15 2017 Win64”。这一步看似不起眼实际上等于把所有库的生成目标强制切成 64 位。找到ACTUAL_3RDPARTY_DIR如果之前安装了第三方库就指过去没装就留空。不安装第三方库OSG 依然能编译只是导入模型时某些格式比如 JPEG 纹理会失效。确认BUILD_OSG_VIEWER、BUILD_OSGDB、BUILD_OSGGA、BUILD_OSGUTIL等核心模块都处于勾选状态。如果之后想用osgQt里的 GraphicsWindowQt需要勾选OSG_USE_QT并指定Qt5_DIR让它指向 Qt 的lib/cmake/Qt5目录。但按我的方案这一步可以不勾。Configure 完成后直接 Generate然后用 VS2017 打开生成的OpenSceneGraph.sln选择 Release x64右键ALL_BUILD编译。编译时间取决于机器配置一般十几分钟到半小时。过程中偶尔会报某些第三方模块找不到只要不是核心包直接在 CMake 里取消对应选项即可不必死磕。编译完成后再把INSTALL项目编译一次把 OSG 头文件、库文件、DLL 统一输出到D:/OSG/install后面 CMake 引用就很干净了。2.3 环境变量与目录规划我把整个工程分成三个目录src放源码thirdparty放 Qt 和 OSGbin放最终生成的 exe 和运行时要用的 DLL。目录规划在项目早期越清晰后面 CMake 和调试就越省心。Windows 下运行时系统会按照 PATH 环境变量找 DLL。我建议把下面两个目录加进系统的 PATHD:/Qt/5.12.2/msvc2017_64/bin D:/OSG/install/bin这样 VS2017 直接 F5 启动调试时Qt5Core.dll、osgViewerd.dll 这类运行库才能被顺利找到。如果不想改系统 PATH也可以在工程属性环境的“调试 环境”里写PATH...但每次换机器都要重新配不如一次性加到系统变量里省事。3. 核心代码实现与实操步骤3.1 工程文件 CMakeLists.txt 配置我全程用 CMake 生成 VS2017 工程而不是手动新建空项目再配路径。手动配置的毛病是“这台上帝那台地狱”换一台电脑就漏库。CMake 文件写好后任何机器只要改几个路径就能重建工程。cmake_minimum_required(VERSION 3.10) project(OSGQtExample) set(CMAKE_CXX_STANDARD 14) set(QT_DIR D:/Qt/5.12.2/msvc2017_64) set(OSG_DIR D:/OSG/install) set(CMAKE_PREFIX_PATH ${QT_DIR} ${OSG_DIR}) find_package(Qt5 REQUIRED COMPONENTS Widgets OpenGL) find_package(osg REQUIRED) find_package(OpenThreads REQUIRED) include_directories( ${OSG_DIR}/include ${QT_DIR}/include ) link_directories(${OSG_DIR}/lib) add_executable(${PROJECT_NAME} WIN32 main.cpp OSGWidget.cpp ) target_link_libraries(${PROJECT_NAME} Qt5::Widgets Qt5::OpenGL osgDB osgViewer osgGA osgUtil OpenThreads )这段配置里link_directories(${OSG_DIR}/lib)非常关键。因为 OSG 提供的 CMake 配置文件版本不同有时候find_package(osg)找不到默认库目录手动指定可以兜底。WIN32关键字让程序不弹出控制台黑窗口但如果你还没到发布阶段想先看 qDebug 输出建议暂时去掉。3.2 QOpenGLWidget 集成 OSG 渲染循环核心工作都在OSGWidget这个类里。先看头文件#pragma once #include QOpenGLWidget #include QTimer #include osgViewer/Viewer #include osgGA/TrackballManipulator class OSGWidget : public QOpenGLWidget { Q_OBJECT public: explicit OSGWidget(QWidget* parent nullptr); protected: void initializeGL() override; void paintGL() override; void resizeGL(int w, int h) override; void mousePressEvent(QMouseEvent* event) override; void mouseMoveEvent(QMouseEvent* event) override; void mouseReleaseEvent(QMouseEvent* event) override; void wheelEvent(QWheelEvent* event) override; private: osg::ref_ptrosgViewer::Viewer _viewer; QTimer _timer; };构造函数里把_timer连到update()每 16 毫秒触发一次重绘OSGWidget::OSGWidget(QWidget* parent) : QOpenGLWidget(parent) { setFocusPolicy(Qt::StrongFocus); connect(_timer, QTimer::timeout, this, static_castvoid (QWidget::*)()(QWidget::update)); _timer.start(16); }initializeGL是初始化的重点核心操作是创建嵌入式 GraphicsContext 并绑定到当前 Qt 窗口上void OSGWidget::initializeGL() { _viewer new osgViewer::Viewer; osg::ref_ptrosgViewer::GraphicsWindowEmbedded gw new osgViewer::GraphicsWindowEmbedded(0, 0, width(), height()); osg::Camera* camera _viewer-getCamera(); camera-setGraphicsContext(gw); camera-setViewport(0, 0, width(), height()); camera-setProjectionMatrixAsPerspective( 45.0, static_castdouble(width()) / static_castdouble(height()), 0.1, 1000.0); camera-setClearColor(osg::Vec4(0.18f, 0.22f, 0.28f, 1.0f)); osg::ref_ptrosg::Node scene osgDB::readNodeFile(cow.osg); if (!scene) { osg::ref_ptrosg::Geode geode new osg::Geode; geode-addDrawable(new osg::ShapeDrawable(new osg::Box(osg::Vec3(), 1.0f))); scene geode; } _viewer-setSceneData(scene); _viewer-setCameraManipulator(new osgGA::TrackballManipulator); _viewer-setThreadingModel(osgViewer::Viewer::SingleThreaded); _viewer-setRunFrameScheme(osgViewer::ViewerBase::ON_DEMAND); }这里有两个坑必须解释。第一setThreadingModel(osgViewer::Viewer::SingleThreaded)是必须的OSG 默认可能是多线程渲染而 Qt 的 QOpenGLWidget 希望所有 OpenGL 调用都发生在 GUI 线程的 paintGL 里如果 OSG 自己开辟渲染线程轻则黑屏重则直接崩溃。第二GraphicsWindowEmbedded构造时的宽高要和 widget 当前宽高一致后续窗口大小变化时必须在 resizeGL 里同步更新视口参数。paintGL 里其实就一句话void OSGWidget::paintGL() { if (_viewer.valid()) { _viewer-frame(); } }QOpenGLWidget 本身已经做好了上下文绑定和交换缓冲区OSG 的frame()只是把当前帧的绘制命令提交到当前 GL 上下文。这也是 QOpenGLWidget 方案最干净的地方——你不用关心窗口句柄、设备上下文、调色板这些传统 OpenGL 的乱账。3.3 输入事件转接与视口自适应鼠标事件不能直接让 QOpenGLWidget 处理因为 OSG 的视口操作器只认osgGA::EventQueue里的事件。我们需要把 Qt 的事件转换成 OSG 的事件void OSGWidget::mousePressEvent(QMouseEvent* event) { if (!_viewer.valid()) return; double x event-pos().x(); double y event-pos().y(); unsigned int button 0; if (event-button() Qt::LeftButton) button 1; else if (event-button() Qt::MiddleButton) button 2; else if (event-button() Qt::RightButton) button 3; _viewer-getEventQueue()-mouseButtonPress(x, y, button); } void OSGWidget::mouseMoveEvent(QMouseEvent* event) { if (_viewer.valid()) _viewer-getEventQueue()-mouseMotion(event-pos().x(), event-pos().y()); } void OSGWidget::mouseReleaseEvent(QMouseEvent* event) { if (!_viewer.valid()) return; // 与按下类似release 用同样的 button 编号 } void OSGWidget::wheelEvent(QWheelEvent* event) { if (_viewer.valid()) _viewer-getEventQueue()-mouseScroll( osgGA::GUIEventAdapter::SCROLL_UP, event-angleDelta().y()); }坐标这里有个容易忽略的点Qt 的pos()原点在窗口左上角OSG 鼠标事件的默认坐标原点也在左上角两者方向一致所以可以直接传。如果你用某些需要原点在左下角的 OpenGL 教程写法三维场景的旋转方向会反过来操作起来很别扭。视口自适应的代码如下放在成员函数上移动无需在 widgetvoid OSGWidget::resizeGL(int w, int h) { if (!_viewer.valid()) return; osg::Camera* camera _viewer-getCamera(); camera-setViewport(0, 0, w, h); camera-setProjectionMatrixAsPerspective( 45.0, static_castdouble(w) / static_castdouble(h), 0.1, 1000.0); osgViewer::GraphicsWindow* gw dynamic_castosgViewer::GraphicsWindow*(camera-getGraphicsContext()); if (gw) gw-resized(0, 0, w, h); }resized这一步很多人会漏漏掉的后果是窗口拉大后三维场景的画面会被拉伸变形因为 OSG 内部的 GraphicsContext 还停留在旧尺寸上。3.4 在同一个面板里扩展 QCustomPlot既然是和 Qt 结合实际项目中很少只放一个三维窗口。我那个项目里还需要把传感器采集到的波形实时显示出来Qt 侧我用 QCustomPlot 画时域波形需要看频谱时再用 kissfft 或 QCustomPlot 自带的 FFT 示例做频域转换。两者的关系和 OSG 完全不冲突因为三维场景归 QOpenGLWidget二维图表归普通 Widget我用 QSplitter 左右一摆刷新逻辑互不干扰。如果你也想并行集成 QCustomPlot建议它放在独立的QWidget上不要试图用 OSG 的 OpenGL 上下文去画 2D。原因是 QCustomPlot 默认走的是 QPainter 软件渲染放在同一个 widget 里会反复切换 GL 上下文交互体验下降而且 DEBUG 会看到一堆上下文警告。工程结构上保持“一个 OpenGL 区域一个普通 2D 区域中间用信号槽通信”是最容易维护的形态。4. 打包发布与常见问题排查4.1 windeployqt 与 OSG 运行时文件调试模式下程序能跑只是第一步。发布到别的电脑就是另一场“找 DLL”的战役。Qt 官方提供了windeployqt.exe它位于 Qt 安装目录的bin下用法非常简单先把自己的 exe 编译成 Release 版本然后打开 Qt 的命令行环境进入 exe 所在目录执行windeployqt OSGQtExample.exe命令会自动把 Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll以及platforms/qwindows.dll等运行组件复制到 exe 旁边。之后再把 OSG 的 release DLL 从D:/OSG/install/bin复制过去常见的有osgViewer.dll、osgDB.dll、osgGA.dll、osgUtil.dll、OpenThreads.dll如果加载了模型格式插件还需要osgPlugins-3.6.5整个目录。这个目录要放在 exe 同级的根目录下否则 OSG 找不到插件模型加载会静默失败。4.2 “Qt platform plugin could not be initialized”这类错误的处理很多人在刚接触 Qt 打包时会看到一句经典报错This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.这句话的直白翻译是exe 找到了 Qt5Core.dll但找不到platforms/qwindows.dll或者这个插件和你用的 Qt 版本文件不匹配。解决方法分两步检查第一exe 旁边必须有platforms文件夹里面放qwindows.dll第二qwindows.dll必须和 exe 使用同一套 Qt 版本编译千万不要从网上随手复制一个。用windeployqt生成时它会自动做好这件事。如果还报检查 release 编译时是否误链接了 debug 版 Qt 库。例如项目链接到Qt5Widgetsd.lib但发布的 DLL 是Qt5Widgets.dll没有 d 后缀就会出现类似问题。把工程切换到 Release 再重新生成一遍基本能解决。4.3 Debug/Release、Win32/x64 混用造成的坑VS2017 里最气人的错误不是你写错了代码而是库混用。比如 OSG 编译的是 Release x64Qt 用的是 Debug 版Qt5Cored.dll链接阶段可能不报错但运行时要么内存访问异常要么某些字符串函数直接崩溃。OSG 的库名是有规律的Release 版叫osgViewer.libDebug 版叫osgViewerd.lib。如果你的 CMake 配置写死了osgViewer但 VS 配置是 Debug就会报找不到库文件或者在混合模式下链接出问题。我的建议是整个工程统一用 Release x64 编译。Qt 在这套组合下带来的调试信息其实已经够用了Debug 版的性能反而可能影响三维场景操作手感。32 位和 64 位就更不用说x64配置下不要出现任何指向x86目录的第三方库路径否则时不时冒出的“操作数类型冲突”会让你怀疑是不是代码写错了。问题表现可能原因处理方式启动后提示缺少 Qt5Core.dllPATH 未包含 Qt bin 目录或未发布 Qt DLL设置 PATH或执行 windeployqt无法加载平台插件缺少 platforms/qwindows.dll重新执行 windeployqt复制整个 platforms 目录三维窗口黑屏但控件正常线程模型未设为 SingleThreaded或 resize 未同步强制 SingleThreaded并在 resizeGL 中调用 gw-resized链接时找不到 osgViewer.libCMake 的 OSG_DIR 指向构建目录而非 install 目录确认 OSG_DIR 指向include和lib所在目录打开 exe 时崩溃记录停在 Qt 消息循环Debug/Release 库混合编译全部统一为 Release x64检查 Qt 版本是 msvc2017_64模型读取成功但没有纹理第三方库未编译或 osgPlugins 目录缺失编译 OSG 时启用 libpng/libjpeg发布时复制插件目录5. 实操心得与经验补充5.1 几个让我少走弯路的细节第一个细节是不要迷信最新版本。Qt 6 都出来很久了如果要和 OSG 搭配我还是会选择 Qt 5.12 到 5.15 之间。原因是 OSG 3.6 系列对 Qt5 的支持最成熟很多网上案例都是基于这组版本写的遇到问题容易搜到解决方案。Qt 6 把很多 OpenGL 相关接口改了和老 OSG 版本结合时不付出额外兼容成本犯不上。第二个细节是在代码里加异常日志。我在 OSG 代码和 Qt 事件转发里都插入了简单的qInfo()输出比如按下鼠标时打印坐标模型加载失败时打印原因。这些日志看着不高级但你在“三维场景不动”和“鼠标没反应”之间做判断时能第一时间定位是 OSG 没渲染还是事件没转发过去。省下的排查时间远超写日志的几分钟。第三个细节如果调试过程中发现 OSG 场景加载比较慢不要每次重新运行程序都重新读模型。我在开发阶段把模型文件放到程序工作目录下路径用相对路径并让 OSG 的osgDB::readNodeFile加上osgDB::Registry::instance()-getDataFilePathList().push_back(data)这样既方便调试也方便后续拷贝到别的机器。5.2 从单一例子扩展到完整业务系统当你把 QOpenGLWidget 和 OSG 的桥接代码跑通一次后这套结构其实可以复用到很多方向。比如把setSceneData里的静态模型换成实时点云就能做数据可视化工具把鼠标点击事件通过 Qt 信号转发出去点击某个三维物体后更新右侧表格就实现了二维和三维的数据联动在 OSG 场景外再叠加一个 QCustomPlot 面板把时域波形实时转成频域频谱就是一个带三维姿态显示的信号分析软件。我自己的习惯是把OSGWidget封装成一个独立的 Qt 插件模块内部不写任何业务逻辑只开放几个方法loadModel、setCameraManipulator、setSceneData以及一个signalPickNode信号。这样项目换到另一个三维仿真系统时直接把这个模块拖过去业务层完全不用大改。集成 OSG 和 Qt 本身只是第一步真正的价值在于把三维能力和交互能力都变成可复用的组件。本文还有配套的精品资源点击获取
简介这是一份基于OSG与Qt的集成开发示例工程源自GitHub经作者在VS201764位环境下调试通过可直接运行。资源面向需要将OSG三维渲染能力嵌入Qt界面程序的开发者覆盖视图渲染、场景交互、模型加载与视角控制等常见功能模块。压缩包仅2.88MB共含72个文件以源码与工程配置为主17个cpp实现业务逻辑14个h头文件声明接口5个ui文件定义界面布局另有工程文件、资源文件及编译中间产物目录结构清晰便于对照学习。已有2347人学习下载适配具有一定C与Qt基础、希望快速掌握两者结合方式的中高级开发者。工程几乎囊括了OSG与Qt结合所需的主要功能点并提供了调试版本只需修改本机环境变量即可运行通过阅读源码与界面定义可系统理解OSGWidget、视图核心等模块的协作方式是一份能直接上手的实践范本。 OSG 和 Qt 的结合我一直觉得是被低估的组合。一边是 Qt 成熟的桌面界面和交互控件一边是 OSG 强大的三维场景管理两者都开源而且都有跨平台基因用 VS2017 的 64 位工具集把它们整合进同一套工程一句话说就是“用 Qt 做皮用 OSG 做骨”。我那时接到一个桌面仿真项目要求窗口左侧是导航菜单和属性面板右侧是三维场景还要支持鼠标拖拽、缩放、旋转模型。最初我脑子里第一反应是“直接用一个 OSG 独立窗口 Qt 主界面”但这样做窗口嵌套、消息传递会非常别扭尤其想要实现“场景内点击后联动右侧面板刷新数据”这种需求时两边各管各的窗口代码结构立刻就会乱。后来我改成让 OSG 渲染进 QOpenGLWidget所有东西都放进 Qt 的父子窗口体系里一分钟的工夫复杂度直接降了一个数量级。这篇文章不是教你从零学 OSG也不是 Qt 入门教材而是给那种已经会用 VS2017 写 C想在同一个窗口里把 OSG 场景和 Qt 控件揉在一起的人提供一个 64 位环境下能直接落地的方案。你会看到环境怎么搭、CMake 怎么写、渲染循环怎么对接、以及我在实际调试中踩过的几个很隐蔽的坑。代码风格偏向“抄了就能跑”但我会尽量把每个关键步骤背后的原因也讲清楚。1. 项目整体设计与思路拆解1.1 为什么要做 OSG Qt VS2017OSGOpenSceneGraph本身是一个场景图库主要管三维场景的组织、几何体绘制、模型加载、相机调度这些事。Qt 负责的是窗口框架、对话框、菜单栏、状态栏、事件循环这些偏业务的东西。两者如果各干各的做演示程序没问题但放到真实的桌面工具软件里几乎没有项目敢接受“三维窗口独立弹出和主界面毫无关系”这种形态。我当时在做的仿真工具核心诉求是左侧操作参数右侧实时看到三维结果并且交互要双向在三维场景里点击一个对象左侧属性表马上显示该对象的信息。这就要求两个库共享一个窗口、共享一个事件循环。VS2017 作为编译环境是因为团队里现有的中间件、第三方库全都围绕这一代 MSVC 工具集编译我不太可能为了 OSG 单独换一套开发环境。64 位则不用多解释模型数据一大单个三维场景占几个 GB 内存很常见32 位进程直接写不下去何况 OSG 在 Release 模式下对多线程的支持也需要一个完整的内存空间。1.2 技术路线选择osgQt 还是 QOpenGLWidget网上提到 OSG 和 Qt 结合大概率会看到两个方向旧一点的资料会直接用osgQt库里的QGLWidget子类把 OSG 渲染绑定到一个继承自 Qt 的窗口上新一点的方案是自己写一个QOpenGLWidget子类在initializeGL/paintGL里把 OSG 的 Viewer 接进来。我选择的是后面这条路线原因有两点。第一osgQt在 OSG 3.6 版本里已经不是默认编译组件需要额外打开 CMake 选项如果编译时没注意后面整个工程都会卡在“找不到 osgQt 依赖”上第二基于QGLWidget的老写法在很多地方依赖已经过时的 OpenGL 固定管线接口放到 VS2017 Qt 5.12 环境下容易出现兼容性问题而QOpenGLWidget是 Qt 官方主推的新式 OpenGL 集成方式生命周期管理、上下文切换都比老类清晰得多。所以就算osgQt看起来“开箱即用”我也建议多花二十分钟自己封装一个QOpenGLWidget。1.3 为什么一定是 64 位标题里专门强调“64位”因为在 VS2017 里新建工程默认的活动解决方案平台是 Win32很多人第一时间没切到 x64结果链接时就会报一堆“无法解析的外部符号”。而且 Qt 官方针对 VS2017 发布的二进制包是有明确区分的msvc2017指 32 位msvc2017_64才是 64 位。如果下载错了 Qt 版本哪怕代码写得再对链接阶段也会因为库架构不一致而失败。另外OSG 在 64 位下对内存映射和模型加载的稳定性明显更好。你可以把 64 位理解成把仓库从单车道改成了八车道平时看不出区别一旦摄像头扫描的点云、地形切片、纹理贴图一起加载差别就非常真实。后面所有命令、路径、库文件我都默认使用 64 位版本。2. 环境准备与依赖编译2.1 依赖清单与版本对照为了避免“版本匹配”这种最浪费时间的问题我把自己最终跑通的组合直接列出来。严格按这个组合来可以少碰很多莫名其妙的错误。依赖项版本建议说明Visual StudioVS2017 v15.9安装“使用 C 的桌面开发”工作负载工具集对应 v141兼容性最稳Qt5.12.2选择 msvc2017_64 预编译包不要选 MinGW 版本VS 无法直接使用CMake3.16 及以上专门用于编译 OSG 和生成 VS 工程OSG3.6.5 源码包同时包含 OpenThreads、osgDB、osgViewer 等模块第三方库zlib、libpng、libjpeg、freetype、gdal 等按需如果不做地形和图片格式扩展可以先不装OSG 会自动跳过这里特别提醒一句Qt 的安装路径不要带中文、不要带空格最好也不要放在 Program Files 这种受保护目录下。OSG 源码解压路径同理。我用的是D:/Qt/5.12.2/msvc2017_64和D:/OSG/build所有 CMake 配置都能一步到位省去了大量权限问题。2.2 OSG 源码编译的 CMake 配置OSG 编译过程不复杂但容易在选项上翻车。我的做法是用 CMake GUI 打开 OSG 源码目录设置构建目录为D:/OSG/build。点击 Configure选择“Visual Studio 15 2017 Win64”。这一步看似不起眼实际上等于把所有库的生成目标强制切成 64 位。找到ACTUAL_3RDPARTY_DIR如果之前安装了第三方库就指过去没装就留空。不安装第三方库OSG 依然能编译只是导入模型时某些格式比如 JPEG 纹理会失效。确认BUILD_OSG_VIEWER、BUILD_OSGDB、BUILD_OSGGA、BUILD_OSGUTIL等核心模块都处于勾选状态。如果之后想用osgQt里的 GraphicsWindowQt需要勾选OSG_USE_QT并指定Qt5_DIR让它指向 Qt 的lib/cmake/Qt5目录。但按我的方案这一步可以不勾。Configure 完成后直接 Generate然后用 VS2017 打开生成的OpenSceneGraph.sln选择 Release x64右键ALL_BUILD编译。编译时间取决于机器配置一般十几分钟到半小时。过程中偶尔会报某些第三方模块找不到只要不是核心包直接在 CMake 里取消对应选项即可不必死磕。编译完成后再把INSTALL项目编译一次把 OSG 头文件、库文件、DLL 统一输出到D:/OSG/install后面 CMake 引用就很干净了。2.3 环境变量与目录规划我把整个工程分成三个目录src放源码thirdparty放 Qt 和 OSGbin放最终生成的 exe 和运行时要用的 DLL。目录规划在项目早期越清晰后面 CMake 和调试就越省心。Windows 下运行时系统会按照 PATH 环境变量找 DLL。我建议把下面两个目录加进系统的 PATHD:/Qt/5.12.2/msvc2017_64/bin D:/OSG/install/bin这样 VS2017 直接 F5 启动调试时Qt5Core.dll、osgViewerd.dll 这类运行库才能被顺利找到。如果不想改系统 PATH也可以在工程属性环境的“调试 环境”里写PATH...但每次换机器都要重新配不如一次性加到系统变量里省事。3. 核心代码实现与实操步骤3.1 工程文件 CMakeLists.txt 配置我全程用 CMake 生成 VS2017 工程而不是手动新建空项目再配路径。手动配置的毛病是“这台上帝那台地狱”换一台电脑就漏库。CMake 文件写好后任何机器只要改几个路径就能重建工程。cmake_minimum_required(VERSION 3.10) project(OSGQtExample) set(CMAKE_CXX_STANDARD 14) set(QT_DIR D:/Qt/5.12.2/msvc2017_64) set(OSG_DIR D:/OSG/install) set(CMAKE_PREFIX_PATH ${QT_DIR} ${OSG_DIR}) find_package(Qt5 REQUIRED COMPONENTS Widgets OpenGL) find_package(osg REQUIRED) find_package(OpenThreads REQUIRED) include_directories( ${OSG_DIR}/include ${QT_DIR}/include ) link_directories(${OSG_DIR}/lib) add_executable(${PROJECT_NAME} WIN32 main.cpp OSGWidget.cpp ) target_link_libraries(${PROJECT_NAME} Qt5::Widgets Qt5::OpenGL osgDB osgViewer osgGA osgUtil OpenThreads )这段配置里link_directories(${OSG_DIR}/lib)非常关键。因为 OSG 提供的 CMake 配置文件版本不同有时候find_package(osg)找不到默认库目录手动指定可以兜底。WIN32关键字让程序不弹出控制台黑窗口但如果你还没到发布阶段想先看 qDebug 输出建议暂时去掉。3.2 QOpenGLWidget 集成 OSG 渲染循环核心工作都在OSGWidget这个类里。先看头文件#pragma once #include QOpenGLWidget #include QTimer #include osgViewer/Viewer #include osgGA/TrackballManipulator class OSGWidget : public QOpenGLWidget { Q_OBJECT public: explicit OSGWidget(QWidget* parent nullptr); protected: void initializeGL() override; void paintGL() override; void resizeGL(int w, int h) override; void mousePressEvent(QMouseEvent* event) override; void mouseMoveEvent(QMouseEvent* event) override; void mouseReleaseEvent(QMouseEvent* event) override; void wheelEvent(QWheelEvent* event) override; private: osg::ref_ptrosgViewer::Viewer _viewer; QTimer _timer; };构造函数里把_timer连到update()每 16 毫秒触发一次重绘OSGWidget::OSGWidget(QWidget* parent) : QOpenGLWidget(parent) { setFocusPolicy(Qt::StrongFocus); connect(_timer, QTimer::timeout, this, static_castvoid (QWidget::*)()(QWidget::update)); _timer.start(16); }initializeGL是初始化的重点核心操作是创建嵌入式 GraphicsContext 并绑定到当前 Qt 窗口上void OSGWidget::initializeGL() { _viewer new osgViewer::Viewer; osg::ref_ptrosgViewer::GraphicsWindowEmbedded gw new osgViewer::GraphicsWindowEmbedded(0, 0, width(), height()); osg::Camera* camera _viewer-getCamera(); camera-setGraphicsContext(gw); camera-setViewport(0, 0, width(), height()); camera-setProjectionMatrixAsPerspective( 45.0, static_castdouble(width()) / static_castdouble(height()), 0.1, 1000.0); camera-setClearColor(osg::Vec4(0.18f, 0.22f, 0.28f, 1.0f)); osg::ref_ptrosg::Node scene osgDB::readNodeFile(cow.osg); if (!scene) { osg::ref_ptrosg::Geode geode new osg::Geode; geode-addDrawable(new osg::ShapeDrawable(new osg::Box(osg::Vec3(), 1.0f))); scene geode; } _viewer-setSceneData(scene); _viewer-setCameraManipulator(new osgGA::TrackballManipulator); _viewer-setThreadingModel(osgViewer::Viewer::SingleThreaded); _viewer-setRunFrameScheme(osgViewer::ViewerBase::ON_DEMAND); }这里有两个坑必须解释。第一setThreadingModel(osgViewer::Viewer::SingleThreaded)是必须的OSG 默认可能是多线程渲染而 Qt 的 QOpenGLWidget 希望所有 OpenGL 调用都发生在 GUI 线程的 paintGL 里如果 OSG 自己开辟渲染线程轻则黑屏重则直接崩溃。第二GraphicsWindowEmbedded构造时的宽高要和 widget 当前宽高一致后续窗口大小变化时必须在 resizeGL 里同步更新视口参数。paintGL 里其实就一句话void OSGWidget::paintGL() { if (_viewer.valid()) { _viewer-frame(); } }QOpenGLWidget 本身已经做好了上下文绑定和交换缓冲区OSG 的frame()只是把当前帧的绘制命令提交到当前 GL 上下文。这也是 QOpenGLWidget 方案最干净的地方——你不用关心窗口句柄、设备上下文、调色板这些传统 OpenGL 的乱账。3.3 输入事件转接与视口自适应鼠标事件不能直接让 QOpenGLWidget 处理因为 OSG 的视口操作器只认osgGA::EventQueue里的事件。我们需要把 Qt 的事件转换成 OSG 的事件void OSGWidget::mousePressEvent(QMouseEvent* event) { if (!_viewer.valid()) return; double x event-pos().x(); double y event-pos().y(); unsigned int button 0; if (event-button() Qt::LeftButton) button 1; else if (event-button() Qt::MiddleButton) button 2; else if (event-button() Qt::RightButton) button 3; _viewer-getEventQueue()-mouseButtonPress(x, y, button); } void OSGWidget::mouseMoveEvent(QMouseEvent* event) { if (_viewer.valid()) _viewer-getEventQueue()-mouseMotion(event-pos().x(), event-pos().y()); } void OSGWidget::mouseReleaseEvent(QMouseEvent* event) { if (!_viewer.valid()) return; // 与按下类似release 用同样的 button 编号 } void OSGWidget::wheelEvent(QWheelEvent* event) { if (_viewer.valid()) _viewer-getEventQueue()-mouseScroll( osgGA::GUIEventAdapter::SCROLL_UP, event-angleDelta().y()); }坐标这里有个容易忽略的点Qt 的pos()原点在窗口左上角OSG 鼠标事件的默认坐标原点也在左上角两者方向一致所以可以直接传。如果你用某些需要原点在左下角的 OpenGL 教程写法三维场景的旋转方向会反过来操作起来很别扭。视口自适应的代码如下放在成员函数上移动无需在 widgetvoid OSGWidget::resizeGL(int w, int h) { if (!_viewer.valid()) return; osg::Camera* camera _viewer-getCamera(); camera-setViewport(0, 0, w, h); camera-setProjectionMatrixAsPerspective( 45.0, static_castdouble(w) / static_castdouble(h), 0.1, 1000.0); osgViewer::GraphicsWindow* gw dynamic_castosgViewer::GraphicsWindow*(camera-getGraphicsContext()); if (gw) gw-resized(0, 0, w, h); }resized这一步很多人会漏漏掉的后果是窗口拉大后三维场景的画面会被拉伸变形因为 OSG 内部的 GraphicsContext 还停留在旧尺寸上。3.4 在同一个面板里扩展 QCustomPlot既然是和 Qt 结合实际项目中很少只放一个三维窗口。我那个项目里还需要把传感器采集到的波形实时显示出来Qt 侧我用 QCustomPlot 画时域波形需要看频谱时再用 kissfft 或 QCustomPlot 自带的 FFT 示例做频域转换。两者的关系和 OSG 完全不冲突因为三维场景归 QOpenGLWidget二维图表归普通 Widget我用 QSplitter 左右一摆刷新逻辑互不干扰。如果你也想并行集成 QCustomPlot建议它放在独立的QWidget上不要试图用 OSG 的 OpenGL 上下文去画 2D。原因是 QCustomPlot 默认走的是 QPainter 软件渲染放在同一个 widget 里会反复切换 GL 上下文交互体验下降而且 DEBUG 会看到一堆上下文警告。工程结构上保持“一个 OpenGL 区域一个普通 2D 区域中间用信号槽通信”是最容易维护的形态。4. 打包发布与常见问题排查4.1 windeployqt 与 OSG 运行时文件调试模式下程序能跑只是第一步。发布到别的电脑就是另一场“找 DLL”的战役。Qt 官方提供了windeployqt.exe它位于 Qt 安装目录的bin下用法非常简单先把自己的 exe 编译成 Release 版本然后打开 Qt 的命令行环境进入 exe 所在目录执行windeployqt OSGQtExample.exe命令会自动把 Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll以及platforms/qwindows.dll等运行组件复制到 exe 旁边。之后再把 OSG 的 release DLL 从D:/OSG/install/bin复制过去常见的有osgViewer.dll、osgDB.dll、osgGA.dll、osgUtil.dll、OpenThreads.dll如果加载了模型格式插件还需要osgPlugins-3.6.5整个目录。这个目录要放在 exe 同级的根目录下否则 OSG 找不到插件模型加载会静默失败。4.2 “Qt platform plugin could not be initialized”这类错误的处理很多人在刚接触 Qt 打包时会看到一句经典报错This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.这句话的直白翻译是exe 找到了 Qt5Core.dll但找不到platforms/qwindows.dll或者这个插件和你用的 Qt 版本文件不匹配。解决方法分两步检查第一exe 旁边必须有platforms文件夹里面放qwindows.dll第二qwindows.dll必须和 exe 使用同一套 Qt 版本编译千万不要从网上随手复制一个。用windeployqt生成时它会自动做好这件事。如果还报检查 release 编译时是否误链接了 debug 版 Qt 库。例如项目链接到Qt5Widgetsd.lib但发布的 DLL 是Qt5Widgets.dll没有 d 后缀就会出现类似问题。把工程切换到 Release 再重新生成一遍基本能解决。4.3 Debug/Release、Win32/x64 混用造成的坑VS2017 里最气人的错误不是你写错了代码而是库混用。比如 OSG 编译的是 Release x64Qt 用的是 Debug 版Qt5Cored.dll链接阶段可能不报错但运行时要么内存访问异常要么某些字符串函数直接崩溃。OSG 的库名是有规律的Release 版叫osgViewer.libDebug 版叫osgViewerd.lib。如果你的 CMake 配置写死了osgViewer但 VS 配置是 Debug就会报找不到库文件或者在混合模式下链接出问题。我的建议是整个工程统一用 Release x64 编译。Qt 在这套组合下带来的调试信息其实已经够用了Debug 版的性能反而可能影响三维场景操作手感。32 位和 64 位就更不用说x64配置下不要出现任何指向x86目录的第三方库路径否则时不时冒出的“操作数类型冲突”会让你怀疑是不是代码写错了。问题表现可能原因处理方式启动后提示缺少 Qt5Core.dllPATH 未包含 Qt bin 目录或未发布 Qt DLL设置 PATH或执行 windeployqt无法加载平台插件缺少 platforms/qwindows.dll重新执行 windeployqt复制整个 platforms 目录三维窗口黑屏但控件正常线程模型未设为 SingleThreaded或 resize 未同步强制 SingleThreaded并在 resizeGL 中调用 gw-resized链接时找不到 osgViewer.libCMake 的 OSG_DIR 指向构建目录而非 install 目录确认 OSG_DIR 指向include和lib所在目录打开 exe 时崩溃记录停在 Qt 消息循环Debug/Release 库混合编译全部统一为 Release x64检查 Qt 版本是 msvc2017_64模型读取成功但没有纹理第三方库未编译或 osgPlugins 目录缺失编译 OSG 时启用 libpng/libjpeg发布时复制插件目录5. 实操心得与经验补充5.1 几个让我少走弯路的细节第一个细节是不要迷信最新版本。Qt 6 都出来很久了如果要和 OSG 搭配我还是会选择 Qt 5.12 到 5.15 之间。原因是 OSG 3.6 系列对 Qt5 的支持最成熟很多网上案例都是基于这组版本写的遇到问题容易搜到解决方案。Qt 6 把很多 OpenGL 相关接口改了和老 OSG 版本结合时不付出额外兼容成本犯不上。第二个细节是在代码里加异常日志。我在 OSG 代码和 Qt 事件转发里都插入了简单的qInfo()输出比如按下鼠标时打印坐标模型加载失败时打印原因。这些日志看着不高级但你在“三维场景不动”和“鼠标没反应”之间做判断时能第一时间定位是 OSG 没渲染还是事件没转发过去。省下的排查时间远超写日志的几分钟。第三个细节如果调试过程中发现 OSG 场景加载比较慢不要每次重新运行程序都重新读模型。我在开发阶段把模型文件放到程序工作目录下路径用相对路径并让 OSG 的osgDB::readNodeFile加上osgDB::Registry::instance()-getDataFilePathList().push_back(data)这样既方便调试也方便后续拷贝到别的机器。5.2 从单一例子扩展到完整业务系统当你把 QOpenGLWidget 和 OSG 的桥接代码跑通一次后这套结构其实可以复用到很多方向。比如把setSceneData里的静态模型换成实时点云就能做数据可视化工具把鼠标点击事件通过 Qt 信号转发出去点击某个三维物体后更新右侧表格就实现了二维和三维的数据联动在 OSG 场景外再叠加一个 QCustomPlot 面板把时域波形实时转成频域频谱就是一个带三维姿态显示的信号分析软件。我自己的习惯是把OSGWidget封装成一个独立的 Qt 插件模块内部不写任何业务逻辑只开放几个方法loadModel、setCameraManipulator、setSceneData以及一个signalPickNode信号。这样项目换到另一个三维仿真系统时直接把这个模块拖过去业务层完全不用大改。集成 OSG 和 Qt 本身只是第一步真正的价值在于把三维能力和交互能力都变成可复用的组件。本文还有配套的精品资源点击获取
