簡(jiǎn)介OpenSceneGraph 3rdParty_VS2017_v141_x64_V11_full.7z 是一套專為 Visual Studio 2017v141 工具集準(zhǔn)備的 OSG 第三方依賴庫(kù)完整打包面向需要在 Windows x64 環(huán)境下編譯或運(yùn)行 OpenSceneGraph 的 C 開(kāi)發(fā)者。由于 OSG 官網(wǎng)訪問(wèn)不穩(wěn)定、下載速度極慢作者耗時(shí)一周才完整獲取這些依賴組件現(xiàn)以 7z 壓縮包形式共享可省去逐個(gè)尋找與等待的時(shí)間。該壓縮包約 98.6MB解壓后即可獲得用于 VS2017 x64 環(huán)境下的依賴組件集合涵蓋編譯 OSG 所需的第三方庫(kù)、頭文件及運(yùn)行支持文件適用于配置渲染、場(chǎng)景管理等基礎(chǔ)開(kāi)發(fā)環(huán)境也適合剛接觸 OSG 的讀者直接解壓使用。目前已有 822 人瀏覽學(xué)習(xí)說(shuō)明對(duì)解決環(huán)境搭建痛點(diǎn)有實(shí)際參考價(jià)值。下載后按 VS2017 x64 工程配置好包含目錄與庫(kù)目錄即可讓 OSG 及相關(guān)插件正常編譯鏈接減少因缺少依賴而反復(fù)報(bào)錯(cuò)的困擾。1. 用 OpenSceneGraph 做渲染卻被依賴卡住這個(gè) v141_x64 依賴包到底解決什么三周前某開(kāi)發(fā)者抱著“VS2017 編譯成功但一運(yùn)行就閃退”的工程來(lái)找我查了一下午問(wèn)題不在他的代碼而在 OSG 插件運(yùn)行時(shí)找不到第三方 DLL。OpenSceneGraphOSG編譯本身不難難的是 zlib、libpng、freetype、glew、tbb 這一圈第三方依賴各自版本、工具集、Debug/Release 一變鏈接期能過(guò)運(yùn)行期不一定能過(guò)。OpenSceneGraph 3rdParty_VS2017_v141_x64_V11_full.7z就是給 Visual Studio 2017v141 工具集x64 架構(gòu)準(zhǔn)備的整套依賴混合包解壓后直接喂給 CMake把“逐個(gè)下載依賴再編譯”這個(gè)最耗時(shí)且最容易翻車的環(huán)節(jié)砍掉。適合要做 OSG 三維仿真、地形渲染、跨平臺(tái)視景程序又不想在依賴上繼續(xù)消耗時(shí)間的 C 開(kāi)發(fā)者。2. 拆包看本質(zhì)這個(gè)依賴包里到底裝著什么2.1 目錄結(jié)構(gòu)背后的三分法邏輯把壓縮包解開(kāi)后典型的 3rdParty 目錄結(jié)構(gòu)是三個(gè)平級(jí)目錄include、lib、bin。這個(gè)結(jié)構(gòu)不是隨便擺的它對(duì)應(yīng) OSG 在 CMake 配置階段的三種搜索需求——頭文件路徑include、鏈接庫(kù)路徑lib、運(yùn)行時(shí) DLL 路徑bin。3rdParty/ ├── include/ │ ├── zlib.h │ ├── png.h │ ├── ft2build.h │ └── ...各依賴庫(kù)頭文件 ├── lib/ │ ├── zlib.lib # Release 版 │ ├── zlibd.lib # Debug 版 │ └── ...同規(guī)則命名的靜態(tài)庫(kù) └── bin/ ├── zlib1.dll ├── zlibd1.dll # Debug 版帶d后綴 └── ...同名但分 Debug / Release 的 DLLOSG 用 CMake 做配置檢測(cè)時(shí)靠名字后綴區(qū)分庫(kù)的調(diào)試態(tài)與發(fā)布態(tài)zlibd.lib里的 d 代表 debugableRelease 構(gòu)建不要鏈接它。這個(gè)“同名帶 d / 不帶 d”的規(guī)則貫穿整個(gè)包后面寫(xiě) LIBPNG、FREETYPE 時(shí)同理。把 Debug 庫(kù)和 Release 庫(kù)混著鏈最常見(jiàn)的結(jié)局是編譯期報(bào)LNK2038或者運(yùn)行時(shí)彈“無(wú)法定位程序輸入點(diǎn)”這屬于可以提前避開(kāi)的基礎(chǔ)常識(shí)。另一個(gè)細(xì)節(jié)是OSG 之所以不直接用系統(tǒng)自帶的同名依賴庫(kù)是因?yàn)樗牟寮w系要求每個(gè)第三方庫(kù)以獨(dú)立模塊存在版本一旦錯(cuò)位插件加載時(shí)就是靜默失敗不報(bào)任何明確信息。2.2 各依賴庫(kù)的角色定位這份依賴包里的每個(gè)庫(kù)在 OSG 渲染管線里承擔(dān)的任務(wù)不一樣。我拆過(guò)幾個(gè) OSG 工程把直接參與常用渲染路徑的庫(kù)挑出來(lái)依賴庫(kù)在 OSG 里的用途必用程度zlib底層解壓縮PNG 壓縮數(shù)據(jù)解析依賴它極高libpng / libjpeg / libtiff紋理圖片解碼加載 jpg/png/tiff 貼圖時(shí)被插件調(diào)用高giflibgif 紋理加載視需求而定freetype文字紋理渲染HUD 和標(biāo)注信息顯示靠它高做 GIS/仿真必備curl網(wǎng)絡(luò)文件讀取遠(yuǎn)程模型庫(kù)加載視需求而定glewOpenGL 擴(kuò)展入口加載OSG 渲染線程初始化時(shí)使用極高glfw / sdl窗口與事件管理viewer 創(chuàng)建窗口視選擇而定tbb并行計(jì)算多線程渲染與裁剪算法加速極高lua腳本綁定可選的腳本化控制層低你解壓后看到的“full”全量包就是把 debug 和 release 兩套庫(kù)都塞進(jìn)去了配齊的好處是不需要因?yàn)槿鄙倌骋粋€(gè)靜態(tài)庫(kù)去臨時(shí)補(bǔ)編。壞處是體積變大后面發(fā)布截取時(shí)可以再瘦身這個(gè)放到第 5 章講。2.3 給熟手劃清邊界這個(gè)包適配什么、不背什么鍋名字上寫(xiě)得很直白VS2017、v141、x64、V11。v141 是 Visual Studio 2017 默認(rèn)的平臺(tái)工具集版本號(hào)這和工程屬性里看到的“Visual Studio 2017 (v141)”是一回事。如果你手里是 VS2019v142 工具集用這份包大概率碰不到顯式報(bào)錯(cuò)但庫(kù)的 ABI 兼容與工具集元數(shù)據(jù)不匹配會(huì)以各種奇怪鏈接錯(cuò)誤的形式出現(xiàn)不排除能過(guò)的情況但別指望它能穩(wěn)定復(fù)現(xiàn)。V11 指的是 3rdParty 包的版本代次對(duì)應(yīng) OSG 3.6.x 開(kāi)發(fā)周期中某一輪的配套依賴快照和 OSG 主版本號(hào)不是同一個(gè)數(shù)字體系實(shí)際編譯前要確認(rèn)你的 OSG 源碼版本和這個(gè)包在 CMake 里的檢測(cè)結(jié)果能對(duì)上。還要?jiǎng)澢宓倪吔缡沁@包只管“第三方依賴”不含 OSG 主庫(kù)源碼、不附帶 CMake 構(gòu)建工具、不提供 VS 工程模板。它的正確用法是作為輸入源喂給 OSG 的 CMake 配置讓 OSG 的構(gòu)建腳本在它上面自動(dòng)生成依賴變量。把這個(gè)前提理解透后面每一步操作都不會(huì)跑偏。3. 把依賴接進(jìn) OSG 構(gòu)建流程從解壓到生成 VS 工程全記錄3.1 環(huán)境核對(duì)與目錄規(guī)劃動(dòng)手前先對(duì)一遍環(huán)境Visual Studio 2017 已裝好、勾選了“適用于 Visual Studio 2017 的 C 工具集”、CMake 版本不低于 3.10。架構(gòu)上明確是 x64生成的 OSG 庫(kù)和插件全是 64 位后面所有配置選項(xiàng)都圍繞 x64 走不要在配置中途切到 Win32否則依賴檢測(cè)會(huì)全部落空。路徑規(guī)劃是很多人在這一步就開(kāi)始踩坑的地方。把這整個(gè) 3rdParty 文件夾放到一個(gè)純英文、無(wú)空格的路徑下比如D:/dev/3rdParty_vs2017_x64不要放進(jìn)C:\Program Files之類帶空格的目錄。因?yàn)?CMake 在處理第三方庫(kù)路徑時(shí)會(huì)把空格后的內(nèi)容拆成新的參數(shù)變量名帶引號(hào)可以緩解但依賴庫(kù)附帶的 pkgconfig 文件不認(rèn)空格。OSG 源碼目錄也建議放在同類規(guī)則的路徑下。3.2 用 CMake 配置腳本把依賴指給 OSG常見(jiàn)做法是在 OSG 源碼目錄外創(chuàng)建一個(gè) build 目錄把 CMake 生成結(jié)果統(tǒng)一收進(jìn)去。把 3rdParty 告訴 CMake 的方式不同版本略有差異。通常優(yōu)先設(shè)置CMAKE_PREFIX_PATH因?yàn)?OSG 的 CMake 腳本會(huì)在該路徑下自動(dòng)搜索include、lib、bin三個(gè)子目錄。具體命令行如下以命令行為例CMake GUI 里對(duì)應(yīng)是兩個(gè)輸入框cmake ../OpenSceneGraph \ -G Visual Studio 15 2017 \ -A x64 \ -DCMAKE_PREFIX_PATHD:/dev/3rdParty_vs2017_x64 \ -DCMAKE_BUILD_TYPERelease \ -DBUILD_OSG_EXAMPLESON-G指定生成器Visual Studio 15 2017是 VS2017 在 CMake 里的固定字符串不要手寫(xiě)版本號(hào)-A x64強(qiáng)制架構(gòu)為 64 位CMAKE_PREFIX_PATH指向解壓后的 3rdParty 根目錄OSG 的檢測(cè)腳本會(huì)按“根/include、根/lib、根/bin”的約定自動(dòng)找到各依賴庫(kù)的具體路徑CMAKE_BUILD_TYPE在 VS 多配置生成器下只作為默認(rèn)配置項(xiàng)實(shí)際 Debug 和 Release 都可以在 VS 里切換但它會(huì)影響 CMake 選擇依賴庫(kù)時(shí)偏向哪一組BUILD_OSG_EXAMPLESON把自帶示例編進(jìn)去強(qiáng)烈建議開(kāi)著后面驗(yàn)證渲染和插件是否正常全靠它。3.3 逐項(xiàng)核對(duì) CMake 變量是否指向正確路徑命令行配置完成后打開(kāi) CMake GUI 加載 build 目錄的 CMakeCache.txt逐項(xiàng)檢查幾個(gè)關(guān)鍵依賴變量的取值。重點(diǎn)看它們是否落在D:/dev/3rdParty_vs2017_x64的范圍內(nèi)CMake 變量期望取值示例錯(cuò)誤取值預(yù)示的問(wèn)題ZLIB_INCLUDE_DIRD:/dev/3rdParty_vs2017_x64/include找不到 zlib.hPNG 插件編譯失敗ZLIB_LIBRARYD:/dev/3rdParty_vs2017_x64/lib/zlib.lib鏈接期找不到 zlib報(bào) LNK1181LIBPNG_LIBRARYD:/dev/3rdParty_vs2017_x64/lib/libpng16.lib紋理解碼功能缺失FREETYPE_INCLUDE_DIR_freetype2D:/dev/3rdParty_vs2017_x64/include/freetype2HUD 文字渲染不可用TBB_INCLUDE_DIRD:/dev/3rdParty_vs2017_x64/include多線程渲染退化為單線程遇到某一個(gè)變量顯示NOTFOUND不要急著對(duì)整個(gè)包做修改。先確認(rèn)對(duì)應(yīng)目錄里是否有該文件、文件名是否帶 d 后綴、x64 子目錄是否存在。CMake 在同一個(gè)根路徑下檢測(cè)時(shí)只要目錄命名標(biāo)準(zhǔn)絕大多數(shù)變量能自動(dòng)對(duì)齊。若個(gè)別項(xiàng)找不到手工點(diǎn) ... 按鈕把路徑指過(guò)去然后重新 Configure直到整張變量表沒(méi)有紅色錯(cuò)誤項(xiàng)。3.4 生成與編譯一次生成別單獨(dú)編某個(gè)項(xiàng)目配置完成后點(diǎn)擊 Generate 生成 VS 解決方案然后打開(kāi)生成的OpenSceneGraph.sln對(duì)整個(gè)解決方案執(zhí)行“生成解決方案”。這里有個(gè)容易出現(xiàn)的方向性錯(cuò)誤不要因?yàn)橹幌腧?yàn)證某個(gè)功能就單獨(dú)編譯osgViewer項(xiàng)目OSG 的插件和庫(kù)存在復(fù)雜的依賴順序單獨(dú)編某個(gè)小項(xiàng)目會(huì)漏掉插件 DDL運(yùn)行時(shí)會(huì)報(bào)一堆 “Failed to load plugin”。命令行下全量構(gòu)建可參考如下步驟VS 界面里執(zhí)行同樣的全量生成即可cmake --build . --config Release --target install--config Release指定構(gòu)建配置和前面 CMAKE_BUILD_TYPE 保持一致--target install會(huì)把產(chǎn)物收集到 CMAKE_INSTALL_PREFIX 指定的目錄默認(rèn)是 OSG 源碼下的 install 子目錄。執(zhí)行時(shí)觀察輸出zlib、libpng、freetype 的編譯日志如果出現(xiàn)在“Building”階段說(shuō)明前面的依賴路徑已被正確接上。整個(gè)過(guò)程在主流配置下約 20 到 50 分鐘中間如果報(bào)錯(cuò)百分之八十的根因都集中在依賴路徑指向錯(cuò)誤上。4. 避坑實(shí)錄把這份包接進(jìn) VS2017 后我翻過(guò)的四次車4.1 Debug 和 Release 混用導(dǎo)致的 LNK2038現(xiàn)象編譯 OSG 主庫(kù)時(shí)報(bào)LNK2038 mismatch detected for RuntimeLibrary詳細(xì)提示是“值 MT_StaticRelease 與 MD_DynamicRelease 不匹配”看起來(lái)像是 CRT 靜態(tài)鏈接和動(dòng)態(tài)鏈接混在一起。原因CMake 在 Debug 配置下自動(dòng)選擇了帶 d 的 debug 庫(kù)在 Release 配置下選擇不帶 d 的 release 庫(kù)但工程里如果有自定義第三方項(xiàng)目同時(shí)引用兩條路徑鏈接器就會(huì)看到同一符號(hào)對(duì)應(yīng)兩種不同的運(yùn)行時(shí)庫(kù)規(guī)則。另一種更常見(jiàn)的觸發(fā)方式是在 Release 項(xiàng)目里手工追加了 debug 版的.lib文件路徑。解決打開(kāi) VS 工程屬性在“鏈接器 → 輸入 → 附加依賴項(xiàng)”里逐行核對(duì)文件名Debug 配置只保留zlibd.lib、libpng16d.lib這類帶 d 的庫(kù)Release 配置只保留不帶 d 的庫(kù)。對(duì)照表如下配置zlib 用這個(gè)libpng 用這個(gè)Debugzlibd.liblibpng16d.libReleasezlib.liblibpng16.lib檢查完后重新生成解決方案不要再只編出錯(cuò)的單項(xiàng)目強(qiáng)迫 CMake 重算一次依賴關(guān)系。4.2 運(yùn)行時(shí)提示缺少 zlib1.dll / libpng16.dll現(xiàn)象編譯全部通過(guò)生成了osgviewer.exe雙擊運(yùn)行直接彈窗“由于找不到 zlib1.dll無(wú)法繼續(xù)執(zhí)行代碼”或者沒(méi)有任何彈窗就閃退。原因OSG 插件在運(yùn)行時(shí)通過(guò)動(dòng)態(tài)加載方式查找依賴 DLL搜索順序是 exe 所在目錄、系統(tǒng) PATH、當(dāng)前工作目錄。這個(gè)包里的bin目錄從未被加入 PATH插件加載失敗后 viewer 選擇了靜默退出。我遇到過(guò)因?yàn)楣ぷ髂夸洸煌鴷r(shí)好時(shí)壞的情況代碼沒(méi)變行為變了查了一小時(shí)才發(fā)現(xiàn)是 PATH 問(wèn)題。解決將D:/dev/3rdParty_vs2017_x64/bin追加到系統(tǒng)環(huán)境變量 PATH?；蛘吒∈碌淖龇ò裝in里的 DLL 一次性復(fù)制到 exe 同級(jí)目錄。復(fù)制的代價(jià)是發(fā)布時(shí)容易帶全所有 debug DLL所以只建議本地調(diào)試用。提示修改 PATH 后要新開(kāi)一個(gè)終端或重啟 VS否則環(huán)境變量不會(huì)刷新。4.3 插件加載失敗但不報(bào)任何原因現(xiàn)象運(yùn)行時(shí)輸出窗口出現(xiàn)Warning: Failed to load plugin osgdb_png.dll但文件明明存在于bin/osgPlugins-3.6.x/目錄下手動(dòng)用加載庫(kù)方式打開(kāi)該 DLL 也成功。原因osgdb_png.dll本身存在但它依賴的libpng16.dll或者zlib1.dll不在系統(tǒng)搜索路徑中。這屬于間接依賴缺失Windows 只報(bào)告第一層加載失敗不會(huì)告訴你“因?yàn)槿?libpng16.dll 所以 osgdb_png.dll 加載不了”。解決用 Dependencies 工具老牌的 Depends.exe 已停止維護(hù)社區(qū)維護(hù)的 Dependencies 可用打開(kāi)osgdb_png.dll在“導(dǎo)入函數(shù)”列表里找標(biāo)紅的 DLL逐個(gè)比對(duì)3rdParty/bin目錄中是否存在同名且同架構(gòu)版本。定位后把缺少的那個(gè) DLL 的目錄加入 PATH問(wèn)題立刻消失。4.4 含空格的路徑讓 CMake 變量全線 NOTFOUND現(xiàn)象把 3rdParty 放到C:\Program Files\3rdParty_vs2017_x64后執(zhí)行 CMakeZLIB_INCLUDE_DIR、LIBPNG_LIBRARY等全部為 NOTFOUND反復(fù)點(diǎn)擊 Configure 無(wú)效手填變量后被下一次 Configure 覆蓋回空值。原因CMake 的內(nèi)置find_path、find_library模塊對(duì)帶空格的路徑處理不徹底生成器表達(dá)式和緩存變量在空格路徑下會(huì)解析出兩個(gè)參數(shù)導(dǎo)致匹配失敗。解決把整個(gè)包移動(dòng)到D:/dev/3rdParty_vs2017_x64這種無(wú)空格無(wú)中文的路徑重新解壓后再次執(zhí)行緩存清理。我習(xí)慣刪掉 build 目錄后重新走一遍配置不給 CMake 緩存留任何歷史包袱。5. 編譯成功只是開(kāi)始驗(yàn)證與配送那幾件容易忽略的事5.1 osgversion 與依賴檢查雙線驗(yàn)證編譯安裝完成后先到安裝目錄的 bin 下找到osgversion.exe命令行執(zhí)行它osgversion正常輸出類似3.6.5某些版本還會(huì)帶OpenSceneGraph Library 3.6.5的字樣。這個(gè)輸出說(shuō)明主庫(kù)構(gòu)建時(shí)對(duì)第三方依賴的檢測(cè)、鏈接都成功了。再把osgviewer.exe拖進(jìn) Dependencies 工具看導(dǎo)入列表里是否出現(xiàn)OPENGL32.dll、GLU32.dll之外的依賴項(xiàng)重點(diǎn)觀察它們是否全部來(lái)自3rdParty/bin。如果列表里出現(xiàn)某個(gè)庫(kù)的絕對(duì)路徑指向了別處說(shuō)明 CMake 緩存里混入了其他版本依賴后面發(fā)布時(shí)會(huì)踩“開(kāi)發(fā)機(jī)正常、別的機(jī)器崩”的雷。5.2 首屏渲染驗(yàn)證插件鏈?zhǔn)欠裾娴耐擞靡粋€(gè) 3D 模型或圖片驗(yàn)證整套插件鏈。OSG 自帶的示例模型在data目錄下用 osgviewer 加載osgviewer cow.osg窗口能彈出來(lái)且顯示一只牛說(shuō)明窗口系統(tǒng)相關(guān)的 GLFW/GLUT 插件已生效模型表面紋理顯示正常說(shuō)明 PNG/JPEG 插件能完成紋理解碼旋轉(zhuǎn)操作流暢說(shuō)明 TBB 并行模塊被正確鏈接進(jìn)渲染循環(huán)。如果界面流暢但紋理是灰色色塊優(yōu)先檢查 zlib 和 libpng 的 debug/release 配置是否錯(cuò)位。這一步同時(shí)把 OSG 的核心鏈路和第三方依賴鏈路做了一次全局冒煙測(cè)試。5.3 發(fā)布階段的 DLL 裁剪清單生產(chǎn)環(huán)境發(fā)布時(shí)不能把 3rdParty 的 bin 整個(gè)搬過(guò)去。按功能鏈路裁剪能省大量體積我通常按這個(gè)最小清單配貨DLL 文件用途鏈路是否必須zlib1.dllPNG 壓縮解壓、網(wǎng)絡(luò)流解壓必須libpng16.dll紋理 PNG 解碼按內(nèi)容格式j(luò)peg62.dlljpg 貼圖解碼按內(nèi)容格式freetype.dll文字標(biāo)注渲染GIS/仿真類必須glew32.dllOpenGL 擴(kuò)展入口必須tbb.dll并行線程調(diào)度必須libcurl.dll網(wǎng)絡(luò)加載模型按需經(jīng)驗(yàn)是三類 DLL 必帶渲染鏈路glew、tbb、文件 I/O 鏈路zlib、libpng、字體鏈路freetype。其他如 giflib、lua 按實(shí)際調(diào)用的 OSG 插件裁剪。不帶 d 后綴的是 Release 版發(fā)布時(shí)只帶這組。6. 把這份依賴包用成基礎(chǔ)設(shè)施的三個(gè)高階習(xí)慣把 3rdParty 當(dāng)一次性解壓工具用太浪費(fèi)我更傾向讓它成為一個(gè)被多個(gè)工程共享的基礎(chǔ)目錄。第一種做法是符號(hào)鏈接代替復(fù)制避免把 DLL 庫(kù)文件散落得到處都是mklink /D D:\dev\shared_3rdParty D:\dev\3rdParty_vs2017_x64Windows 下mklink /D創(chuàng)建目錄符號(hào)鏈接可以給同一份依賴做多個(gè)邏輯入口比如第一個(gè)工程用 VS2017 編譯時(shí)指向上層路徑第二個(gè)工程在另一臺(tái)機(jī)器上用同樣鏈接映射到同一個(gè)物理目錄。注意符號(hào)鏈接本身對(duì) CMake 透明路徑被解析成真實(shí)路徑后不再體現(xiàn)鏈接關(guān)系。第二種習(xí)慣是把CMAKE_PREFIX_PATH寫(xiě)進(jìn)用戶級(jí)環(huán)境變量這樣后續(xù)新拉的 OSG 源碼、甚至其他依賴同一套庫(kù)的工程CMake 都能默認(rèn)找到依賴根目錄。新建工程的 CMakeLists 里不需要再寫(xiě)死路徑直接沿用環(huán)境配置。第三種習(xí)慣是對(duì)不需要的依賴做頏減在 CMake 配置階段關(guān)掉BUILD_OSG_LUA和所有非核心插件的編譯選項(xiàng)讓整個(gè)構(gòu)建時(shí)間縮短三分之一以上。全量包負(fù)責(zé)兜底頏減后的構(gòu)建負(fù)責(zé)交付。從那以后我每次換 OSG 主版本都強(qiáng)制走一遍同樣的動(dòng)作先解壓 3rdParty、校準(zhǔn)工具集、再清掉 build 緩存重配 CMake最后用 osgviewer 加載一個(gè)帶紋理的模型確認(rèn)插件鏈路完整隨后才敢繼續(xù)寫(xiě)業(yè)務(wù)代碼。這套流程看著樸素但把“依賴不匹配”這類的黑匣子消掉后編譯期報(bào)錯(cuò)反而變得直白可查。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取