适用于 Jetpack XR 的 ARCore

借助感知功能将数字内容带入现实世界。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2025 年 7 月 30 日 - - - 1.0.0-alpha05

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.xr.arcore:arcore:1.0.0-alpha05"
}

Kotlin

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

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

反馈

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

创建新问题

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

版本 1.0

版本 1.0.0-alpha05

2025 年 7 月 30 日

发布了 androidx.xr.arcore:arcore:1.0.0-alpha05、androidx.xr.arcore:arcore-guava:1.0.0-alpha05 和 androidx.xr.arcore:arcore-rxjava3:1.0.0-alpha05。版本 1.0.0-alpha05 中包含这些提交内容。

新功能

  • 添加 getPrimaryHandSide，以便开发者可以获取左侧信息 (I270bd)
  • 添加了地理空间检查 VPS 可用性 API (I58573)
  • 为 checkVpsAvailability 添加了 ARCore API (Idbded)
  • 为供 Java 开发者使用，向 :xr:arcore:arcore-rxjava3 添加了 stateFlowable 扩展函数。（I083aa、b/427247794）

API 变更

  • 配置 *Mode 值已重命名，以反映其行为。（I6d247、b/414648065）
  • 主要 ARCore 制品 (xr:arcore:arcore) 将仅包含 Kotlin 样式的异步 API。Java 开发者可以依赖 xr:arcore:arcore-rxjava3 库来访问兼容的 API。（Ia525e、b/422794329）
  • 主要 ARCore 制品 (xr:scenecore:scenecore) 将仅包含 Kotlin 样式的异步 API。Java 开发者可以依赖 xr:arcore:arcore-guava 库来访问兼容的 API。（Iffcb4、b/422773524）
  • Anchor.persistAsync() 已添加到 AnchorGuava 中，供 Java 开发者使用。（I4af1c、b/425984631）
  • Earth.createAnchorOnSurfaceAsync(Session, Double, Double, Double, Quaternion, Surface) 已添加到 EarthGuava 中，供 Java 开发者使用。（I66357、b/425992992）
  • Java 开发者将使用 GltfModel.kt 中 GltfModel.createAsync 的扩展函数。GltfModel 中的异步函数将被删除。(I0af60)
  • 此库现在使用类型使用的 JSpecify nullness 注释。Kotlin 开发者应使用以下编译器实参来强制执行正确用法：-Xjspecify-annotations=strict（这是 Kotlin 编译器从 2.1.0 版开始的默认设置）（Ia8420、b/326456246）
  • 为供 Java 开发者使用，向 :xr:arcore:arcore-rxjava3 添加了 subscribeAsFlowable 扩展函数。（Id3e49、b/427277298）

版本 1.0.0-alpha04

2025 年 5 月 7 日

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

API 变更

  • 使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本。(Idb6b5)
  • TrackingState 和 HandJointType 已从 ARCore 移至运行时。
  • Hand.State.isActive (boolean) 已更改为 Hand.State.trackingState (androidx.xr.runtime.TrackingState)。
  • 如果 UUID 无效，Anchor.load 会返回 Anchor.AnchorLoadInvalidUuid。

版本 1.0.0-alpha03

2025 年 2 月 26 日

发布了 androidx.xr.arcore:arcore:1.0.0-alpha03，该版本与上个 Alpha 版相比没有明显变化。版本 1.0.0-alpha03 中包含这些提交内容。

版本 1.0.0-alpha02

2025 年 2 月 12 日

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

新功能

  • 添加了手部跟踪支持。使用 Hand.left 和 Hand.right 访问跟踪信息。
  • 生成锚点（Anchor.create、Anchor.load、Plane.createAnchor）的 API 现在全部返回 AnchorCreateResult 并正确实现 AnchorCreateResourcesExhausted。

bug 修复

  • Anchor.detach 不会再因与会话更新线程发生竞态条件而导致严重崩溃。
  • 在模拟器上运行时，Anchor.create 更稳定

版本 1.0.0-alpha01

2024 年 12 月 12 日

发布了 androidx.xr.arcore:arcore-* 1.0.0-alpha01。

初始版本的功能

ARCore for Jetpack XR 库的灵感源自现有的 ARCore 库，可提供将数字内容与现实世界融合的功能。该库包括运动跟踪、持久锚点、命中测试和平面识别（带语义标签，例如地面、墙壁和桌面）。如需详细了解如何将 ARCore 用于 Jetpack XR，请查看开发者指南。

  • Session：ARCore for Jetpack XR 在后台使用 Jetpack XR 运行时来支持其功能。您将使用会话与大多数 ARCore for Jetpack XR API 进行交互，因此请查看其文档。

  • Plane：使用平面来了解周围的世界。每个平面都有一个 Label，用于从语义上描述该平面。您可以使用 subscribe 接收有关最新检测到的飞机的通知，也可以使用 state 接收有关特定飞机发生变化的通知。

  • Anchor：虚拟对象与现实世界位置之间的关联。锚点可以附加到空间中的特定位置（使用 create）或 Trackable（使用 createAnchor）。

    • 锚点可在多个会话中重复使用。您可以使用 persist 存储它们，使用 getPersistedAnchorUuids 枚举它们，并使用 load 检索它们。请确保在不再使用这些密钥后将其unpersist。

    • 锚点可在 ARCore for Jetpack XR 和 Jetpack SceneCore 之间互操作。您可以使用锚点创建 AnchorEntity，或者，如果您已有 AnchorEntity，可以使用 getAnchor 检索其支持的锚点。

    • 使用 hitTest 提供自然的用户互动。命中测试使用 Ray 来确定它与哪些内容相交，并从该位置创建 Anchor。考虑从 InputEvent 执行 hitTest。

已知问题

  • 调用 unpersist 与从 getPersistedAnchorUuids 返回的结果中移除其 UUID 之间可能会有延迟。

  • create 不会验证系统是否有足够的资源来返回新的锚点。创建过多的锚点可能会导致崩溃。

  • 目前不支持持久保存之前已持久保存并取消持久保存的锚点。

  • 支持在模拟器中使用，但行为可能不如在实际设备上运行时稳定。特别是，对 create 的调用可能会因原生代码错误而失败，并立即终止 activity。

  • 在某些情况下，使用“Anchor was not persisted”消息调用 persist 时，可能会错误地抛出 RuntimeException。在这种情况下，该函数仍会成功执行，并且锚点会被持久化。我们建议将对 persist 的调用封装在 try 块中，以解决此问题。