使用 ARCore 為 Jetpack XR 建立錨點

錨點會描述實體世界中的固定位置和方向。將物件附加到錨點，有助於讓物件在真實世界中呈現逼真的效果。

建立 ARCore for Jetpack XR 工作階段

透過 ARCore for Jetpack XR 工作階段建立錨點。請參閱「瞭解工作階段的生命週期」一文，瞭解如何取得 Session。

設定工作階段

建立及載入錨點不需要設定工作階段。不過，錨點持久性預設為在 XR 工作階段中停用。如要儲存及載入錨點，請設定工作階段：

val newConfig = session.config.copy(
    anchorPersistence = Config.AnchorPersistenceMode.Enabled,
)
when (val result = session.configure(newConfig)) {
    is SessionConfigureConfigurationNotSupported ->
        TODO(/* Some combinations of configurations are not valid. Handle this failure case. */)
    is SessionConfigurePermissionsNotGranted ->
        TODO(/* The required permissions in result.permissions have not been granted. */)
    is SessionConfigureSuccess -> TODO(/* Success! */)
}
Anchors.kt

將內容固定在空間中固定位置

錨點是使用 Pose 建立，可根據現有的 Trackable 進行解讀，也可以不依據現有的 Trackable 進行解讀。

建立相對於可追蹤項目的錨點

錨點建立於 Trackable (例如 Plane) 時，錨點會在附加的 Trackable 移動時，追隨附加的 Trackable。

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

在不使用 Trackable 的情況下建立錨點

如要建立未連結至 Trackable 的錨點，請按照下列步驟操作：

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

將實體附加至錨點

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

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

瞭解 TrackingState

每個 Trackable 都有一個 TrackingState，應在使用前先檢查。Trackable 的 TrackableState 為 Tracking 時，系統會主動更新其 Pose。Paused 的 Trackable 日後可能會變成 Tracking，但 Stopped 則永遠不會變成 Tracking。

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

未儲存的錨點會在工作階段結束後消失。透過錨點持久化，應用程式會記住錨點在私人應用程式資料中的相對位置。這個錨點可在後續工作階段中擷取，並且會錨定在世界地圖上的同一個位置。

如要保留錨點，請使用 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()。這會從應用程式儲存空間中移除錨點，並讓指定的 UUID 無法擷取，以便呼叫 Anchor.load()。

Anchor.unpersist(session, uuid)
AnchorPersistence.kt

應用程式也可以要求已儲存的所有錨點清單，這些錨點仍會保留在應用程式儲存空間中：

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