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

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

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

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

如要快速瞭解支援的材質，請參閱 Khronos 網站上的 glTF PBR 屬性。如要瞭解如何使用這些屬性和其他屬性自訂 3D 模型，請參閱「在應用程式中自訂 3D 模型」。

將 glTF 檔案新增至素材資源資料夾

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

將素材資源新增至 /models 目錄的範例

使用 SpatialGltfModel 新增 3D 物件

Android XR 支援 3D 模型的 glTF 格式，通常會儲存為 .glb 檔案。如要將這些物件新增至版面配置，請使用 SpatialGltfModel。SpatialGltfModel 是子空間可組合項，可讓您在空間版面配置中加入 glTF 格式的 3D 模型。這個 API 可簡化載入素材資源和管理其狀態的程序。

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

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

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

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

程式碼重點

  • 非同步載入：模型會以非同步方式載入。在初始組合期間，其固有大小可能為零；模型準備就緒後，版面配置會重新測量。
  • 控制狀態：使用 SpatialGltfModelState.status 查詢載入狀態或控制動畫。
  • 大小和縮放：根據預設，版面配置大小會與素材資源的定界框相符。您可以使用 SubspaceModifier.size 覆寫這項設定，將模型等比例縮放至指定範圍內。

使用 Compose SceneCoreEntity 放置 3D 模型

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

使用 Jetpack Scenecore 放置 3D 模型

如要載入 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 模型範例

使用 Scene Viewer 載入 3D 模型

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

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

以下範例說明如何使用 Intent，在 Android XR 的 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 使用這些功能。