XR 运行时

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

声明依赖项

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

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

Groovy

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

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

Kotlin

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

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

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

反馈

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

创建新问题

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

版本 1.0

版本 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.runtime.math.IntSize2d。将 androidx.xr.scenecore.Dimensions 重命名为 androidx.xr.runtime.math.FloatSize3d 并移至 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）
  • Session.resume()、Session.pause() 和 Session.destroy() 已从 API Surface 中移除。会话不再是 LifecycleOwner。会话的生命周期现在将附加到 Session.create() 中传入的 Activity 的生命周期。(I28a03)
  • 此库现在使用类型使用的 JSpecify nullness 注释。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 表面。

  • Session：可让您对 XR 系统进行精细控制，包括决定何时执行处理以及总体配置。您还将使用此句柄通过所有其他 API 来解锁底层系统功能。

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

已知问题

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