Jetpack SceneCore
最近更新時間 | 穩定版 | 候選版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
2025 年 5 月 7 日 | - | - | - | 1.0.0-alpha04 |
宣告依附元件
如要新增 XR SceneCore 的依附元件,必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。
在應用程式或模組的 build.gradle
檔案中,新增所需構件的依附元件:
Groovy
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" }
Kotlin
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,請參閱這份指南。