简介本资源为VS2017 64位环境下编译生成的osg、osgWorks、Bullet3与osgbullet库集合面向从事三维游戏开发、物理仿真与可视化应用的C开发者尤其适合需要在Windows平台快速集成3D渲染与碰撞检测的中高级技术人员。压缩包为rar格式整体约228.02MB内含动态库与静态库两类链接形式前者便于减小应用体积、运行时加载后者可直接嵌入目标程序开发者可按项目需求灵活选用。资源核心覆盖OpenSceneGraph高性能3D图形工具包、osgWorks扩展模块、Bullet3开源物理引擎及osgbullet接口库能够将刚体动力学、软体与多边形网格碰撞检测无缝融入osg场景实现物体运动与碰撞效果的视觉同步。目前已有801人学习下载适合需要搭建真实物理行为三维场景、研究渲染与物理集成方案的开发者参考使用。1. VS2017 64 位下把 osg、osgworks、bullet3、osgbullet 串成一条编译链如果你手上有一个 VS2017 的 64 位工程需要同时用到 OpenSceneGraph 做场景渲染、osgWorks 做工具扩展、bullet3 做物理碰撞还要用 osgbullet 把两者粘起来那么你迟早会撞上同一个问题这四个库的编译顺序、位数、运行库选项必须完全对齐否则链接阶段会给你一堆 LNK2019 和 LNK2038。我见过太多人卡在 osgbullet 上前面三个库都编过了最后一步死活过不去翻来覆去查代码其实问题出在 CMake 的变量名和 bullet 的安装布局上。这篇笔记讲的就是这条编译链在 VS2017 64 位环境下的完整落地路径。从依赖关系、CMake 配置、动态库与静态库的取舍到 osgbullet 对接 bullet3 时那几个必调参数再到实际编译中会遇到的坑我都会按我自己的操作顺序写清楚。适合已经会用 CMake 生成 VS 工程、但对这四个库的联动编译还不熟的人。如果你正在做仿真、虚拟现实或者机器人场景里的碰撞检测这套组合值得花时间跑通。2. 四个库的依赖关系与编译顺序为什么 osgbullet 必须最后编2.1 依赖链拆解谁依赖谁谁先谁后先把依赖关系理清楚后面所有操作都围绕这张图展开。osg 是根osgWorks 依赖 osgbullet3 相对独立但 osgbullet 同时依赖 osg 和 bullet3。所以编译顺序只有一个正确解osg → osgWorks → bullet3 → osgbullet。任何一步提前CMake 配置阶段就会报找不到依赖。这里有一个容易忽略的点bullet3 虽然不依赖 osg但 osgbullet 在查找 bullet 时用的是 bullet 自己的 CMake 配置文件BulletConfig.cmake而不是简单的头文件和库路径。这意味着 bullet3 必须用 CMake 安装install一次生成配置文件osgbullet 才能找到它。很多人编译完 bullet 直接指库目录结果 osgbullet 的 CMake 死活找不到 bullet就是缺了 install 这一步。另一个关键点是位数。VS2017 的 64 位工具链和 32 位是两套完全独立的配置CMake 生成工程时必须显式指定-A x64或-G Visual Studio 15 2017 Win64。如果 osg 编的是 64 位osgWorks 编成了 32 位链接时会出现模块计算机类型冲突。这个错误信息很直白但如果你用 CMake GUI 忘了改平台它默认可能是 Win32编到一半才发现就浪费时间了。2.2 用 CMake 生成 VS2017 64 位工程的命令与参数我一般用命令行做比 GUI 可复现。先建一个工作目录把四个源码包解压到同级目录然后逐个编译安装。下面以 osg 为例其他三个库的流程结构一样只是参数不同。# 假设源码目录结构如下 # D:/dev/osg-src/OpenSceneGraph-3.6.5 # D:/dev/osg-src/osgWorks-master # D:/dev/osg-src/bullet3-2.89 # D:/dev/osg-src/osgbullet-master # 安装前缀统一用 D:/dev/osg-install # 1. 编译安装 osg64 位 Release Debug 都编 cd D:/dev/osg-src/OpenSceneGraph-3.6.5 mkdir build-vs2017-x64 cd build-vs2017-x64 cmake .. -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/osg-install ^ -DCMAKE_BUILD_TYPERelease ^ -DBUILD_OSG_APPLICATIONSOFF ^ -DBUILD_DOCUMENTATIONOFF ^ -DDYNAMIC_OSGON cmake --build . --config Release --target INSTALL cmake --build . --config Debug --target INSTALL这段命令里几个参数值得说明。-G Visual Studio 15 2017 Win64直接锁定 64 位生成器避免后面手动改平台。CMAKE_INSTALL_PREFIX统一指向一个安装目录后面三个库都装到这里osgbullet 配置时只需要一个路径。DYNAMIC_OSGON表示编动态库如果你需要静态库改成 OFF但要注意静态库模式下 osgWorks 和 osgbullet 的链接选项也要跟着变。BUILD_OSG_APPLICATIONSOFF跳过示例程序省时间第一次跑通编译链不需要它们。Release 和 Debug 都编是因为实际项目里你可能两个配置都要用。如果只编 ReleaseDebug 模式下链接会找不到对应的库文件。这一步编译时间比较长取决于机器性能耐心等。2.3 osgWorks 与 bullet3 的编译参数差异osgWorks 的编译依赖 osg 的安装路径。CMake 里用OSG_DIR指向 osg 安装目录下的 lib/cmake/osg 或者直接指安装根目录不同版本行为略有差异我一般两个都试一下哪个能找到就用哪个。# 2. 编译安装 osgWorks cd D:/dev/osg-src/osgWorks-master mkdir build-vs2017-x64 cd build-vs2017-x64 cmake .. -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/osg-install ^ -DOSG_DIRD:/dev/osg-install ^ -DCMAKE_BUILD_TYPERelease cmake --build . --config Release --target INSTALL cmake --build . --config Debug --target INSTALLbullet3 的编译稍微不同它有自己的构建选项。关键是INSTALL_LIBSON和BUILD_SHARED_LIBS的选择。如果你要动态库版本的 bullet设BUILD_SHARED_LIBSON静态库则设 OFF。osgbullet 对两者都支持但你的项目最终用哪种这里就要定下来因为后面 osgbullet 链接的库类型必须一致。# 3. 编译安装 bullet3 cd D:/dev/osg-src/bullet3-2.89 mkdir build-vs2017-x64 cd build-vs2017-x64 cmake .. -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/osg-install ^ -DCMAKE_BUILD_TYPERelease ^ -DBUILD_SHARED_LIBSON ^ -DINSTALL_LIBSON ^ -DBUILD_BULLET2_DEMOSOFF ^ -DBUILD_CPU_DEMOSOFF ^ -DBUILD_OPENGL3_DEMOSOFF cmake --build . --config Release --target INSTALL cmake --build . --config Debug --target INSTALLBUILD_BULLET2_DEMOS这些示例关掉能省不少编译时间。INSTALL_LIBSON是必须的否则 install 步骤不会把库文件和 CMake 配置文件拷到安装目录osgbullet 就找不到 bullet。编译完成后检查一下D:/dev/osg-install/lib/cmake/bullet目录是否存在里面应该有 BulletConfig.cmake 等文件。2.4 osgbullet 的 CMake 配置三个必须显式指定的变量osgbullet 是最后一步也是最容易翻车的一步。它的 CMakeLists 会去找 osg、osgWorks 和 bullet但查找逻辑对路径布局有要求。我一般显式指定三个变量避免它自己猜。# 4. 编译安装 osgbullet cd D:/dev/osg-src/osgbullet-master mkdir build-vs2017-x64 cd build-vs2017-x64 cmake .. -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/osg-install ^ -DOSG_DIRD:/dev/osg-install ^ -DOSGWORKS_DIRD:/dev/osg-install ^ -DBULLET_DIRD:/dev/osg-install ^ -DCMAKE_BUILD_TYPERelease cmake --build . --config Release --target INSTALL cmake --build . --config Debug --target INSTALLOSG_DIR、OSGWORKS_DIR、BULLET_DIR这三个变量是 osgbullet 能找到依赖的关键。如果 CMake 输出里出现Could NOT find Bullet先检查BULLET_DIR是否指向了包含lib/cmake/bullet的安装根目录。如果出现Could NOT find osgWorks检查 osgWorks 是否真的 install 到了同一个前缀下。这三个变量都对了配置阶段就不会报错。编译完成后D:/dev/osg-install下会有 include、lib、bin 三个目录四个库的头文件、库文件和运行时 DLL 都在里面。你的项目只需要把这个安装目录配到 VS2017 的包含目录和库目录里就能同时使用这四个库。3. 动态库与静态库的取舍编译选项怎么配运行时怎么部署3.1 动态库模式DLL 部署与运行时路径动态库模式下每个库编译出对应的 DLL 和导入库.lib。osg 的 DLL 在 bin 目录下名字类似 osg160-osg.dll、osg160-osgDB.dll 等。osgWorks 和 osgbullet 的 DLL 也在 bin 下。bullet3 如果开了 BUILD_SHARED_LIBS同样会有 BulletDynamics.dll、BulletCollision.dll 等。运行时部署的关键是让 exe 能找到这些 DLL。最直接的做法是把D:/dev/osg-install/bin加到系统 PATH 里或者把需要的 DLL 拷到 exe 同级目录。我一般用 CMake 的 install 规则或者一个简单的拷贝脚本处理避免手动拷漏。# 把运行时需要的 DLL 拷到输出目录以 Release 为例 copy D:\dev\osg-install\bin\*.dll D:\my-project\bin\Release\注意 Debug 和 Release 的 DLL 不能混用。Debug 版的 osg 库带d后缀如 osg160-osgd.dllRelease 版不带。如果你 Debug 配置下链接了 Release 的 lib运行时会崩溃或者行为异常。CMake 的--config Debug和--config Release分别 install 就是为了生成两套。3.2 静态库模式编译选项与链接顺序静态库模式下DYNAMIC_OSGOFF、BUILD_SHARED_LIBSOFF编译出来的是 .lib 文件。静态链接的好处是部署简单不需要带一堆 DLL坏处是最终 exe 体积大而且链接顺序有讲究。VS2017 链接静态库时依赖顺序必须是从上层到下层的顺序。osgbullet 依赖 osgWorks 和 bulletosgWorks 依赖 osg所以链接器输入里 osgbullet 的 lib 要放在 osgWorks 前面osgWorks 放在 osg 前面。如果顺序反了会出现符号找不到的错误。我一般用 CMake 的 target_link_libraries 自动处理顺序手动配 VS 工程时就要注意这一点。另一个静态库的坑是运行库选项。osg 和 bullet 如果用了/MD多线程 DLL 运行库你的项目也必须用/MD如果用了/MT项目也要用/MT。混用会报 LNK2038 运行库不匹配。CMake 里用CMAKE_MSVC_RUNTIME_LIBRARY统一设置或者编译每个库时显式指定。3.3 混合模式哪些库适合动态哪些适合静态实际项目里不一定全动态或全静态。我的经验是 osg 用动态库因为它的 DLL 比较多静态链接后 exe 会非常大bullet3 可以用静态库它的库文件相对独立静态链接后不会引入太多额外依赖osgWorks 和 osgbullet 跟着 osg 走osg 动态它们也动态。这种混合模式需要在 osgbullet 编译时正确设置 bullet 的链接类型。如果 bullet 是静态库而 osg 是动态库osgbullet 的 CMake 配置里BUILD_SHARED_LIBS要设成 ON因为 osgbullet 本身是动态库但它链接的 bullet 库是静态的。这完全可行只是链接时 bullet 的静态库会被打包进 osgbullet 的 DLL 里。注意混合模式下bullet 的静态库编译时必须用和 osgbullet 相同的运行库选项否则链接 osgbullet 时会报运行库冲突。4. osgbullet 对接 bullet3 的碰撞检测从场景节点到物理世界的映射4.1 osgbullet 的核心类与数据流osgbullet 做的事情是在 osg 的场景图和 bullet 的物理世界之间建立映射。核心类有几个osgbCollision::btCompoundShape用来从 osg 节点生成 bullet 的碰撞形状osgbCollision::btBoxCollisionShape等辅助类生成基本形状osgbDynamics::MotionState把 osg 的变换矩阵同步到 bullet 的刚体。数据流是这样的osg 场景图里的一个节点比如一个 MatrixTransform 下面的几何体通过 osgbullet 的工具函数生成对应的 btCollisionShape 和 btRigidBody加入到 btDiscreteDynamicsWorld 里。每帧调用world-stepSimulation()后MotionState 会把 bullet 计算出的新变换写回 osg 节点实现物理模拟驱动渲染。理解这个数据流很重要因为碰撞检测不生效时问题往往出在某一环断了要么形状没生成对要么刚体没加到 world 里要么 MotionState 没正确绑定。4.2 从 osg 节点生成 bullet 碰撞形状的代码示例下面这段代码演示如何从一个 osg 节点生成 bullet 的碰撞形状并创建刚体。这是 osgbullet 最典型的用法。#include osgbCollision/Utils.h #include osgbDynamics/MotionState.h #include btBulletDynamicsCommon.h #include osg/MatrixTransform // 假设 root 是 osg 场景里的一个节点 osg::ref_ptrosg::MatrixTransform node ...; // 1. 从 osg 节点生成 bullet 碰撞形状 btCollisionShape* shape osgbCollision::btCollisionShapeForOSG(node.get()); if (!shape) { // 形状生成失败通常是节点没有几何体或者包围盒计算失败 return; } // 2. 创建 MotionState绑定 osg 节点 osg::ref_ptrosgbDynamics::MotionState motion new osgbDynamics::MotionState(); motion-setTransform(node.get()); // 关键把 osg 节点交给 MotionState 管理 // 3. 设置刚体的初始变换和惯性 btTransform startTransform; startTransform.setIdentity(); btScalar mass 1.0f; // 质量0 表示静态物体 btVector3 inertia(0, 0, 0); if (mass 0.0f) { shape-calculateLocalInertia(mass, inertia); } // 4. 创建刚体并加入物理世界 btRigidBody::btRigidBodyConstructionInfo rbInfo(mass, motion.get(), shape, inertia); btRigidBody* body new btRigidBody(rbInfo); world-addRigidBody(body);这段代码里几个关键点。btCollisionShapeForOSG会根据节点的包围盒生成一个复合形状如果节点结构复杂生成的形状可能不够精确需要手动调整。motion-setTransform(node.get())是绑定 osg 节点和 bullet 刚体的关键少了这一步物理模拟的结果不会反映到渲染上。mass为 0 时是静态物体不参与动力学计算但可以参与碰撞检测。4.3 碰撞检测的三种模式与参数设置bullet 的碰撞检测有三种模式离散检测Discrete、连续检测Continuous、以及扫描检测Sweep。osgbullet 默认用离散检测对于高速运动的物体可能会穿透需要开连续检测。// 开启连续碰撞检测CCD body-setCcdMotionThreshold(0.1f); // 触发 CCD 的运动阈值 body-setCcdSweptSphereRadius(0.05f); // 扫掠球半径一般设为物体最小尺寸的一半 // 设置碰撞标志和掩码控制哪些物体之间检测碰撞 body-setCollisionFlags(body-getCollisionFlags() | btCollisionObject::CF_CUSTOM_MATERIAL_CALLBACK); world-addRigidBody(body, btBroadphaseProxy::DefaultFilter, btBroadphaseProxy::AllFilter);setCcdMotionThreshold的值需要根据场景尺度调整。如果场景单位是米物体运动速度是米/秒阈值设 0.1 意味着每帧移动超过 0.1 米就触发连续检测。setCcdSweptSphereRadius太小会导致检测不到太大会误报一般取物体最小尺寸的一半。碰撞标志和掩码用于过滤。比如你只想让角色和地面碰撞不想让角色和装饰物碰撞就可以用不同的 filter group 和 mask 来区分。addRigidBody的第二个和第三个参数就是 group 和 mask默认是 DefaultFilter 和 AllFilter表示和所有物体碰撞。4.4 调试碰撞形状用 osg 可视化 bullet 的碰撞体碰撞检测不生效时最有效的调试方法是把 bullet 的碰撞形状可视化出来看看它和渲染的几何体是否对齐。osgbullet 提供了osgbCollision::createDebugNode之类的工具但不同版本名字可能不同。我一般自己写一个简单的可视化遍历 world 里的所有碰撞对象用btCollisionShape的getAabb或者直接根据形状类型生成对应的 osg 几何体。// 简单可视化为每个碰撞体画一个线框盒子 for (int i 0; i world-getNumCollisionObjects(); i) { btCollisionObject* obj world-getCollisionObjectArray()[i]; btRigidBody* body btRigidBody::upcast(obj); if (!body) continue; btVector3 min, max; body-getAabb(min, max); osg::ref_ptrosg::Geode geode new osg::Geode(); osg::ref_ptrosg::ShapeDrawable box new osg::ShapeDrawable( new osg::Box(osg::Vec3((min.x()max.x())/2, (min.y()max.y())/2, (min.z()max.z())/2), max.x()-min.x(), max.y()-min.y(), max.z()-min.z())); box-setColor(osg::Vec4(1, 0, 0, 0.5)); geode-addDrawable(box); debugRoot-addChild(geode); }这段代码把每个碰撞体的 AABB 画成半透明红色盒子叠加在场景上。如果红色盒子和渲染的物体位置偏差很大说明 MotionState 的绑定或者初始变换有问题。如果盒子大小和物体不匹配说明碰撞形状生成有问题。5. 编译与运行中的避坑清单从 LNK 错误到运行时崩溃5.1 LNK2019 未解析的外部符号九成是位数或运行库不匹配现象链接时大量 LNK2019提示某个 osg 或 bullet 的函数找不到实现。原因通常是库的位数不对32 位库链到 64 位工程或者运行库选项不一致/MD 链了 /MT 的库。解决方法是检查每个库编译时的-G参数是否都是 Win64以及CMAKE_MSVC_RUNTIME_LIBRARY是否统一。用 dumpbin /headers 查看 lib 文件的机器类型确认是 x64 还是 x86。5.2 osgbullet 找不到 bulletBulletConfig.cmake 的路径问题现象CMake 配置 osgbullet 时报Could NOT find Bullet即使 bullet 已经编译安装。原因是 bullet 的 install 步骤没有生成 CMake 配置文件或者BULLET_DIR指向的目录不对。解决方法是确认D:/dev/osg-install/lib/cmake/bullet/BulletConfig.cmake存在然后BULLET_DIR指向D:/dev/osg-install而不是D:/dev/osg-install/lib。如果文件不存在重新编译 bullet 并确保INSTALL_LIBSON。5.3 运行时崩溃DLL 版本混用与 Debug/Release 混链现象程序启动时崩溃或者运行到某个功能时异常退出。原因通常是 Debug 配置下链接了 Release 的 DLL或者 PATH 里存在多个版本的 osg DLL加载了错误的那个。解决方法是检查输出目录下的 DLL 是否和当前配置匹配Debug 版 DLL 带 d 后缀。用 Dependency Walker 或者 VS 的模块窗口查看实际加载的 DLL 路径。5.4 碰撞检测不生效MotionState 绑定与形状生成的常见错误现象物理世界里的物体不动或者穿透了但没有任何碰撞反应。原因可能是 MotionState 没有正确绑定 osg 节点或者碰撞形状生成失败返回了空指针或者刚体没有加到 world 里。解决方法是逐步检查btCollisionShapeForOSG返回值是否非空motion-setTransform是否调用world-addRigidBody是否执行。用第 4 章的可视化方法确认碰撞体是否存在。5.5 静态库链接顺序错误符号重复定义与缺失现象静态链接时报符号重复定义LNK2005或者符号缺失LNK2019。原因是链接顺序不对或者同一个库的静态版和动态版同时被链接。解决方法是调整链接器输入顺序上层库在前下层库在后确保没有同时链接同一个库的 .lib 和导入库。用 CMake 的 target_link_libraries 可以自动处理顺序手动配 VS 工程时要特别注意。6. 验证编译链是否真正跑通一个最小碰撞场景的完整测试编译完四个库只是第一步真正要确认的是它们能协同工作。我一般会写一个最小的测试程序一个 osg 场景里放一个地面和一个下落的小球用 bullet 做碰撞检测小球落到地面后弹跳或者静止。这个测试能同时验证 osg 渲染、osgWorks 工具、bullet 物理和 osgbullet 绑定是否都正常。测试程序的骨架是这样的初始化 osgViewer创建根节点用 osgbullet 创建地面和球体的碰撞形状和刚体加入 btDiscreteDynamicsWorld每帧调用world-stepSimulation(1/60.0f)然后 viewer 渲染。如果小球下落、碰撞、停止说明整条链路通了。如果小球直接穿过地面检查碰撞形状的尺寸和位置是否匹配如果小球不动检查质量是否设了 0 或者 MotionState 是否绑定。// 最小测试小球落地 btDiscreteDynamicsWorld* world new btDiscreteDynamicsWorld(dispatcher, broadphase, solver, config); world-setGravity(btVector3(0, -9.8f, 0)); // 地面静态平面 btCollisionShape* groundShape new btStaticPlaneShape(btVector3(0, 1, 0), 0); btRigidBody* groundBody createRigidBody(0, btTransform::getIdentity(), groundShape); world-addRigidBody(groundBody); // 小球动态球体 btCollisionShape* ballShape new btSphereShape(0.5f); btTransform ballTransform; ballTransform.setOrigin(btVector3(0, 5, 0)); btRigidBody* ballBody createRigidBody(1.0f, ballTransform, ballShape); world-addRigidBody(ballBody); // 每帧更新 world-stepSimulation(1.0f / 60.0f, 10);这个测试跑通后再把 osg 的节点和 MotionState 绑上去确认渲染的球体跟着物理世界动。这一步过了说明你的编译链和运行时环境都没问题可以开始往里面加复杂的场景和碰撞体了。我自己的习惯是每换一台机器或者升级一次 VS2017 的补丁都重新跑一遍这个最小测试。血泪经验是VS2017 的小版本更新有时会改变运行库的默认选项之前编好的库可能突然链接不上重新编一遍四个库比逐个排查快得多。希望帮到你。本文还有配套的精品资源点击获取