Win10+VS2019下OSG 3.6.5与OSGEarth 3.1双版本编译指南

简介该资源面向Windows 10平台下从事三维图形与三维GIS开发的C程序员提供基于Visual Studio 2019完整编译的OpenSceneGraph 3.6.5与OSGEarth 3.1双版本开发库解决自行编译耗时长、依赖配置繁琐的问题可直接接入新项目或替换旧版依赖。压缩包共42个文件约3.49MB以lib导入库为主另含osg_demo示例、main.cpp入口代码及工程配置文件覆盖几何渲染、地形加载、动画控制、标注系统、光照处理与坐标变换等模块。目录按Release与Debug双模式组织bin、include、lib三个标准子目录齐备从AnimationPath、AnnotationNode、AltitudeSymbol、AnisotropicLighting等类名可见关键扩展特性已启用兼容x64架构经多次编译验证。目前已有38人学习下载适合三维GIS、仿真可视化与虚拟训练等桌面应用开发者快速搭建环境、对照示例验证链接配置降低环境搭建与排错成本。1. 为什么 Win10 下编译 OSG OSGEarth 这件事值得你花一个下午如果你在 Windows 上做三维地理可视化大概率绕不开 OSG 和 OSGEarth 这套组合。OSG 负责底层渲染OSGEarth 在它之上封装了地形、影像、矢量图层和坐标投影两者版本必须严格对齐差一个小版本就可能链接报错。而官方并不提供 Windows 下 VS2019 的预编译包网上流传的要么是 VS2015 时代的旧库要么是只编了 Release 没有 Debug 的半成品。结果就是你拿到一个示例工程Release 能跑Debug 一启动就崩或者反过来调试时断点根本进不去。这篇笔记要讲的就是怎么在 Win10 VS2019 环境下把 OSG 3.6.5 和 OSGEarth 3.1 完整编译出来并且同时产出 Release 和 Debug 两套目录结构让两种配置都能正常链接、正常调试。适合已经会写 C、用过 CMake、但被第三方库编译折磨过的同学。下面按依赖准备、编译配置、目录组织、避坑、进阶验证的顺序展开每一步都给出可复现的命令和参数。2. 编译前的依赖准备从零把第三方库凑齐2.1 为什么 OSG 3.6.5 的依赖不能随便下OSG 本身依赖一堆第三方库zlib、libpng、libjpeg、libtiff、freetype、curl、GDAL、Proj 等。很多人图省事直接从网上找现成的二进制包结果编译时 CMake 找得到头文件却链接不上或者运行时报缺少 DLL。根本原因是这些预编译包的编译器版本、运行库选项/MT 还是 /MD、字符集Unicode 还是多字节跟你当前工程不一致。我一般会统一用 vcpkg 来管理这些依赖因为 vcpkg 能保证所有库用同一套工具链编译并且自动处理依赖传递。如果你不想用 vcpkg那就得手动下载源码用同一个 VS2019 逐个编译工作量翻倍且容易出错。2.2 用 vcpkg 安装依赖的完整命令先准备一个干净的目录比如D:\dev然后克隆 vcpkg 并引导git clone https://github.com/microsoft/vcpkg.git D:\dev\vcpkg cd D:\dev\vcpkg .\bootstrap-vcpkg.bat接着安装 OSG 和 OSGEarth 需要的依赖。注意这里要指定 triplet 为x64-windows因为现在基本没人用 32 位了。如果你需要静态库把 triplet 换成x64-windows-static但 OSGEarth 官方更推荐动态库所以下面以动态库为例.\vcpkg install zlib:x64-windows libpng:x64-windows libjpeg-turbo:x64-windows libtiff:x64-windows freetype:x64-windows curl:x64-windows gdal:x64-windows proj:x64-windows sqlite3:x64-windows这里有几个参数要解释zlib是压缩库OSG 读写 osgb 文件时用到libpng、libjpeg-turbo、libtiff分别处理不同格式的纹理freetype用于文字渲染curl用于网络加载gdal和proj是 OSGEarth 处理地理数据必须的sqlite3则是 GDAL 的依赖。安装完成后vcpkg 会把头文件和库放在D:\dev\vcpkg\installed\x64-windows下后面 CMake 配置时要指向这个路径。提示vcpkg 安装 GDAL 比较慢因为会连带编译很多依赖建议先泡杯茶。如果中途失败删掉buildtrees目录重来不要反复重试。2.3 检查依赖是否齐全装完后用下面的命令确认关键库都存在dir D:\dev\vcpkg\installed\x64-windows\lib\*.lib你应该能看到zlib.lib、libpng16.lib、freetype.lib、gdal.lib、proj.lib等。如果缺了某个说明安装时出错了需要单独重装。另外OSGEarth 3.1 对 GDAL 版本有要求太新的 GDAL 可能 API 不兼容vcpkg 默认拉的是较新的版本如果编译 OSGEarth 时报 GDAL 相关错误可以尝试指定旧版 GDAL比如gdal[core]:x64-windows并加上版本约束但 vcpkg 的版本控制比较麻烦更稳妥的做法是手动编译一个 GDAL 2.x。不过根据我的经验OSGEarth 3.1 配合 GDAL 3.x 也能编过只是个别函数需要打补丁后面避坑章节会讲。3. 编译 OSG 3.6.5CMake 参数与 Release/Debug 双目录3.1 获取源码与目录规划从 OSG 的官方仓库下载 3.6.5 版本的源码包解压到D:\dev\osg-3.6.5。不要用 git clone 最新代码因为最新代码可能已经到 3.7 了版本对不上。目录结构建议这样规划D:\dev\ ├── osg-3.6.5\ # 源码 ├── osg-build\ # 编译中间目录 │ ├── release\ # Release 配置 │ └── debug\ # Debug 配置 ├── osg-install\ # 安装目录 │ ├── release\ # Release 库和头文件 │ └── debug\ # Debug 库和头文件 └── vcpkg\ # 依赖这样分开的好处是Release 和 Debug 的库不会混在一起工程里切换配置时只需要改库目录不会出现链接到错误版本的问题。3.2 Release 版本的 CMake 配置命令打开 CMake GUI 或者直接用命令行。我习惯用命令行因为参数可以保存成脚本。先创建 release 构建目录mkdir D:\dev\osg-build\release cd D:\dev\osg-build\release cmake D:\dev\osg-3.6.5 ^ -G Visual Studio 16 2019 ^ -A x64 ^ -DCMAKE_INSTALL_PREFIXD:\dev\osg-install\release ^ -DCMAKE_TOOLCHAIN_FILED:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ -DVCPKG_TARGET_TRIPLETx64-windows ^ -DCMAKE_BUILD_TYPERelease ^ -DBUILD_OSG_APPLICATIONSON ^ -DBUILD_OSG_EXAMPLESON ^ -DOSG_USE_UTF8ON参数逐个说明-G指定 VS2019 生成器-A x64指定 64 位CMAKE_INSTALL_PREFIX是安装路径CMAKE_TOOLCHAIN_FILE让 CMake 自动找到 vcpkg 的库VCPKG_TARGET_TRIPLET必须和安装依赖时一致CMAKE_BUILD_TYPE在 VS 生成器下其实不生效但写上没坏处BUILD_OSG_APPLICATIONS和BUILD_OSG_EXAMPLES建议打开方便后面验证OSG_USE_UTF8开启 UTF-8 支持避免中文路径乱码。配置完成后执行编译和安装cmake --build . --config Release --target INSTALL这一步会编译所有 OSG 核心库和插件时间大概 20 到 40 分钟取决于机器性能。编译完成后D:\dev\osg-install\release下会出现include、lib、bin三个目录。3.3 Debug 版本的 CMake 配置与编译Debug 版本不能和 Release 共用构建目录必须另建一个。步骤类似只是路径和配置不同mkdir D:\dev\osg-build\debug cd D:\dev\osg-build\debug cmake D:\dev\osg-3.6.5 ^ -G Visual Studio 16 2019 ^ -A x64 ^ -DCMAKE_INSTALL_PREFIXD:\dev\osg-install\debug ^ -DCMAKE_TOOLCHAIN_FILED:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ -DVCPKG_TARGET_TRIPLETx64-windows ^ -DCMAKE_BUILD_TYPEDebug ^ -DBUILD_OSG_APPLICATIONSON ^ -DBUILD_OSG_EXAMPLESON ^ -DOSG_USE_UTF8ON然后编译安装cmake --build . --config Debug --target INSTALLDebug 版本的库文件名通常带d后缀比如osgdbd.lib这样链接时不会和 Release 混淆。安装完成后D:\dev\osg-install\debug下同样有完整的目录结构。注意vcpkg 安装的依赖库默认只有 Release 版本Debug 版本需要额外安装x64-windows的 debug 变体。实际上 vcpkg 在安装时会同时生成 release 和 debug 两套但需要确认installed\x64-windows\debug\lib下是否有对应的*d.lib。如果没有需要重新运行vcpkg install并加上--triplet x64-windows的 debug 选项或者直接用vcpkg install zlib:x64-windows --debug这种形式。更简单的办法是安装时加上--recurse并确保没有跳过 debug。4. 编译 OSGEarth 3.1链接 OSG 与处理 GDAL 兼容性4.1 OSGEarth 3.1 的源码获取与 CMake 关键变量OSGEarth 3.1 的源码需要和 OSG 3.6.5 配套。下载后解压到D:\dev\osgearth-3.1。编译前要确保 CMake 能找到刚才安装的 OSG。关键变量是OSG_DIR指向 OSG 的安装目录下的lib\cmake\osg或者直接指向安装根目录。我一般这样配置 Release 版本mkdir D:\dev\osgearth-build\release cd D:\dev\osgearth-build\release cmake D:\dev\osgearth-3.1 ^ -G Visual Studio 16 2019 ^ -A x64 ^ -DCMAKE_INSTALL_PREFIXD:\dev\osgearth-install\release ^ -DCMAKE_TOOLCHAIN_FILED:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ -DVCPKG_TARGET_TRIPLETx64-windows ^ -DCMAKE_BUILD_TYPERelease ^ -DOSG_DIRD:\dev\osg-install\release ^ -DGEOJSON_LIBRARYON ^ -DBUILD_OSGEARTH_EXAMPLESON这里OSG_DIR必须指向 Release 版本的 OSG 安装目录否则会链接到 Debug 库导致冲突。GEOJSON_LIBRARY开启 GeoJSON 支持BUILD_OSGEARTH_EXAMPLES打开示例方便验证。4.2 处理 GDAL 版本不兼容的补丁OSGEarth 3.1 的代码里有些地方调用了 GDAL 的旧 API而 vcpkg 安装的 GDAL 可能是 3.4 以上会报GDALAllRegister未定义或者OGRRegisterAll参数不匹配。常见的错误是error C2039: OGRRegisterAll: 不是 OGR 的成员。解决办法是手动修改源码。找到src/osgEarth/GDALSource.cpp把OGRRegisterAll()改成GDALAllRegister()因为新版 GDAL 把 OGR 的注册合并到了 GDAL 里。另外如果报CPLSetConfigOption相关错误检查是否包含了cpl_conv.h。这些补丁不多但必须打否则编译不过。4.3 编译安装与 Debug 版本Release 编译命令cmake --build . --config Release --target INSTALLDebug 版本类似但OSG_DIR要指向D:\dev\osg-install\debug安装路径也换成D:\dev\osgearth-install\debug。注意 Debug 版本的 OSGEarth 库文件名也会带d后缀比如osgEarthd.lib。编译完成后检查bin目录下是否有osgEarth.dll和osgEarthd.dll以及对应的插件 DLL。提示OSGEarth 编译时如果报找不到osgEarth::Symbology之类的错误多半是 OSG 的 Debug 库没有正确安装回头检查D:\dev\osg-install\debug\lib下是否有osgd.lib等文件。5. 避坑与常见问题血泪经验五条5.1 链接时报 LNK2038 或 RuntimeLibrary 不匹配现象编译自己的工程时链接器报LNK2038: 检测到RuntimeLibrary的不匹配: 值MDd_DynamicDebug与MTd_StaticDebug不匹配。原因OSG 或 OSGEarth 编译时用的运行库选项和你工程的不一致。vcpkg 默认用动态运行库/MD如果你的工程设成了 /MT就会冲突。解决在 VS 里把工程的 C/C - 代码生成 - 运行库改成“多线程调试 DLL (/MDd)”对应 Debug“多线程 DLL (/MD)”对应 Release。如果必须用 /MT那就得重新编译所有依赖用x64-windows-statictriplet。5.2 Debug 版本启动崩溃Release 正常现象用 Debug 配置运行程序一启动就崩报缺少osgDBd.dll或者osgEarthd.dll。原因系统 PATH 里只有 Release 的 DLL或者拷贝 DLL 时只拷了 Release 版。解决把D:\dev\osg-install\debug\bin和D:\dev\osgearth-install\debug\bin加到 PATH 最前面或者把 Debug 的 DLL 拷贝到 exe 同目录。注意 Debug 和 Release 的 DLL 不能混用文件名带 d 的必须对应 Debug 配置。5.3 CMake 找不到 OSG报 Could NOT find OSG现象配置 OSGEarth 时CMake 输出Could NOT find OSG。原因OSG_DIR没设对或者 OSG 安装目录下缺少osg-config.cmake。解决确认D:\dev\osg-install\release\lib\cmake\osg下是否有osg-config.cmake。如果没有说明 OSG 安装时没有生成 CMake 配置文件需要重新编译 OSG 并确保CMAKE_INSTALL_PREFIX正确。另外OSG_DIR应该指向包含lib和include的根目录而不是lib子目录。5.4 运行时提示“无法定位程序输入点”于某个 DLL现象运行示例程序时弹窗提示无法定位程序输入点 xxx 于动态链接库 osgDB.dll 上。原因DLL 版本不匹配比如用 Release 的 exe 加载了 Debug 的 DLL或者 OSG 和 OSGEarth 的版本不对应。解决用 Dependency Walker 或dumpbin /dependents检查 exe 依赖的 DLL确保所有 DLL 都来自同一套安装目录。特别要注意OSGEarth 的 DLL 必须和 OSG 的 DLL 版本严格一致不能混用不同时间编译的产物。5.5 中文路径导致读取文件失败现象加载包含中文路径的模型或影像时OSG 报Could not find plugin to read或者直接崩溃。原因OSG 默认使用本地编码而 Windows 中文系统是 GBK如果路径是 UTF-8 就会乱码。解决编译时加上-DOSG_USE_UTF8ON并且在代码里用osgDB::convertStringFromCurrentCodePageToUTF8转换路径。另外尽量把资源放在纯英文路径下这是最省事的做法。6. 验证双版本库是否可用一个最小加载示例与进阶技巧编译完成后怎么确认两套库都能正常工作我一般写一个最小的 OSGEarth 示例加载一个简单的 earth 文件然后分别用 Release 和 Debug 编译运行。示例代码#include osgViewer/Viewer #include osgEarth/MapNode #include osgEarth/EarthManipulator #include osgDB/ReadFile int main(int argc, char** argv) { osg::ref_ptrosgViewer::Viewer viewer new osgViewer::Viewer; // 加载 earth 文件这里假设当前目录下有 simple.earth osg::ref_ptrosg::Node node osgDB::readNodeFile(simple.earth); if (!node) return -1; viewer-setSceneData(node); viewer-setCameraManipulator(new osgEarth::Util::EarthManipulator); return viewer-run(); }对应的simple.earth文件内容map nametest options profileglobal-geodetic/profile /options image nameworld drivergdal urlworld.tif/url /image /map把world.tif换成任意一张全球影像。编译时Release 配置链接osgEarth.lib、osg.lib等Debug 配置链接osgEarthd.lib、osgd.lib。运行前确保 PATH 包含对应版本的 bin 目录。如果窗口能正常显示地球说明双版本库都可用。进阶技巧如果你需要把这两套库集成到自己的工程里建议在 VS 里建两个属性表Property Sheet一个叫OSG_Release.props一个叫OSG_Debug.props分别设置包含目录、库目录和依赖项。然后在工程里根据配置自动导入对应的属性表。这样切换配置时不用手动改路径减少出错。另外OSGEarth 的插件 DLL 很多部署时可以用windeployqt类似的工具但 OSG 没有官方工具我一般写个批处理脚本把bin目录下所有 DLL 拷贝到输出目录再根据配置筛选带 d 和不带 d 的。这个脚本我用了三年比手动拷贝靠谱得多。最后说一个我踩过的坑有一次我为了省空间把 Release 和 Debug 的安装目录合并成一个结果 CMake 生成的配置里同时包含了两种库的路径链接时随机选一个导致程序时而正常时而崩溃查了两天才发现是目录混用。从那以后我坚持 Release 和 Debug 完全隔离连头文件都分开存放。希望帮到你。本文还有配套的精品资源点击获取