{ } { }

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 執行階段中的 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 的工作階段工廠 (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 用戶端應將 implementation(“com.google.guava:listenablefuture-1.0”) 新增至應用程式依附元件的 Gradle 設定。在日後推出的版本中，Scenecore 會將這個程式庫納入 api 依附元件，因此用戶端不必明確宣告該程式庫。
• SceneCore 誤將 com.google.guava:guava-31.1-android 和 com.google.protobuf:protobuf-javalite 納入轉換依附元件。如果這會導致建構作業出現重複的類別錯誤，您可以放心排除這兩個依附元件。
• 如果您的應用程式使用 SceneCore 並啟用 ProGuard，則在建立工作階段時會發生當機情形。解決方法是停用 ProGuard。如要進一步瞭解如何啟用 ProGuard，請參閱這份指南。