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

使用 3D 模型時，Jetpack XR SDK 支援 glTF 2.0 開放標準。當 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 屬性。

使用 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
    .hasCapability(SpatialCapabilities.SPATIAL_CAPABILITY_3D_CONTENT)
) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}
GltfEntity.kt

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

載入 3D 模型的範例

將 3D 模型放入 Compose 容器

雖然您仍需使用 GltfModel.create() 將 glTF 載入記憶體，但如果您使用 Jetpack Compose for XR 建立 UI，則可以將 3D 模型放入 Volume。請參閱「使用 Volume 在版面配置中放置 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 檢視器將獲得焦點。您可能變更的任何環境都會重設為使用者的系統偏好設定。

以下是使用 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 支援多種 gfTF 擴充功能，可擴充 3D 模型的功能。您可以透過 GltfEntity 和 Scene Viewer 使用這些功能。