Jetpack XR 版 ARCore

通过感知能力将数字内容带入现实世界。
最新更新 稳定版 发布候选版本 Beta 版 Alpha 版
2025 年 5 月 7 日 - - - 1.0.0-alpha04

声明依赖项

要添加对 Jetpack XR 版 ARCore 的依赖项，您必须将 Google Maven 代码库添加到您的项目中。如需了解更多信息，请阅读 Google 的 Maven 代码库。

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

Groovy

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

Kotlin

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

如需了解有关依赖项的更多信息，请参阅添加构建依赖项。

反馈

您的反馈有助于改进 Jetpack。如果您发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请查看此库中的现有问题。您可以通过点击星标按钮来为现有问题投票。

创建新问题

如需了解更多信息，请参阅问题跟踪器文档。

版本 1.0

版本 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 移至 Runtime。
  • 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 访问跟踪信息。
  • 生成锚点的 API（Anchor.create、Anchor.load、Plane.createAnchor）现在都返回 AnchorCreateResult 并正确实现 AnchorCreateResourcesExhausted。

Bug 修复

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

版本 1.0.0-alpha01

2024 年 12 月 12 日

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

初始发布的功能

Jetpack XR 版 ARCore 库受现有 ARCore 库启发，提供了将数字内容与现实世界融合的功能。此库包括运动跟踪、持久锚点、点击测试和带有语义标签（例如，地板、墙壁和桌面）的平面识别。查看开发者指南，了解有关使用 Jetpack XR 版 ARCore 的更多信息。

  • Session：Jetpack XR 版 ARCore 在底层使用 Jetpack XR Runtime 来为其功能提供支持。您将使用 Session 与大多数 Jetpack XR 版 ARCore API 交互，因此请查看其文档。

  • Plane：使用平面来了解您周围的世界。每个平面都有一个 Label，用于语义描述。您可以使用 subscribe 来接收最新检测到的平面的通知，或者使用 state 来接收特定平面更改的通知。

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

    • 锚点可以在不同会话中重复使用。您可以使用 persist 来存储它们，使用 getPersistedAnchorUuids 来枚举它们，并使用 load 来检索它们。确保在不再使用时unpersist 它们。

    • 锚点在 Jetpack XR 版 ARCore 和 Jetpack SceneCore 之间是可互操作的。您可以使用锚点创建 AnchorEntity，或者如果您已有现有的 AnchorEntity，则可以使用 getAnchor 来检索其后备锚点。

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

已知问题

  • 在调用 unpersist 后，到其 UUID 从 getPersistedAnchorUuids 返回的结果中移除，可能会有延迟。

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

  • 目前不支持持久化之前已持久化和已解除持久化的锚点。

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

  • 在某些情况下，当调用 persist 时，可能会错误地抛出 RuntimeException，并显示消息“Anchor was not persisted”。在这些情况下，函数仍然会成功，并且锚点将保持持久化。我们建议将对 persist 的调用包装在 try 块中作为一种解决方法。