在應用程式中新增 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"))
GltfEntity.kt

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

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

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

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

載入的 3D 模型範例

將 3D 模型放入 Compose SceneCoreEntity

您仍需使用 GltfModel.create() 將 glTF 載入記憶體，但如果使用 Jetpack Compose for XR 建立 UI，則可將 3D 模型放入 SceneCoreEntity。請參閱「使用 SceneCoreEntity 在版面配置中放置 3D 物件」。

為 3D 模型製作動畫

根據 glTF 規格，3D 模型可以內嵌動畫。 Jetpack XR SDK 支援骨架 (綁定)、剛性、變形目標 (混合形狀) 動畫。系統也支援使用 KHR_animation_pointer glTF 擴充功能建立的 Material 動畫。

如要播放動畫，請呼叫 startAnimation() 並指定動畫名稱。您可以選擇指定動畫是否應無限循環播放。

gltfEntity.startAnimation(loop = true, animationName = "Walk")
GltfEntity.kt

第二次呼叫 startAnimation 時，目前的動畫會停止，並開始播放新動畫。

您可以透過 getAnimationState() 查詢動畫的目前狀態。

如果呼叫 startAnimation() 時指定的動畫名稱不存在，呼叫會無聲無息地失敗，所有正在執行的動畫都會停止，且 getAnimationState() 會傳回 STOPPED。

使用 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.
}
GltfEntity.kt

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

glTF 擴充功能

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