在應用程式中新增 3D 模型

適用的 XR 裝置
這份指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
XR 頭戴式裝置
有線 XR 眼鏡
瞭解 XR 裝置類型 →

使用 3D 模型時，Jetpack XR SDK 支援 glTF 2.0 開放標準。Android XR 轉譯以 Jetpack XR SDK 建構的應用程式時，會使用 glTF 2.0 標準中指定的物理基礎轉譯(PBR) 技術 (以及支援的擴充功能) 轉譯 3D 模型。大多數數位內容創作 (DCC) 工具 (例如 Autodesk Maya、Maxon ZBrush、Blender 和 Spline) 都能將 3D 模型匯出為 glTF 格式 (.gltf 或 .glb 檔案)。

如果使用者或應用程式已指定 SpatialEnvironment 天空盒，3D 模型就會根據環境天空盒提供的光照資訊進行照明。反射材質和鏡面高光也會反映環境天盒。如果已啟用穿透功能，燈光、反射和鏡面反光會以明亮的房間和單一方向光為準。

如要快速瞭解支援的材質，請參閱 Khronos 網站上的「glTF PBR 屬性」。

使用 Jetpack XR SDK 建構的應用程式主要有兩種載入 3D 模型的方式。

將 3D 模型放入 ActivitySpace

取得 glTF 檔案後，下一步就是將檔案新增至 Android Studio 的素材資源目錄。建議您建立 models 目錄，以便更妥善地整理資產類型。

將資產新增至 /models 目錄的範例

如要載入 glTF 模型，請呼叫 GltfModel.create()。

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

此時模型會載入記憶體，但尚未算繪。 如果需要載入大量 3D 模型，或模型很大，建議事先非同步載入。這樣一來，使用者就不必等待模型載入記憶體。

我們需要將 glTF 新增至 ActivitySpace。呼叫 GltfModelEntity.create 建立實體，並將其放入 ActivitySpace。最佳做法是確認應用程式處於允許空間功能的狀態。

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

現在執行應用程式時，應該會看到載入的 3D 模型。

載入的 3D 模型範例

使用 SpatialGltfModel 新增 3D 物件

Android XR 支援 glTF 格式的 3D 模型，通常會儲存為 .glb 檔案。如要將這些物件新增至版面配置，請使用 SpatialGltfModel 可組合函式。這個 API 可簡化載入資產及管理資產狀態的程序。

如要顯示模型，請先使用 rememberSpatialGltfModelState 定義模型的來源和狀態。您可以從應用程式的 assets 資料夾、URI 或 raw data 載入模型。

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

定義狀態後，請使用 SpatialGltfModel 可組合函式，在子空間中算繪狀態。

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

將 3D 模型放入 Compose SceneCoreEntity

如要使用 SceneCoreEntity 放置 3D 模型，請先使用 GltfModel.create() 將 glTF 載入記憶體。接著，您可以將 3D 模型放入 SceneCoreEntity，將 SceneCore 元件與 Compose for XR 版面配置橋接。請參閱「使用 SceneCoreEntity 在版面配置中放置 3D 物件」。

使用 Scene Viewer 載入 3D 模型

如果您想以最簡單的方式載入 3D 模型，並提供基本互動功能，可以選擇在行動裝置上使用 Scene Viewer。Android XR 和行動裝置上的 Scene Viewer 主要差異在於，Scene Viewer 只支援指向 glTF 檔案的檔案 URI 參數，並會忽略所有其他參數。

Scene Viewer 是透過意圖叫用的獨立應用程式，並以全螢幕模式執行。因此，當您叫用時，應用程式將不再顯示，而 Scene Viewer 會成為焦點。您變更的任何環境都會重設為使用者的系統偏好設定。

以下範例說明如何在 Android XR 裝置上使用 Intent 在 Scene Viewer 中檢視 glTF 檔案：

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

如要進一步瞭解 Scene Viewer 的互動選項，請參閱3D 模型設計說明文件。

glTF 擴充功能

Jetpack XR SDK 支援多種 glTF 擴充功能，可擴充 3D 模型的功能。這些功能可透過 GltfModelEntity 和 Scene Viewer 使用。