XR 執行階段

使用原生執行階段啟動自訂 AR 或 3D 工作階段。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 10 月 22 日 - - - 1.0.0-alpha07

宣告依附元件

如要為 XR 執行階段新增依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱「 Google 的 Maven 存放區」。

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

Groovy

dependencies {
    implementation "androidx.xr.runtime:runtime:1.0.0-alpha07"

    // Optional dependencies for asynchronous conversions
    implementation "androidx.xr.runtime:runtime-guava:1.0.0-alpha07"
    implementation "androidx.xr.runtime:runtime-rxjava3:1.0.0-alpha07"

    // Use in environments that do not support OpenXR
    testImplementation "androidx.xr.runtime:runtime-testing:1.0.0-alpha07"
}

Kotlin

dependencies {
    implementation("androidx.xr.runtime:runtime:1.0.0-alpha07")

    // Optional dependencies for asynchronous conversions
    implementation("androidx.xr.runtime:runtime-guava:1.0.0-alpha07")
    implementation("androidx.xr.runtime:runtime-rxjava3:1.0.0-alpha07")

    // Use in environments that do not support OpenXR
    testImplementation("androidx.xr.runtime:runtime-testing:1.0.0-alpha07")
}

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

意見回饋

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

建立新問題

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

1.0 版本

1.0.0-alpha07 版本

2025 年 10 月 22 日

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

API 變更

  • 移除 SessionConfigureConfigureNotSupported，並替換為 UnsupportedOperationException。(I7680f)

1.0.0-alpha06 版本

2025 年 9 月 24 日

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

API 變更

  • HandJointType 已從 xr:runtime:runtime 移至 xr:arcore:arcore。(Iadb9c、b/409058039)
  • 將 componentWiseMultiplication 的時間運算子從 Vector2、Vector3、Vector4 改為縮放，並移除運算子符號，與其他數學程式庫保持一致。此外，我們也從 Vector 類別中移除 componentWiseDivision，改用 Vector.scale(otherVector.inverse())。(I8e1f6、b/399146447)
  • 新增 [unscaled] 即可傳回比例為一的 Matrix。(I6381d、b/434928658)
  • :xr:runtime:runtime-guava 將移除，因為 Coroutines.kt 已改為 SuspendtoFutureAdapter。(I0cd3c、b/406597902)

1.0.0-alpha05 版本

2025 年 7 月 30 日

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

新功能

  • 新增 HandJointType 和 TrackingState。(I55880、b/334645808)
  • 將 Config 實作設為公開。(I95860、b/334645808)
  • 推出新的 SessionCreateResult 和 SessionConfigureResult 類型。(Icb8cb、b/334645808)
  • 新增 BoundingBox 類別，代表 3D 空間中與軸對齊的邊界方塊，由最小和最大角點定義。(Ic68c5、b/423073468)

API 變更

  • 已將 androidx.xr.scenecore.PixelDimensions 重新命名為 androidx.xr.runtime.math.IntSize2d，並移至該處。已將 androidx.xr.scenecore.Dimensions 重新命名為 androidx.xr.runtime.math.FloatSize3d，並移至該處。「androidx.xr.scenecore.PlaneType」已重新命名為「androidx.xr.scenecore.PlaneOrientation」。「androidx.xr.scenecore.PlaneSemantic」已重新命名為「androidx.xr.scenecore.PlaneSemanticType」。(Ifd405、b/416456228)
  • 已移除 androidx.xr.runtime.FoV 類別。請改用 androidx.xr.runtime.FieldOfView。(I9ae27)
  • 新增 Session.create 的額外超載，可為要附加的 Session 提供 LifecycleOwner。請注意，您仍須提供活動，才能取得資源擁有權，且 LifecycleOwner 必須限定在活動範圍內。(I1690b)
  • 已將 FakeRuntimeAnchor.anchorsCreated 重新命名為 anchorsCreatedCount (I96df9、b/424441218)
  • 設定 *Mode 值已重新命名，以反映其行為。(I6d247、b/414648065)
  • 使用 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本 (Idb6b5、b/344563182)
  • 與資訊清單字串相關的 API 已從 :xr:runtime:runtime 遷移至 :xr:runtime:runtime-manifest。套件名稱已從「androidx.xr.runtime」變更為「androidx.xr.runtime.manifest」。(I610ad、b/418800249)
  • Session.resume()、Session.pause() 和 Session.destroy() 已從 API 介面中移除。工作階段不再是 LifecycleOwner。現在，Session 的生命週期會附加至 Session.create() 中傳遞的 Activity 生命週期。(I28a03)
  • 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版的預設值) (Ia8420、b/326456246)
  • 主要執行階段構件 (:xr:runtime:runtime) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依賴 :xr:runtime:runtime-guava 存取相容的 API。(I05d4a、b/426639315)
  • 主要執行階段構件 (:xr:runtime:runtime) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依附 xr:runtime:runtime-rxjava3 程式庫來存取相容的 API。(I64122、b/426639775)
  • 將協同程式移至 :xr:runtime:runtime-guava，並將 Flow 移至 :xr:runtime:runtime-rxjava3。(I60ae9)
  • 如果未授予足夠的權限，Session.create 和 Session.configure 現在會擲回 SecurityException，而不是傳回 SessionCreatePermissionsNotGranted 或 SessionConfigurePermissionsNotGranted。(I7c488、b/430651879)

1.0.0-alpha04 版本

2025 年 5 月 7 日

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

新功能

  • Session 現在會實作 androidx.lifecycle.LifecycleOwner，以便與現有的 Android 生命週期範例進行更多互通性。
  • Android XR 的資訊清單字串指定方式和相關說明請參閱這裡。
  • 新增 Spatial Visibility Callback 擴充方法，用於監控場景內容在使用者視野內或視野外的移動情形。
  • 新增 JxrPlatformAdapter 的虛設常式版本 (和所有相關類別)。
  • 工作階段會同時用於 SceneCore 和 Runtime，而非 SceneCore 中的工作階段。
  • 已新增 ActivityPose.hitTest，可針對虛擬內容啟用 hitTest。
  • 現在支援在編譯時指定多個 Runtime 實作項目。系統會根據目前裝置的功能集，在執行階段載入其中一個。
  • 新增 SpatialPointerComponent 元件類型，讓用戶指定指標的顯示圖示，或停用圖示。目前這個元件只能附加至 PanelEntity 個執行個體。

API 變更

  • 將 Config 實作設為公開。(I95860)
  • 新增 HandJointType 和 TrackingState。(I55880)
  • 使用 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本 (Idb6b5)
  • 「Hand.isActive (boolean)」已變更為「Hand.trackingState」。OpenXR 實作項目已相應修改。
  • android.permission.SCENE_UNDERSTANDING 的權限規定已變更為 android.permission.SCENE_UNDERSTANDING_COARSE。Session.configure
  • LifecycleManager.configure 已實作，現在會傳遞 Config 物件，其中包含每個可設定的執行階段功能的屬性。
  • 現在可以透過 Config 呼叫 Session.configure，設定可用的執行階段功能。
  • Session.create 現在支援傳遞 CoroutineContext，而非 CoroutineDispatcher。
  • Session.create 支援載入 Jetpack XR 和/或 SceneCore 的 ARCore。至少須提供一個 (可使用測試版)。
  • 如果傳遞無效的 UUID 給 Anchor.load 和 Anchor.unpersist，FakePerceptionManager 會擲回 AnchorInvalidUuidException。
  • CoreState 不再是資料類別。

修正錯誤

  • 修正執行階段 ProGuard 設定。

1.0.0-alpha03 版本

2025 年 2 月 26 日

發布 androidx.xr.runtime:runtime:1.0.0-alpha03、androidx.xr.runtime:runtime-openxr:1.0.0-alpha03 和 androidx.xr.runtime:runtime-testing:1.0.0-alpha03，但自上次 Alpha 版以來沒有重大異動。1.0.0-alpha03 版包含這些修訂項目。

1.0.0-alpha02 版

2025 年 2 月 12 日

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

破壞性變更和行為變更

  • 如果 OpenXR 執行階段函式傳回 Anchor，且遇到通知已達 OpenXR 資源限制的錯誤碼，現在會擲回 AnchorResourcesExhaustedException。
  • Session.create 和 Session.resume 現在必須具備 android.permission.HAND_TRACKING 權限。

新功能

  • 新增手部追蹤支援。

修正錯誤

  • 在模擬器上執行時，建立錨點的穩定性更高

1.0.0-alpha01 版

2024 年 12 月 12 日

發布 androidx.xr.runtime:runtime-* 1.0.0-alpha01。

初始版本的功能

Jetpack XR Runtime 的初始版本。這個程式庫包含 Jetpack XR 程式庫套件的基本功能。包括功能探索、生命週期管理、設定等。視執行平台而定，執行階段程式庫會提供不同變體 (例如 runtime-openxr 或 runtime-testing)。此外，這個程式庫還提供基本數學抽象概念，例如 Vector3 和 Matrix4，這些概念會用於整個 Jetpack XR API 介面。

  • Session：可精細控管 XR 系統，包括決定何時執行處理作業，以及整體設定。您也會在所有其他 API 中使用這個控制代碼，解鎖基礎系統功能。

  • Pose：任意座標系統中的位置，與位置和方向相關聯。您將使用這個類別，透過 Jetpack XR 和 Jetpack SceneCore 與 ARCore 通訊，傳達物件的位置。

已知問題

  • configure 目前為無運算元。日後發布的版本會新增設定，供您控管 Session 的行為。