QT 5.14.1 QT3D QML 3D模型檢視器開發初體驗

個人使用QT已有好幾年了，之前主要是為了解決跨平台開發的問題，只要寫一次程式（含人機界面），經不同平台上重新編譯後就分別能在Windows和Liunx上執行。當然使用QT好處還不只這個，除了本身是開源程式開發工具外，另有許多現成圖形介（GUI）元件（如Widget、QML等）可用，省去不少的開發時間。最近新的版本（QT 5.14 + Creator 4.11）剛釋出，在3D繪圖上提供了更多的支援(如QT3D QML），包括支援最新的3D模型、骨架、動畫的格式檔glTF 2.0（就像3D界的PDF格式），簡化許多以前開發3D繪圖功能要自己用OpenGL或OpenGL ES基礎功能去組合的動作。於是立馬下載來玩玩，但一如往常，使用新功能前總有一堆坑要填，在說明如何使用QT3D QML方式來讀取常見的3D模型OBJ（不帶材質貼圖）格式前，先讓大家看看執行結果圖(Fig. 1)。至於如何讀取帶材質、骨架動畫的glTF 2.0格式3D模型就留待下次分解。

完整程式及可執行程式請參考本工作室Github開源程式庫

Fig. 1 QT3D QML方式讀取OBJ檔格式靜態3D模型結果。(OmniXR整理製作)（點擊圖放大）

還沒有安裝QT的朋友可先依至官網下載（如Fig. 2所示），這裡是以Windows安裝進行說明。

Fig.2 QT下載最新版本步驟。(OmniXR整理製作)（點擊圖放大）

下載完成後點擊qt-opensource-windows-x86-5.14.1.exe（這裡以QT 5.14.1 Windows版為例）執行安裝（如Fig. 3所示），大部份情況都只需用預設設定值按下一步（Next鍵）即可，但這裡有幾個重要步驟需要注意，如下所示：

Step 2: 沒有QT帳號的朋友請先建立帳號，密碼要七位數以上，要包含大小寫英文字母及數字。若已有帳號的朋友可直接在上方欄位輸入帳號及密碼。

Step 7: 選擇習慣的編譯平台，個人為方便後續開發其它程式所以選了msvc 2017 64bit、mingw 7.3.0 32bit、mingw 7.3.0 64bit，若有需要其它類型平台請自行勾選。但請特別注意mingw 7.3.0 64bit目前無法支援QT3D QML（第一個大坑，害我爬文快一星期才確定問題），只有msvc 2017 64bit及mingw 32bit可支援，若要同時在Windows及Linux上執行的朋友則建議選用mingw 32bit。

Step 8: 勾選QT Charts, QT Quick 3D，之後開發相關3D繪圖程式會用的到，其它項目可依需求自行勾選。

Step 12: 建議使用預設路徑即可，若有需要請自行修改，但注意路徑名稱中不能有中文。

Fig.3 QT 5.14.1及Creator 4.11.0安裝步驟。(OmniXR整理製作)（點擊圖放大）

接下來就可以從Github下載範例程式來執行，其檔案非常少，程式也沒幾行，這就是使用QT3D QML方式的好處。以下就是本專案的檔案說明。

\QT3D_QML_Viewer
　├ assets ─ obj ─ toyplane.obj // 玩具小飛機3D模檔（不帶材質貼圖）
　├ main.cpp // 主程式
　├ main.qml // 主QML設定檔
　├ qml.qrc // QML資源檔
　├ QT3D_QML_Viewer.pro // QT專案檔
　└ QT3D_QML_Viewer.pro.user // QT編譯後自動產出

// main.cpp 主程式

#include <Qt3DQuickExtras/qt3dquickwindow.h>
#include <QGuiApplication>

int main(int argc, char* argv[])
{
    QGuiApplication app(argc, argv);
    Qt3DExtras::Quick::Qt3DQuickWindow view;
    view.setSource(QUrl("qrc:/main.qml"));
    view.show();

    return app.exec();
} 

// main.qml 主QML設定

import QtQuick 2.2 as QQ2
import Qt3D.Core 2.0
import Qt3D.Render 2.0
import Qt3D.Input 2.0
import Qt3D.Extras 2.0

Entity {
    id: sceneRoot

    Camera {
        id: camera
        projectionType: CameraLens.PerspectiveProjection
        fieldOfView: 45
        aspectRatio: 16/9
        nearPlane : 0.1
        farPlane : 1000.0
        position: Qt.vector3d( 0.0, 0.0, -40.0 )
        upVector: Qt.vector3d( 0.0, 1.0, 0.0 )
        viewCenter: Qt.vector3d( 0.0, 0.0, 0.0 )
    }

    OrbitCameraController {
        camera: camera
    }

    components: [
        RenderSettings {
            activeFrameGraph: ForwardRenderer {
                clearColor: Qt.rgba(0, 0.5, 1, 1)
                camera: camera
            }
        },
        // Event Source will be set by the Qt3DQuickWindow
        InputSettings { }
    ]

    Entity {
            id: topplane

            PhongMaterial {
                id: material
            }

            Mesh {
                id: toyplaneMesh
                source: "qrc:/assets/obj/toyplane.obj"
            }

            components: [toyplaneMesh, material]
    }
}

// qml.qrc QML資源檔

<RCC>
    <qresource prefix="/">
        <file>main.qml</file>
        <file>assets/obj/toyplane.obj</file>
    </qresource>
</RCC>

Fig. 4 編譯結果、部署及可執行結果。(OmniXR整理製作)（點擊圖放大）

接著以QT Creator開啟專案檔QT3D_QML_Viewer.pro後，設定編譯平台為mingw 7.3.0 32bit（亦可設為msvc 2017 64bit）Release，經建置（build）後即會得到執行檔QT3D_QML_Viewer.exe（如Fig. 4左欄所示）。直接按Ctrl+R鍵就可執行，會出現如Fig. 1結果畫面。按住滑鼠左鍵移動可平移模型，按住滑鼠右鍵移動可旋轉模型，滾動滑鼠中鍵可縮放視野大小。

本來以為拿著這個執行檔就能執行，但發現竟無法執行，會出現缺xxx.dll的訊息（第二個大坑）。突然想到安裝QT時它並沒有自動將相關路徑增加到%PATH%中，於是啟動命令列（cmd）模式，輸入下列指令，再切換到執行檔案路徑(cd 完整工作路徑)執行QT3D_QML_Viewer.exe，果然就正常了。

set PATH=C:\Qt\Qt5.14.1\5.14.1\mingw73_32\bin;%PATH%

但回到視窗模式檔案總管後，直接點擊執行檔仍出現同樣問題，因為執行時所需相關程式還是沒有連結。於是依錯誤訊息從"C:\Qt\Qt5.14.1\5.14.1\mingw73_32\bin"下找到對應的dll檔複製到QT3D_QML_Viewer.exe所在路徑，但不幸的是仍無法順利啟動。經爬文後得知可用\mingw73_32\bin\下的windeploy.exe協助自動收集部署所需相關檔案。於是進入命令列模式，如上設定路徑後，切換至執行檔工作路徑，執行下列命令得到如Fig. 4中欄所示結果。

C:\Qt\Qt5.14.1\5.14.1\mingw73_32\bin\windeployqt.exe QT3D_QML_Viewer.exe

回到檔案總管模式點擊後果然可以順利執行，但啟動後並沒有看到如Fig. 1結果而是一片全白，連回到QT Creator重新執行也是同樣結果，程式視窗一片全白（第三個大坑）。一時間不知道發生什麼問題，反複實驗、線上爬文仍找不到解法，只好用最笨的方法，手工處理，將相關程式一個一個複製到執行檔工作路徑下（如Fig. 4右欄所示），搞了幾個小時，果然解決問題，順利執行起來。

從Fig. 4右欄中可看出，紅色及紫色框標出的檔案是重點，尤其是\qml下的相關檔案，少了這些檔案QT3D QML無法順利啟動，但又沒有警告訊息直接卡住，所以才會一片全白。另外在手工複製檔案測試時發現其實透過windeployqt.exe自動部署的檔案有很多暫時用不到（灰色虛線標示檔案）可保留無妨。

以上是個人花了一星期多的填坑心得，希望有興趣研究的朋友看完後能少踩一些坑。此次對程式內容並沒有很多說明，有興趣的朋友可以直接參考官網範例說明，後續會繼續測試QT3D QML相關用法，待有新結果後再分享給大家，敬請期待。

參考文獻：

[01] QT 5.14 QT3D官方說明網頁 https://doc.qt.io/qt-5/qt3d-index.html

[02] QT 5.14 Qt3D官方範例 https://doc.qt.io/qt-5/qt3d-examples.html

[03] QT 5.14和QT Creator工具簡介 https://blog.csdn.net/somken/article/details/104053605