XR 运行时

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

声明依赖项

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

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

Groovy

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

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

Kotlin

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

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

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

反馈

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

创建新问题

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

1.0 版

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()。pose 属性现已废弃。(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，并向 TrackingState 添加了 TRACKING_DEGRADED。（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）
  • 移除了 Quaternion 的 toNormalized、times(float)、div(float) 方法。鉴于所有 Quaternion 都在构造时进行了归一化，并且该类是不可变的，因此这些方法是多余的。（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

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）
  • 更改了 Vector2、Vector3、Vector4 的 componentWiseMultiplication 的 times 运算符以进行缩放，并移除了运算符符号，以与其他数学库保持一致。此外，还移除了 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 添加了一个额外的重载，该重载可以为 Session 提供要附加到的 LifecycleOwner。请注意，仍需要为资源所有权提供 Activity，并且 LifecycleOwner 必须限定在 Activity 内。（I1690b）
  • 将 FakeRuntimeAnchor.anchorsCreated 重命名为 anchorsCreatedCount（I96df9、b/424441218）
  • Config *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 表面移除。Session 不再是 LifecycleOwner。Session 的生命周期现在将附加到 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 中包含 这些提交内容。

新功能

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

API 变更

  • 将配置实现设为公开。(I95860)
  • 添加了 HandJointType 和 TrackingState。(I55880)
  • 使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本（Idb6b5）
  • Hand.isActive (boolean) 已更改为 Hand.trackingState。相应地修改了 OpenXR 实现。
  • android.permission.SCENE_UNDERSTANDING 权限要求在 Session.configure 中已更改为 android.permission.SCENE_UNDERSTANDING_COARSE。
  • 实现了 LifecycleManager.configure，现在传入了一个 Config 对象，该对象包含每个可配置的运行时功能的属性。
  • 现在可以使用 Config 调用 Session.configure，以便配置可用的运行时功能。
  • Session.create 现在支持传递 CoroutineContext，而不是 CoroutineDispatcher。
  • Session.create 支持为 Jetpack XR 和/或 SceneCore 加载 ARCore。必须至少提供一个（测试版本可用）。
  • 当向 Anchor.load 和 Anchor.unpersist 传递无效 UUID 时，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 运行时函数遇到通知 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 运行时的初始版本。此库包含 Jetpack XR 库套件的基本功能。这包括功能发现、生命周期管理、配置等。运行时库根据执行平台提供不同的变体（例如 runtime-openxr 或 runtime-testing）。此外，此库还提供基本数学抽象（例如 Vector3 和 Matrix4），这些抽象在整个 Jetpack XR API 表面中使用。

  • Session：为您提供对 XR 系统的精细控制，包括决定何时执行和不执行处理以及总体配置。它也是您将在所有其他 API 中使用的句柄，用于解锁底层系统功能。

  • Pose：任意坐标系中的位置，具有与其关联的位置和方向。您将使用此类与 ARCore for Jetpack XR 和 Jetpack SceneCore 通信对象的位置。

已知问题

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