{ } { }

Jetpack SceneCore

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

宣告依附元件

如要為 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-alpha02 版

2025 年 2 月 12 日

發布 androidx.xr.scenecore:scenecore:1.0.0-alpha02 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

即將發生的破壞性變更，會影響 1.0.0-alpha02 之前建構的應用程式

  • 工廠方法已從 Session 類別移至各個類型的伴隨方法：
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) 已刪除，並由 ActivityPanelEntity.create(Session, Dimensions, String, Pose) 取代
    • Session.createAnchorEntity(Anchor) 已刪除，並由 AnchorEntity.create(Session, Anchor) 取代
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) 已刪除，並由 AnchorEntity.create(Session, Dimensions, Int, Int, Duration) 取代
    • Session.createEntity(String, Pose) 已刪除，並由 ContentlessEntity.create(Session, String, Pose) 取代
    • Session.createExrImageResource(String) 已刪除，並由 ExrImage.create(Session, String) 取代
    • Session.createGltfEntity(GltfModel, Pose) 已刪除，並替換為 GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) 已刪除，並替換為 GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) 已刪除，並替換為 InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) 已刪除，並替換為 MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) 已刪除，並由 PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose) 取代
    • Session.createResizableComponent(Dimensions, Dimensions) 已刪除，並由 ResizableComponent.create(Session, Dimensions, Dimensions) 取代
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) 已刪除，並替換為 StereoSurface.create(Session, Int, Dimensions, Pose)
  • 已移除下列已淘汰的方法：
    • 已刪除「Session.canEmbedActivityPanel(Activity)」。改用 getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY)。
    • 已刪除「Session.hasSpatialCapability(Int)」。getSpatialCapabilities() 會傳回 SpatialCapabilities 物件，因此已改用 getSpatialCapabilities().hasCapability() 這個更具區隔性的方式來檢查是否有空間功能。
    • Session.requestFullSpaceMode() 已刪除，並替換為 SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() 已刪除，並替換為 SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) 和 Session.setFullSpaceModeWithEnvironmentInherited(Bundle) 已移至擴充功能函式。開發人員檔案需要新增匯入項目才能存取：
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) 已移至擴充功能函式。開發人員檔案需要新增匯入功能才能存取：
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) 和 Session.getEntityForRtEntity(RtEntity) 已移至擴充功能函式。開發人員檔案需要新增匯入項目才能存取：
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • 「Session.unpersistAnchor(Anchor)」已刪除
  • 「Session.createPersistedAnchorEntity(UUID)」已刪除

已知問題

  • PanelEntity.setCornerRadius() 和 ActivityPanelEntity.setCornerRadius() 可能要等到下次移動面板時才會生效，您可以將面板移動到目前位置，以便緩解這種情況
  • 在 ActivitySpace 上呼叫 BoundsChanged 時，部分 ActivityPose 可能未正確更新。系統會在 ActivitySpace 的下一個 OnSpaceUpdated 呼叫中更新

破壞性與行為變更

  • 如果面板的寬度或高度小於 32 dp，PanelEntity 和 ActivityPanelEntity 的預設圓角半徑將為 32 dp 或更小

新 API 和功能

  • 推出 StereoSurface.CanvasShape，可用於建立 Spherical 和 Hemispherical 畫布，用於轉譯沉浸式媒體。
  • StereoSurfaceEntity.create() 現在可接受 CanvasShape 參數。(這個參數目前會遭到忽略，但會在日後的版本中使用)
  • StereoSurfaceEntity.create() 不再使用 Dimensions 參數。應用程式應透過設定 CanvasShape 控管畫布的大小
  • StereoSurfaceEntity 有可動態設定的 CanvasShape 成員。
  • StereoSurfaceEntity.dimensions 現在是唯讀屬性；應用程式應設定 CanvasShape 來變更維度。
  • StereoSurfaceEntity 現在允許在建構後重新設定 StereoMode。

其他變更

  • 將編譯時 minSDK 降至 24。所有 Jetpack XR API 在執行階段仍需要 API 34。
  • SceneCore 的工作階段工廠 (Session.create) 不再啟動意圖，以便取得 SCENE_UNDERSTANDING 權限。相反地，用戶端應用程式必須先明確要求使用者授予權限，才能嘗試建立錨點。如果使用者未授予權限，就無法建立錨點。

修正錯誤

  • getActivitySpacePose() 已修正為考量 ActivitySpace 比例，藉由傳回經過縮放的米值，而非一律傳回未經縮放的米值。transformPoseTo 現在也會在 ActivitySpace 涉及來源或目的地時，使用正確的單位來計算座標變更。
  • 只要使用 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) 傳遞空值天空盒偏好設定，現在就會將天空盒設為全黑。如要還原為系統預設的 Skybox 和幾何圖形，請使用 setSpatialEnvironmentPreference(null).

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，請參閱這份指南。