使用 ARCore 為 Jetpack XR 建立錨點

適用 XR 裝置

這份指南可協助您為這類 XR 裝置打造體驗。

瞭解 XR 裝置類型 →

XR 頭戴式裝置

有線 XR 眼鏡

瞭解 XR 裝置類型 →

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

存取工作階段

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

設定工作階段

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

val newConfig = session.config.copy(
    anchorPersistence = Config.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 建立，可解讀為相對於現有 Trackable 或不相對於現有 Trackable。

建立相對於可追蹤物件的錨點

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

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

建立沒有可追蹤物件的錨點

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

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 Pose。TrackableStateTrackable可能在未來成為 Tracking，而 Stopped 則永遠不會成為 Tracking。TrackablePausedTrackingStopped

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

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

如要保存錨點，請使用 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