使用 ARCore 為 Jetpack XR 建立錨點

適用的 XR 裝置
這份指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
XR 頭戴式裝置
有線 XR 眼鏡
瞭解 XR 裝置類型 →

錨點會說明現實世界中的固定位置和方向。將物件附加至錨點，可讓物件在現實世界中呈現逼真的放置效果。

存取工作階段

透過 Jetpack XR 專用的 ARCore Session 建立錨點。如果您使用 Jetpack Compose for XR 強化空間 UI，請透過 Jetpack Compose for XR 存取工作階段。如果您要處理 Jetpack SceneCore 程式庫中的空間實體，請從 Jetpack XR Runtime 存取工作階段。

設定工作階段

建立及載入錨點時，不需要設定工作階段。 不過，XR 工作階段預設不會啟用錨點持續性。如要從本機儲存空間保存及載入錨點，請設定工作階段並設定 AnchorPersistenceMode.LOCAL 模式：

val newConfig = session.config.copy(
    anchorPersistence = AnchorPersistenceMode.LOCAL,
)
when (val result = session.configure(newConfig)) {
    is SessionConfigureSuccess -> TODO(/* Success! */)
    else ->
        TODO(/* The session could not be configured. See SessionConfigureResult for possible causes. */)
}
Anchors.kt

將內容錨定至空間中的固定位置

錨點是使用 Pose 建立，可解讀為與現有 Anchorable 相關，也可以不相關。Anchorable 是可附加錨點的 Trackable。

建立相對於 Anchorable 的錨點

如果錨點是相對於 Anchorable 建立，例如 Plane，錨點就會在空間中移動時，跟著附加的 Anchorable 移動。

when (val result = anchorable.createAnchor(pose)) {
    is AnchorCreateSuccess -> { /* anchor stored in `result.anchor`. */ }
    else -> { /* handle failure */ }
}
Anchors.kt

建立沒有 Anchorable 的錨點

如要建立未附加至 Anchorable 的錨點：

when (val result = Anchor.create(session, pose)) {
    is AnchorCreateSuccess -> { /* anchor stored in `result.anchor`. */ }
    else -> { /* handle failure */ }
}
Anchors.kt

將實體附加至錨點

如要在這個位置算繪模型，請建立 GltfModel，並將其父項設為 AnchorEntity。

AnchorEntity.create(session, anchor).apply {
    parent = session.scene.activitySpace
    addChild(entity)
}
Anchors.kt

瞭解 TrackingState

每個 Trackable 都有 TrackingState，使用前應先檢查。 系統會主動更新具有 Tracking Trackable 的 Trackable。PoseTrackableStateTrackable 可能會在未來變成 Tracking，但 Stopped 永遠不會變成 Tracking。Paused

在整個工作階段中保留錨點

未保存的錨點會在工作階段終止後消失。應用程式會將錨點儲存在私人應用程式資料中，記住錨點的位置。這個錨點可在後續工作階段中擷取，並錨定在世界上的相同位置。

如要保存錨點，請使用 Anchor.persist()，如下所示：

val uuid = anchor.persist()
AnchorPersistence.kt

應用程式可以在日後的工作階段使用 UUID 擷取錨點：

when (val result = Anchor.load(session, uuid)) {
    is AnchorCreateSuccess -> {
        // Loading was successful. The anchor is stored in result.anchor.
    }
    else -> {
        // handle failure
    }
}
AnchorPersistence.kt

不再需要錨點時，請呼叫 unpersist()。這會從應用程式的儲存空間移除錨點，並讓 Anchor.load() 的呼叫無法擷取指定的 UUID。

Anchor.unpersist(session, uuid)
AnchorPersistence.kt

應用程式也可以要求列出所有已保存且仍存在應用程式儲存空間中的錨點：

val uuids = Anchor.getPersistedAnchorUuids(session)
AnchorPersistence.kt