XR 运行时

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

声明依赖项

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

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

Groovy

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

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

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

Kotlin

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

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

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

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

反馈

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

创建新问题

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

1.0 版

1.0.0-alpha12

2026 年 3 月 25 日

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

API 变更

  • 将 Config.augmentedObjectCategories 从列表更改为集合 (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、会话和 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 添加了一个额外的重载，该重载可以为会话提供要附加到的 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)
  • 已从 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。必须至少提供一个（测试版本可用）。
  • 当向 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 surface 中使用。

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

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

已知问题

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