Jetpack SceneCore

宣告依附元件

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

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

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha04"
    // 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-alpha04"
}

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha04")
    // 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-alpha04")
}

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-alpha04 版本

2025 年 5 月 7 日

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

新功能

• 現在，面板實體 (不含內嵌活動) 也支援返回處理。如要讓返回鍵處理作業正常運作，您需要在 Android 資訊清單中指定 android:enableOnBackInvokedCallback= "true"。
• StereoSurfaceEntity 現在支援透過兩個新的 StereoMode 值 (MULTIVIEW_LEFT_PRIMARY 和 MULTIVIEW_RIGHT_PRIMARY) 播放 MV-HEVC。
• PanelEntity.setSize 和 PanelEntity.getSize 現在會傳回父項空間中的大小。
• Entity.setPose、Entity.getPose、Entity.setScale、Entity.getScale、Entity.setAlpha 和 Entity.getAlpha 現在會採用新的參數 relativeTo，可讓您取得/設定與不同空間相關的值。支援的值包括「Parent」、「Activity」和「Real World」空間，這個參數的預設值為「Parent」。
• 新增至 SessionExt.kt 的空間可見度回呼擴充方法，可監控場景內容在使用者視野內或視野外的移動情形。
• 已將 setPointSourceParams 新增至 SpatialAudioTrack，因此您可以在建構軌跡後更新參數。
• 新增了 Scene 類別，並參照 Scenecore API。場景會以工作階段的擴充屬性形式提供。SessionExt 內的函式已移至 Scene，因此需要調整匯入項目，例如 SessionExt.getScene(session)。addSpatialCapababilitiesChangedListener對SessionExt.addSpatialCapabilitiesChangedListener。
• 已新增 ActivityPose.hitTestAsync，可針對虛擬內容啟用 hitTest。
• 新增了 SpatialPointerComponent 元件類型，讓用戶端指定指標的顯示圖示，或停用圖示。目前這個元件只能附加至 PanelEntity 個執行個體。
• 我們推出新的 PanelEntity 工廠，可接受以公尺或像素為單位的面板尺寸。已移除舊版 PanelEntity 工廠，該工廠會採用兩個 Dimension 類型參數做為面板。

API 變更

• 已移除所有 Jetpack XR 套件的 RequiresApi(34) 限制。由於 Jetpack XR 目前僅適用於 API 級別 34 以上的裝置，因此這項限制是多餘的。(Iae0f8)
• 使用 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本 (Idb6b5)
• 已移除「PermissionHelper」類別。
• PanelEntity.getPixelDensity 已淘汰。
• 移除 PanelEntity.setPixelDimensions 和 PanelEntity.getPixelDimension，並替換為 setSizeInPixels 和 getSizeInPixels。
• 已移除Entity.getActivitySpaceAlpha。可以替換為 Entity.getAlpha(Space.Activity)。
• 已移除Entity.getWorldSpaceScale。可以替換為 Entity.getScale(Space.REAL\_WORLD)。
• SceneCore 中的 Session 類別已刪除，改用 XR Runtime 中的 Session。
• StereoSurfaceEntity 已重新命名為 SurfaceEntity。
• 移除 Entity.setSize 和 Entity.getSize，並將相同方法新增至 PanelEntity。
• PointSourceAttributes 已重新命名為 PointSourceParams。
• SpatializerConstants.SOURCE\_TYPE\_BYPASS 已重新命名為 SpatializerConstants.SOURCE\_TYPE\_DEFAULT。
• 「PointSourceParams」實體已從公開存取權改為內部存取權。
• AnchorEntity.create 現在需要透過 Session.configure() 設定 PlaneTrackingMode。
• SpatialUser API 現在需要於 Session.configure() 中設定 HeadTrackingMode。
• 如果未附加 ResizableComponent，系統會提供 INFO 層級的記錄，而非 ERROR 層級的記錄。
• Fov 類別現在是一般 Kotlin 類別。
• 分割 Entity.kt，將每個具體實體類型放入各自的檔案。
• 建立新的 PanelEntity 時，大部分的「檢視區塊」都會重新成為 FrameLayout 的子項。這有助於搭配空間面板使用 LayoutInspector。
• 目前使用的 XrExtensions 例項已盡可能向平台註冊，有助於偵錯應用程式。

修正錯誤

• 新增修正程式，避免移動含有 MovableComponent 和 AnchorPlacement 的 PanelEntity 時發生異常終止問題
• 修正問題：ResizableComponent 在 onResizeStart 回呼中提供過時大小。
• 修正多次呼叫 JxrPlatformAdapterAxr 的 dispose() 時發生的異常終止問題。

1.0.0-alpha03 版本

2025 年 2 月 26 日

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

新功能

• 現在 Jetpack XR 程式碼支援 Proguard 壓縮功能

修正錯誤

• 其他修正，支援 Jetpack XR SceneCore 的 Proguard 縮減功能 (I4f47e)
• 更新 Jetpack XR Scenecore ProGuard 規則，防止 AbstractMethodError 用於縮小用戶端。(I91a01)

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 的工作階段 Factory (Session.create) 不再啟動意圖來取得 SCENE_UNDERSTANDING 權限。用戶端應用程式必須先明確要求使用者授予權限，才能嘗試建立錨點。如果使用者未授予權限，錨點建立作業就會失敗。

修正錯誤

• getActivitySpacePose() 已修正，可根據 ActivitySpace 比例傳回以縮放比例計算的公尺值，而非一律傳回未縮放的公尺值。如果 ActivitySpace 涉及來源或目的地，transformPoseTo 現在也會使用正確的單位來計算座標變化。
• 現在使用 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) 傳遞空值 skybox 偏好設定時，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 版面配置和活動嵌入空間化面板，即可將 2D 內容新增至 3D 場景，這些面板可浮動或錨定在現實世界表面。
• GltfModelEntity：在場景中放置 3D 模型、為模型製作動畫，以及與模型互動。SceneCore 支援 glTF 檔案格式，方便您與現有模型整合。
• 空間音訊：在 3D 場景中加入環境和點音訊來源，享受完全沉浸式的空間化音效。
• StereoSurfaceEntity：SceneCore 支援將內容轉送至 Android Surface 的左/右眼。這項功能可用於以並排或上下格式算繪立體內容，例如立體相片、3D 影片或其他動態算繪的 UI。應用程式應使用 MediaPlayer 或 ExoPlayer 進行影片解碼。
• 元件系統：SceneCore 提供強大且彈性的元件系統，可為 XR 內容新增功能，包括供使用者移動、調整大小及與模型和面板互動的輔助功能。
• 錨點：啟用直通功能後，您可以將面板和模型附加至實際表面，讓使用者在真實環境中順暢整合虛擬內容。
• 使用者姿勢：存取使用者在虛擬場景中的位置，根據使用者位置調整內容方向。
• SpatialCapabilities：建構完全自動調整式應用程式，在可用的情況下充分運用空間化功能，例如 UI 內容的 3D 定位。不僅如此，應用程式還能在執行期間監控功能變更，根據使用者使用 Android XR 裝置的方式調整體驗。

已知問題

• 目前使用 Jetpack SceneCore 的最低 SDK 版本為 30。如要解決這個問題，請新增下列資訊清單項目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>，以便使用 minSDK 23 建構及執行。
• 在各種情況下，系統會自動重新建立活動，導致工作階段失效，包括調整主面板大小、連線周邊裝置，以及在淺色和深色模式之間切換。如果遇到工作階段失效問題，可以採取下列因應措施：讓主面板無法調整大小、使用動態面板實體、針對特定設定變更停用活動重建功能，或是停用淺色/深色模式主題變更。
• GltfEntity 不支援可移動和可調整大小的元件。
• GltfEntity 不支援 Entity.getSize()。
• Jetpack XR 應用程式必須在 AndroidManifest 中要求 android.permission.SCENE_UNDERSTANDING 權限。
• 建立工作階段僅支援 Android XR 裝置。此時，如果您建立 Session 並嘗試在非 Android XR 裝置上使用，系統會擲回 RuntimeException。
• 透過 `SpatialEnvironment.setSpatialEnvironmentPreference()` 將天空盒設為空值，不會如文件所述產生全黑天空盒。這可能會導致系統預設的 Skybox 或目前的 Skybox 沒有任何變更。
• 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，在建立 Session 時會異常終止。如要暫時解決這個問題，請停用 ProGuard。如要進一步瞭解如何啟用 ProGuard，請參閱這份指南。