Jetpack SceneCore

使用 3D 內容建構及操控 Android XR 場景圖。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 10 月 22 日 - - - 1.0.0-alpha08

宣告依附元件

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

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

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha08"

    // Optional dependencies for asynchronous conversions
    implementation "androidx.xr.scenecore:scenecore-guava:1.0.0-alpha08"

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

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha08")

    // Optional dependencies for asynchronous conversions
    implementation("androidx.xr.scenecore:scenecore-guava:1.0.0-alpha08")

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

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-alpha08 版本

2025 年 10 月 22 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha08。1.0.0-alpha08 版包含這些修訂項目。

API 變更

  • 已將 ActivityPanelEntity.moveActivity 重新命名為 transferActivity (I273c5、b/430332856)

修正錯誤

  • :xr:scenecore:scenecore-spatial-rendering 和 :xr:scenecore:scenecore-spatial-core 已新增為 :xr:scenecore:scenecore 的實作依附元件 (I6ab65、b/447000520)
  • 如果工作階段毀損後存取 session.scene，系統會擲回例外狀況。(I77e6f)

1.0.0-alpha07 版本

2025 年 9 月 24 日

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

API 變更

  • 將 fixedAspectRatio 重新命名為 isFixedAspectRatioEnabled，並設為布林值屬性 (I5c4e8、b/440588971)
  • Scenecore Fakes 現在位於 xr:scenecore:scenecore-testing 模組中。(Idd951)
  • 已將 shouldAutoHideContent 重新命名為 isAutoHideContentWhileResizingEnabled，並將 shouldAlwaysShowOverlay 重新命名為 isAlwaysShowOverlayEnabled (I97c36、b/432335421)
  • 更新 SceneCore TextureSampler 常數，提高可讀性，例如 TextureSampler.MinFilter.LINEAR 現在是 TextureSampler.MIN_FILTER_LINEAR (Ib159c)
  • 場景的 setKeyEntity 設定程式已併入 keyEntity 變數。如果將 keyEntity 設為無法移動的 Entity (例如 AnchorEntity)，系統會擲回 IllegalArgumentException，而不是傳回布林值 false。(I62080、b/428721695、b/422215745)
  • 場景的 SpatialModeChangeListener 變數已替換為 setSpatialModeChangedListener。它會接收 Consumer<SpatialModeChangeEvent>，而不是 SpatialModeChangedListener。setSpatialModeChangedListener 現在可選擇接收執行者。(I62080、b/428721695、b/422215745)
  • 從 ActivityPanelEntity.startActivity 移除 bundle 參數 (I64344、b/430332856、b/430333040)
  • SpatializerConstants.SOURCE_TYPE_BYPASS 已重新命名為 SpatializerConstants.SOURCE_TYPE_DEFAULT。(Ifc7fe、b/422215565)
  • 新增 SpatialSoundPool.PLAY_FAILED 常數。(Ifc7fe、b/422215565)
  • 已將預設引數新增至 SpatialSoundPool.play 方法。(Ifc7fe、b/422215565)
  • 已移除 SpatialAudioTrackBuilder 中設定器的傳回值。(Ifc7fe、b/422215565)
  • SurfaceEntity 變更
    • SurfaceEntity.CanvasShape已重新命名為Shape
    • SurfaceEntity.CanvasShape.Vr180Hemisphere已重新命名為Hemisphere
    • SurfaceEntity.CanvasShape.Vr360Sphere已重新命名為Sphere
    • SurfaceEntity.EdgeFeatheringParams.SmoothFeather已重新命名為RectangleFeather
    • SurfaceEntity.EdgeFeathingParams.SolidEdge已重新命名為NoFeathering
    • SurfaceEntity.ContentSecurityLevel已重新命名為SurfaceProtection
    • SurfaceEntity.ContentSecurityLevel.{values}新增了 SURFACE_PROTECTION_ 前置字串。
    • SurfaceEntity.SuperSampling.{$values}新增了 SUPER_SAMPLING_ 前置字元
    • SurfaceEntity.StereoMode.{values}新增了 STEREO_MODE_ 前置字元
    • SurfaceEntity.ContentColorMetadata.maxCLL 已重新命名 maxContentLightLevel (I7eb5f、b/422216050、b/427529950)
  • 已將 launchActivity 重新命名為 startActivity (I7db90、b/430332856)
  • 已移除 Scene.activitySpaceRoot。請改用 Scene.activitySpace。(I05ee8、b/378706624、b/422215745)
  • configureBundleForFullSpaceModeLaunch 和 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited 分別重新命名為 createBundleForFullSpaceModeLaunch 和 createBundleForFullSpaceModeLaunchWithEnvironmentInherited，並移至 LaunchUtils.kt 檔案做為頂層方法，且將 Session 做為第一個參數 (I64a2c、b/437186050)
  • GroupEntity 工廠現在會傳回 GroupEntity 型別，而非 Entity。(I66042)

修正錯誤

1.0.0-alpha06 版本

2025 年 8 月 13 日

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

API 變更

  • 取消限制 SceneCore 的 SceneCore's BaseEntity 和 BaseScenePose API (88c0ff6)

1.0.0-alpha05 版本

2025 年 7 月 30 日

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

新功能

  • Perceived Resolution API 已新增至面板實體和 SurfaceEntities。(I118f6)
  • PerceivedResolution 新增至 Scene.kt 的回呼方法，用於監控 HSM 中活動主要面板的感知解析度。(I58084)
  • SurfaceEntity - 新增支援功能，讓應用程式在建立時要求超級取樣。這可讓應用程式使用超取樣濾鏡進行反鋸齒。(I06913)
  • 已將 recommendedContentBoxInFullSpace 屬性新增至 ActivitySpace。在完整空間模式下，系統會傳回建議的內容放置方塊。(I4cd6f)
  • 為可移動的修飾符提供多載建構函式，可進行錨定。(Ic0c70)

API 變更

這個版本對 SceneCore 進行了大規模的 API 變更，許多類別已重新命名和/或移至不同模組，且大多數的 getter/setter 方法已替換為 Kotlin 屬性。我們預期在第一個 Beta 版發布前，API 會出現破壞性變更，但不會造成太多干擾或變動。

  • 下列類別和介面已重新命名和/或移動：androidx.xr.scenecore.PixelDimensions 至 androidx.xr.runtime.math.IntSize2d；androidx.xr.scenecore.Dimensions 至 androidx.xr.runtime.math.FloatSize3d；androidx.xr.scenecore.ActivityPose 至 ScenePose、androidx.xr.scenecore.ContentlessEntity 至 GroupEntity、androidx.xr.scenecore.PlaneType 至 PlaneOrientation；androidx.xr.scenecore.PlaneSemantic 至 PlaneSemanticType。(Ifd405)(I3b622) (If534d)
  • Scene 屬性的多個設定器已設為私有，這些設定器不應由 SceneCore 用戶端突變：activitySpace、activitySpaceRoot、mainPanelEntity、perceptionSpace、spatialCapabilities、spatialEnvironment 和 spatialUser。(I2f506)
  • 在實體中，將下列項目變更為屬性：get/setParent()、setContentDescription；已淘汰 Entity.is/setHidden()，請改用 Entity.is/setEnabled。(Ibc4c6)
  • 已移除 androidx.xr.scenecore.BasePanelEntity 類別，請改用 PanelEntity。將 PanelEntity 的 getter 和 setter 換成屬性。PanelEntity.size 屬性已從 Float3dSize 變更為 Float2dSize。移除已淘汰的 androidx.xr.scenecore.PanelEntity.getPixelDimensions 方法，請改用 getSizeInPixels。(Icc174)
  • 以 Runnable 取代 androidx.xr.scenecore.OnSpaceUpdatedListener。(I19308)
  • 以屬性取代 SpatialUser.getCameraViews()。(Ib0cc5) 針對 ExrImage 和 GltfModel: 變更 create 方法，使其成為暫停函式；修改建立參數，接受 Uri 或 Path，而非 String。(Id8883) (I0d247)、(I25706)
  • 已將 SpatialEnvironment.requestFullSpaceMode 和 SpatialEnvironment.requestHomeSpaceMode 移至 Scene，例如使用 session.scene.requestFullSpaceMode() 而不是 session.scene.spatialEnvironment.requestFullSpaceMode()。addOnPassthroughOpacityChangedListener 和 addOnSpatialEnvironmentChangedListener 現在有可接受選用執行器的覆寫。(I12fe0) (I6b21e)
  • 已移除下列已淘汰的 SpatialEnvironment 方法：togglePassthrough、setPassthrough、setPassthroughOpacity、getPassthroughMode、getPassthroughOpacity、setSkybox 和 setGeometry。同時也移除了已淘汰的 SpatialEnvironment.PassthroughMode 類別 (I927bd) (I927bd) (I927bd)
  • 將下列 SpatialEnvironment 取得器和設定器替換為 Kotlin 屬性：getCurrentPassthroughOpacity()、get/setPassthroughOpacityPreference()、get/setSpatialEnvironmentPreference()、isSpatialEnvironmentPreferenceActive() (I33a7b) (Ie06e2) (Ie06e2)
  • SpatialEnvironmentPreference.preferredPassthroughOpacity 類型已從 Float? 變更為 Float。不再接受空值。而是使用 SpatialEnvironment.NO_PASSTHROUGH_OPACITY_PREFERENCE 表示沒有不透明度偏好設定。(I40107)
  • 在建立方法中，將 windowBoundsPx 參數更新為 pixelDimensions，並將其類型從 Rect 變更為 IntSize2d。(I1926e)
  • SpatialEnvironment 建構函式現在是內部函式 (I75a51)
  • 將 SpatialPointerIconNone 和 SpatialPointerIconCircle 類別替換為伴生物件 SpatialPointerIcon.NONE 和 SpatialPointerIcon.CIRCLE (I416d2)
  • SpatialPointerComponent 中的 SpatialPointerIcon 不再可為空值。請使用 SpatialPointerIcon.DEFAULT，而非空值，表示應使用系統預設指標圖示。(I416d2)
  • 以唯讀屬性取代 androidx.xr.scenecore.AnchorEntity.getState()。為求清楚，已重新命名 AnchorEntity.create() 方法的參數。在 AnchorEntity 的方法中，用於設定及新增事件監聽器時，事件監聽器已移至最後一個引數，以啟用結尾 lambda。已將 AnchorEntity 的 androidx.xr.scenecore.OnStateChangedListener 替換為 Consumer<AnchorEntity.State>。(I472e0)
  • GltfModelEntity.getAnimationState() 現在是屬性。(I10b29)
  • 以屬性取代 ActivitySpace.getBounds()。「ActivitySpace.addBoundsChangedListener」已重新命名為「ActivitySpace.addOnBoundsChangedListener」。將 ActivitySpace.setOnSpaceUpdatedListener 替換為新增/移除方法。(I4c956)
  • AnchorPlacement: planeTypeFilter 已重新命名為 anchorablePlaneOrientations，planeSemanticFilter 已重新命名為 anchorablePlaneSemanticTypes。將 MovableComponent 新增至 AnchorEntity 或 ActivitySpace 會傳回 false，MoveListener 已重新命名為 EntityMoveListener shouldDisposeParentAnchor，EntityMoveListener shouldDisposeParentAnchor 已重新命名為 disposeParentOnReAnchor systemMovable，create 函式已移除 disposeParentOnReAnchor systemMovable，改用 creeateCustomMovable、createSystemMovable 和 createAnchorable (If11c4)
  • 移除 SurfaceEntity.featherRadiusX/Y 並新增 EdgeFeatheringParams 類別概念。(Ic78fc)
  • PanelEntity.enablePanelDepthTest() 方法已替換為 panelClippingConfig 屬性。將 Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true) 設為啟用深度測試，或設為 PanelClippingConfig(isDepthTestEnabled = false) 停用深度測試。(I0cbe0)
  • Scene.mainPanelEntity 現在是 MainPanelEntity 類型，而非 PanelEntity (I7125a)
  • 已將 Scene 的 setFullSpaceMode 方法重新命名為 configureBundleForFullSpaceModeLaunch，並將 setFullSpaceModeWithEnvironmentInherited 方法重新命名為 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited。(I0cbe0) (I0cbe0)
  • SpatialVisibility 的 UNKNOWN、OUTSIDE_FOV、PARTIALLY_WITHIN_FOV 和 WITHIN_FOV 值已分別重新命名為 SPATIAL_VISIBILITY_UNKNOWN、SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW、SPATIAL_VISIBILITY_PARTIALLY_WITHIN_FIELD_OF_VIEW 和 SPATIAL_VISIBILITY_WITHIN_FIELD_OF_VIEW (Ie7e8c)
  • SpatialVisibility 類別已替換為具有 const Int 值的公開物件。setSpatialVisibilityChangedListener 現在接受 Consumer<Int>，而非 Consumer<SpatialVisibility> (Ie7e8c)
  • PointerCaptureComponent 常數已重新命名並移至 PointerCaptureComponent.PointerCaptureState 物件 (I9c7ac)
  • 以 Consumer<Int> 取代 PointerCaptureComponents' StateListener。(I9c7ac)
  • 將 InputEventListener 替換成 Consumer<InputEvent> (I9c7ac)
  • setPreferredAspectRatio 已從 Scene 類別移至 SpatialWindow 物件，並將 Session 做為第一個參數。(I7b717)
  • Entity.setHidden() 已由 Entity.setEnabled() 取代，Entity.isHidden() 已由 Entity.isEnabled() 取代。setHidden(false) 等於 setEnabled(true) 和 isHidden() == !isEnabled()。(Icf0de)
  • Entity.contentDescription 類型已從 String 變更為 CharSequence。(Ie59be)
  • 如果未授予足夠的權限，Session.create 和 Session.configure 現在會擲回 SecurityException，而不是傳回 SessionCreatePermissionsNotGranted 或 SessionConfigurePermissionsNotGranted。(I7c488)
  • ResizableComponent.create 現在需要 Consumer<ResizeEvent> ResizeEventListener 已取代 Consumer<ResizeEvent> ResizableComponent.size 已重新命名為 ResizableComponent.affordanceSize ResizableComponent.minimumSize 已重新命名為 ResizableComponent.minimumEntitySize ResizableComponent.maximumSize 已重新命名為 ResizableComponent.maximumEntitySize，ResizableComponent.autoHideContent 已重新命名為 ResizableComponent.shouldAutoHideContent，ResizableComponent.forceShowResizeOverlay 已重新命名為 ResizableComponent.shouldAlwaysShowOverlay (I97a2d)
  • 將 androidx.xr.scenecore 和 androidx.xr.compose 的 minSDK 減少至 24。XR 套件在執行階段仍需使用 API 34。(I17224)
  • 已移除所有 Jetpack XR 套件的 RequiresApi(34) 限制。由於 Jetpack XR 目前僅適用於 API 級別 34 以上的裝置，因此這項限制是多餘的。(Iae0f8)
  • 主要的 SceneCore 構件 (xr:scenecore:scenecore) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依附 xr:scenecore:scenecore-guava 程式庫來存取相容的 API。(If221b)
  • 使用 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本 (Idb6b5)
  • 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版的預設值) (Ia8420)
  • 所有傳回 ListenableFuture 的非同步方法都已替換為 Kotlin 暫停函式。Java 開發人員如要使用以 ListenableFuture 為基礎的非同步方法，而非 Kotlin 暫停函式，現在必須使用 :xr:scenecore-scenecore-guava 中的擴充功能函式。舉例來說，GuavaExrImage 包含 Guava 等效的 ExrImage 非同步函式，GuavaScenePose 包含 Guava 等效的 ScenePose 非同步函式，GuavaGltfModel 包含 Guava-equivalent GltfModel 非同步函式等。(If7283) (I0af60) (If7283) (Ia8515) (I4efdf) (I54bbf) (I3467a) (I82a33)

修正錯誤

  • 更新 Jetpack XR Scenecore ProGuard 規則，防止縮小用戶端發生 AbstractMethodError。(I91a01)
  • 其他修正，支援 Jetpack XR SceneCore 的 Proguard 縮減功能 (I4f47e)
  • 修正錯誤：如果系統傳回的 hitPosition 為空值，InteractableComponent 可能會導致 InputEvent 的 HitInfo 發生當機情形 (I7a695)hitPosition
  • Config *Mode vals 已重新命名，以反映其行為。(I6d247)
  • 修正 SceneCore TestApp 中的視野和 HitTest 問題。(I2c51e)
  • 修正 SpatialCapabilities.hasCapability() 中的錯誤，現在只有在所有功能都為 true 時，才會傳回 true，而不是只要其中一個功能為 true 就會傳回 true。(I2cd40)
  • SurfaceEntity.StereoMode.TOP_BOTTOM，現在左眼會看到上方地圖，右眼則會看到下方地圖。(I4ae68)

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)) 傳遞空值天空盒偏好設定時，天空盒會設為全黑。如要還原為系統預設天空盒和幾何圖形，請使用 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，請參閱這份指南。