使用 ARCore 為 Jetpack XR 建立錨點

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

錨點會說明現實世界中的位置和方向。 將物件附加至錨點，可讓物件在現實世界中呈現逼真的放置效果，並避免應用程式在每個影格都執行邏輯，進而節省電力。

存取工作階段

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

設定工作階段

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

val newConfig = Config.Builder(session.config)
    .setAnchorPersistence(AnchorPersistenceMode.LOCAL)
    .build()
when (val result = session.configure(newConfig)) {
    is SessionConfigureSuccess -> TODO(/* Success! */)
    else ->
        TODO(/* The session could not be configured. See SessionConfigureResult for possible causes. */)
}

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

錨點是使用 Pose 建立，可根據現有的 Anchorable 解讀，或固定在世界中。Anchorable 是可附加錨點的 Trackable。

建立相對於 Anchorable 的錨點

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

val anchor = plane.createAnchor(pose)

在世界中建立錨點

如要建立固定在世界中的錨點，請勿將錨點附加至 Anchorable。請只將這類錨點用於空間中浮動的點，因為工作階段對不可移動物件位置的估計值會隨時間改變：

val anchor = Anchor.create(session, pose)

將實體附加至錨點

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

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

瞭解 TrackingState

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

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

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

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

val uuid = anchor.persist()

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

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

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

Anchor.unpersist(session, uuid)

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

val uuids = Anchor.getPersistedAnchorUuids(session)