{ } { }

Jetpack SceneCore

使用 3D 內容建構及操作 Android XR 場景圖表。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2024 年 12 月 12 日 - - - 1.0.0-alpha01

宣告依附元件

如要為 XR SceneCore 新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha01"
    // Required for Java
    implementation "com.google.guava:listenableFuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha01")
    // Required for Java
    implementation("com.google.guava:listenableFuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.0 版本

1.0.0-alpha01 版

2024 年 12 月 12 日

發布 androidx.xr.scenecore:scenecore-* 1.0.0-alpha01。

初始版本的功能：Jetpack SceneCore 的初始開發人員版本，這是用於建立及操作沉浸式場景和環境的 3D 場景圖表程式庫。這個程式庫可讓您將 3D 模型和內容面板放置及排列在彼此之間，以及在虛擬或真實環境中。

  • SpatialEnvironment：使用天空盒圖片和/或 3D 模型幾何圖形做為 XR 環境場景的背景，打造完全沉浸式的體驗。或者啟用穿透功能，讓虛擬場景可與使用者的實際環境整合。
  • PanelEntity：將標準 Android 版面配置和活動嵌入可浮動或固定在實際表面的空間化面板，藉此在 3D 場景中加入 2D 內容。
  • GltfModelEntity：在場景中放置、製作動畫，以及與 3D 模型互動。SceneCore 支援 glTF 檔案格式，方便與現有模型整合。
  • 空間音訊：在 3D 場景中加入環境音和定點音源，打造完全身歷的空間音效。
  • StereoSurfaceEntity：SceneCore 支援將內容算繪至 Android 途徑的左/右眼路由。這可用於以並排或上下格式算繪立體內容，例如立體相片、3D 影片或其他動態算繪的 UI。應用程式應使用 MediaPlayer 或 ExoPlayer 進行影片解碼。
  • 元件系統：SceneCore 提供功能強大且靈活的元件系統，可為 XR 內容新增功能，包括可讓使用者移動、調整大小，以及與模型和面板互動的操作元素。
  • 錨點：啟用透視功能後，您可以將面板和模型附加到實際表面，讓使用者在實際環境中無縫整合虛擬內容。
  • 使用者姿勢：存取使用者在虛擬場景中的位置，以便根據使用者的位置調整內容方向。
  • SpatialCapabilities：建構完全自動調整式應用程式，在可用時善用空間化功能，例如 UI 內容的 3D 定位。此外，應用程式執行時還能監控功能變更，根據使用者使用 Android XR 裝置的方式調整體驗。

已知問題

  • 目前，您必須使用 30 以上的最低 SDK 版本，才能使用 Jetpack SceneCore。解決方法是新增下列資訊清單項目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>，以便以 23 的 minSDK 建構及執行。
  • 在自動重建活動的各種情況下，工作階段可能會失效，包括調整主面板大小、連接外接裝置，以及切換淺色和深色模式。如果您遇到工作階段失效問題，解決方法包括讓主要面板無法調整大小、使用動態面板實體、停用活動重建功能 (針對特定設定變更)，或停用淺色/深色模式主題變更。
  • GltfEntity 不支援可移動和可調整大小的元件。
  • GltfEntity 不支援 Entity.getSize()。
  • Jetpack XR 應用程式必須在 AndroidManifest 中要求 android.permission.SCENE_UNDERSTANDING 權限。
  • 您只能在 Android XR 裝置上建立工作階段。目前，如果您建立工作階段並嘗試在非 Android XR 裝置上使用，就會收到 RuntimeException。
  • 透過 `SpatialEnvironment.setSpatialEnvironmentPreference() 將天空盒設為空值，並不會產生如說明所述的純黑天空盒。這可能會導致系統預設天空盒，或不會變更目前的天空盒。
  • SceneCore 客戶應在應用程式依附元件的 Gradle 設定中加入 implementation(“com.google.guava:listenablefuture-1.0”)。在日後推出的版本中，Scenecore 會將這個程式庫納入 api 依附元件，因此用戶端不必明確宣告該程式庫。
  • SceneCore 誤將 com.google.guava:guava-31.1-android 和 com.google.protobuf:protobuf-javalite 納入轉換依附元件。如果這會導致建構作業出現重複的類別錯誤，您可以放心排除這兩個依附元件。
  • 如果您的應用程式使用 SceneCore 並啟用 ProGuard，則在建立工作階段時會發生當機情形。解決方法是停用 ProGuard。如要進一步瞭解如何啟用 ProGuard，請參閱這份指南。