XR 运行时

使用我们的原生运行时启动自定义 AR 或 3D 会话。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2026 年 9 月 9 日 - 1.0.0-rc01 - 1.1.0-alpha01

声明依赖项

如需添加 XR 运行时的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    implementation "androidx.xr.runtime:runtime:1.1.0-alpha01"

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

Kotlin

dependencies {
    implementation("androidx.xr.runtime:runtime:1.1.0-alpha01")

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

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.1

版本 1.1.0-alpha01

2026 年 9 月 9 日

发布了 androidx.xr.runtime:runtime-*:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

API 变更

  • 向 SpatialApiVersions 添加了 SPATIAL_API_V4 (I71e7a)

版本 1.0

版本 1.0.0-rc01

2026 年 9 月 9 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

行为变更

版本 1.0.0-beta02

2026 年 8 月 12 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-beta02。版本 1.0.0-beta02 中包含这些提交内容。

bug 修复

  • 改进了对模拟环境中 OpenXR 支持的检测。(Ifec51)
  • 在更多类中实现了 toString() 以进行调试。(I67d83)
  • 修复了 XrDeviceTestRule 在应用设置后创建 XrDevice 时无法正常运行的问题。(Ica32c)

版本 1.0.0-beta01

2026 年 7 月 15 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

API 变更

  • 向运行时测试添加了 SessionTestRule。此 API（I672bc、b/516876144）
  • 将 Session.create 转换为挂起函数。(I5d27f)
  • 为 XrDeviceTestRule 添加了对生命周期的支持（I2319c、b/512140272）
  • 移除了未使用的 ExperimentalXrDeviceLifecycleApi 实验性选择启用注解。(I46d95)
  • 为多种运行时类型添加了 toString() 的专用替换项。这些类型旨在为开发者提供额外的调试信息，不适合在生产环境或已发布的应用中使用。

bug 修复

  • 修复了姿势。fromLookAt 前向方向对齐，修正了 Matrix3 中的缩放提取，并防止了归一化、轴角转换和 angleBetween 计算中的数值 NaNs。（I7a3b5、b/367780918）

版本 1.0.0-alpha15

2026 年 6 月 17 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha15。版本 1.0.0-alpha15 中包含这些提交内容。

API 变更

  • 为 isProjectedServiceAvailable() 添加了测试 API (I44ba1)
  • 在新的 @ExperimentalInertialTrackingApi 注释下将 DeviceTrackingMode.INERTIAL 公开为公共实验性 API。(Ic3df3)
  • 添加了 Config.Builder。应用可以通过对构建器对象调用 setter 函数来创建自定义配置，然后调用 Builder.build。(I13142)
  • 移除了 androidx.xr.runtime.FieldOfView。应用应改用 androidx.xr.runtime.math.FieldOfView。(I621ef)
  • 现在必须在 @WorkerThread 上运行 Session.create。(I2169e)
  • 向 XrDevice 添加了 isProjectedServiceAvailable() (I507e9)
  • 将 DeviceTrackingMode.SPATIAL_LAST_KNOWN 重命名为 DeviceTrackingMode.SPATIAL，并将 DeviceTrackingMode.INERTIAL_LAST_KNOWN 重命名为 DeviceTrackingMode.INERTIAL (I96f8b)
  • Vector3.angleBetween 和 Vector4.angleBetween 现在返回的是度数，而不是弧度。(Ica8bc)
  • 添加了 QrCode API (Ia0bbe)

版本 1.0.0-alpha14

2026 年 5 月 19 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha14。版本 1.0.0-alpha14 中包含这些提交内容。

API 变更

  • 弃用 GeospatialMode.VPS_AND_GPS，改用 GeospatialMode.SPATIAL，并推出一种新的低功耗追踪模式 GeospatialMode.INERTIAL，该模式仅使用 IMU 和 GPS。(I1e6cd)
  • 移除了 androidx.xr.runtime.FieldOfView 上的弃用标记。将 androidx.xr.runtime.math.FieldOfView 设置为 androidx.xr.runtime.FieldOfView 的类型别名，为在下一版本中移除后者做好准备。如果客户正在使用 androidx.xr.runtime 版本，则必须迁移到 androidx.xr.runtime.math 版本。(I6ce15)
  • 添加了 PreviewProjectedApi 注解 (Ic49f6)
  • 移除了 AugmentedObjectCategory.allSupported (I08656)
  • 在 XrDevice 中添加了 API，用于确定设备对手部跟踪、眼部跟踪、深度估计、地理空间和渲染的支持情况。(I00696)
  • Session.getNativeData 已替换为 XrDevice.getNativeInstanceData 和 Session.getNativeSessionData。(Ieb077)
  • 使用 @PreviewSpatialApi 对 DeviceTrackingMode.INERTIAL_LAST_KNOWN 进行了注解。(I99868)
  • 添加了 XrDeviceTestRule，以便在单元测试中使用。(I87584)
  • 添加 CATEGORY_XR_PROJECTED_LAUNCHER，此常量用于清单文件中，以指示系统应将相应 activity 发现为启动器。(Ia3069)

外部贡献

  • 向 Config API 添加了 AugmentedImageMode (I0cf09)

版本 1.0.0-alpha13

2026 年 5 月 6 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha13。版本 1.0.0-alpha13 中包含这些提交内容。

API 变更

  • TrackingState 和 VpsAvailabilityResult 已移至 androidx.xr.arcore package，androidx.xr.runtime 中的类型现已弃用。（Ic7930、b/480462213）
  • Session.getNativeData() 现在已在 xr:runtime:runtime 模块中定义，并为 OpenXR 支持的运行时提供 [nativeFunctionTablePointer]。(Ifa862)
  • 将 NativeData API 移至 xr:runtime:runtime 库。（I87954、b/494251500）
  • Session.create 和 Session.configure 现在是非详尽的，需要在 when 语句中添加 else 子句。（I9885e、b/495805998、b/495805998）
  • 已弃用 androidx.xr.runtime.FieldOfView。请改用 androidx.xr.runtime.math.FieldOfView。（Ia01a0、b/480233045）
  • Matrix4.pose 已重命名为 Matrix4.toPose()。姿势属性现已弃用。（I329b4、b/493383490）
  • 添加了 XrServiceAvailability API（If379e、b/493558010）
  • 添加了 ExperimentalXrServiceAvailabilityApi 注释（Icab49、b/491069725）
  • 移除了 @PreviewSpatialApi 的后缀（If5242、b/491939311）
  • 将 DeviceTrackingMode.LAST_KNOWN 重命名为 SPATIAL_LAST_KNOWN（具有已弃用的回退），添加了用于 3DoF 跟踪的 INERTIAL_LAST_KNOWN，并将 TRACKING_DEGRADED 添加到了 TrackingState。（Ie661c、b/445466590）
  • 添加了 XrLog API。将 XrLog.isEnabled 设置为 true 可在 JetpackXR 中启用日志记录，并使用 [XrLog.Level] 设置日志级别。（I76a1f、b/463460895、b/487378441）
  • 添加 DISPLAY_CATEGORY_XR_PROJECTED，此常量用于清单文件中，以指示 activity 适用于 XR 投影显示屏 (I26d8b)

版本 1.0.0-alpha12

2026 年 3 月 25 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha12。版本 1.0.0-alpha12 中包含这些提交内容。

API 变更

  • 将 Config.augmentedObjectCategories 从 List 更改为 Set（I25a64、b/487376359）
  • 从 Session.create 中移除了 unscaledGravityAlignedActivitySpace 标志。ActivitySpace 现在始终处于未缩放状态，并与重力对齐。（If6f11、b/458173423）
  • 添加了 Session.create 重载，以允许传递 Android Context 进行资源范围界定。（I7d3fe、b/415805990、b/477386334）
  • 向 FloatSize2d.to3d、Matrix3.copy 和 Matrix4.copy 添加了 JvmOverloads（I69586、b/481371562）
  • 添加了在配置中为 AugmentedObject 跟踪设置类别的功能（I1f6e4、b/480220930）
  • 添加了 xr:runtime:runtime-interfaces 模块。（I52ac6、b/461561664）

版本 1.0.0-alpha11

2026 年 2 月 25 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha11。版本 1.0.0-alpha11 中包含这些提交内容。

API 变更

  • 将 ConfigMode 接口限制为仅供内部使用 (Ibfb87)
  • 将 androidx.xr.runtime.Config.GeospatialMode 移到了软件包级别 (Ibe682)
  • 将 androidx.xr.runtime.Config.FaceTrackingMode 移到了软件包级 (Iac501)
  • 已将 androidx.xr.runtime.Config.AnchorPersistenceMode 移至软件包级 (I0360f)
  • 将 androidx.xr.runtime.Config.DepthEstimationMode 移至软件包级 (I7e3e9)
  • 将 androidx.xr.runtime.Config.DeviceTrackingMode 移到了软件包级 (I3aacd)
  • 将 androidx.xr.runtime.Config.HandTrackingMode 移到了软件包级别 (I658f3)
  • 将 androidx.xr.runtime.Config.PlaneTrackingMode 移到了软件包级 (Ia251b)
  • 将 androidx.xr.runtime.XrDevice.DisplayBlendMode 移至软件包级 (I6f333)
  • 添加了一个工厂方法，用于使用 Context、Session 和 CoroutineContext 创建 XrDevice。(I139c5)
  • 添加了 SpatialApiVersionHelper，以帮助查询平台上可用的 Android XR 运行时版本。(I7c53c)
  • 添加了 xr:runtime:runtime-openxr 模块 (Ib42ea)

版本 1.0.0-alpha10

2026 年 1 月 28 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha10。版本 1.0.0-alpha10 中包含这些提交内容。

API 变更

  • ConfigMode.HeadTrackingMode 已替换为 ConfigMode.DeviceTrackingMode。（le273e、b/467150206）
  • 移除了四元数的 toNormalized、times(float)、div(float) 方法。鉴于所有四元数在构建时都已归一化，并且该类是不可变的，因此这些方法是多余的。（l558fc、b/460210457）

bug 修复

  • 为 Session.create 添加了文档，说明如何避免在应用的主线程上创建会话。（le5554、b/463687170）
  • 阻止应用创建具有 NaN 值的 BoundingBox。（l58c14、b/464025895）

版本 1.0.0-alpha09

2025 年 12 月 3 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha09。版本 1.0.0-alpha09 中包含这些提交内容。

版本 1.0.0-alpha08

2025 年 11 月 19 日

发布了 androidx.xr.runtime:runtime-*:1.0.0-alpha08。版本 1.0.0-alpha08 中包含这些提交内容。

新功能

  • 添加了 XrDevice，用于提供有关设备功能的信息。(Ic9d1f)
  • 添加了新的 ConfigMode.isSupported API，用于查询会话功能。(Iff7af)
  • 添加了 XrDisplay.BlendMode API。(I484e4)

API 变更

  • 已将 [XrDevice.getPreferredBlendMode] 重命名为 [XrDevice.getPreferredDisplayBlendMode]。(I7e48f)

版本 1.0.0-alpha07

October 22, 2025

发布了 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]，以返回缩放比例为 1 的矩阵。（I6381d、b/434928658）
  • 由于 Coroutines.kt 已替换为 SuspendtoFutureAdapter，因此 :xr:runtime:runtime-guava 将被移除。（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）
  • 将配置实现设为公开。（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 添加了额外的重载，可为要附加到的会话提供 LifecycleOwner。请注意，仍需为资源所有权提供 Activity，并且 LifecycleOwner 必须限定在 Activity 范围内。(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）
  • 已从 API Surface 中移除 Session.resume()、Session.pause() 和 Session.destroy()。会话不再是 LifecycleOwner。会话的生命周期现在将附加到 Session.create() 中传入的 activity 的生命周期。(I28a03)
  • 此库现在使用 JSpecify nullness 注解，这些注解属于 type-use 类型。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，并将数据流移至 :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 中包含这些提交内容。

新功能

  • 会话现在实现了 androidx.lifecycle.LifecycleOwner，以便与现有的 Android 生命周期范式实现更好的互操作性。
  • Android XR 的清单字符串在此处指定和记录。
  • 添加了空间可见性回调扩展方法，用于监控场景内容何时移入或移出用户的视野。
  • 添加了 JxrPlatformAdapter（及其所有相关类）的桩版本。
  • 会话将用于 SceneCore 和运行时，而不是 SceneCore 中的会话。
  • 添加了 ActivityPose.hitTest，可针对虚拟内容进行 hitTest。
  • 现在支持在编译时间指定多个运行时实现。在执行时，系统会根据当前设备的功能集加载其中一个。
  • 添加了新的组件类型 SpatialPointerComponent，允许客户端指定为指针渲染的图标，或停用该图标。此组件目前只能附加到 PanelEntity 个实例。

API 变更

  • 将配置实现设为公开。(I95860)
  • 添加了 HandJointType 和 TrackingState。(I55880)
  • 使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本才能使用 (Idb6b5)
  • Hand.isActive (boolean) 已更改为 Hand.trackingState。OpenXR 实现已相应修改。
  • Session.configure 中 android.permission.SCENE_UNDERSTANDING 权限的要求已更改为 android.permission.SCENE_UNDERSTANDING_COARSE。
  • LifecycleManager.configure 已实现，现在传入一个 Config 对象，其中包含每个可配置的运行时功能的属性。
  • 现在可以使用 Config 调用 Session.configure，以配置可用的运行时功能。
  • Session.create 现在支持传递 CoroutineContext 而不是 CoroutineDispatcher。
  • Session.create 支持为 Jetpack XR 和/或 SceneCore 加载 ARCore。必须至少提供一个（有测试版本）。
  • 如果将无效 UUID 传递给 Anchor.load 和 Anchor.unpersist，FakePerceptionManager 会抛出 AnchorInvalidUuidException。
  • CoreState 不再是数据类。

bug 修复

  • 修复了运行时 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 权限。

新功能

  • 添加了手部追踪支持。

bug 修复

  • 在模拟器上运行时，创建锚点的稳定性更高

版本 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：任意坐标系中具有关联位置和方向的位置。您将使用此类与 ARCore 进行通信，以确定 Jetpack XR 和 Jetpack SceneCore 中对象的位置。

已知问题

  • configure 目前是一个空操作。未来的版本将添加新设置，您可以使用这些设置来控制 Session 的行为。