An Anchor describes a fixed location and orientation in the real world. Attaching an object to an anchor helps objects appear realistically placed in the real world.
Create an ARCore for Jetpack XR session
Create anchors through an ARCore for Jetpack XR session. See
Understand a Session's lifecycle
to obtain a Session
.
Configure the Session
Creating and loading anchors does not require the session to be configured. However, anchor persistence is not enabled by default on XR sessions. To persist and load anchors, configure the session:
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! */) }
Anchor content to a fixed location in space
An anchor is created using a Pose
, which can be
interpreted relative to an existing Trackable
or not.
Create an anchor relative to a Trackable
When an anchor is created relative to a Trackable
, such as a Plane
, which
makes the anchor follow the attached Trackable
when it moves through space.
when (val result = trackable.createAnchor(pose)) { is AnchorCreateSuccess -> { /* anchor stored in `result.anchor`. */ } else -> { /* handle failure */ } }
Create an anchor without a Trackable
To create an anchor that isn't attached to a Trackable
:
when (val result = Anchor.create(session, pose)) { is AnchorCreateSuccess -> { /* anchor stored in `result.anchor`. */ } else -> { /* handle failure */ } }
Attach an entity to an anchor
To render a model at this location, [create a GltfModel
][5] and set its parent
to an AnchorEntity
.
AnchorEntity.create(session, anchor).apply { setParent(session.activitySpace) addChild(entity) }
Understand TrackingState
Each Trackable
has a TrackingState
that should be checked before being used.
A Trackable
that has a TrackableState
of Tracking
has its Pose
actively
updated by the system. A Trackable
that is Paused
may become Tracking
in
the future, whereas one that is Stopped
will never become Tracking
.
Persist an Anchor throughout sessions
An anchor that is not persisted disappears after a session is destroyed. By persisting an anchor, your app remembers that anchor's position in its private app data. This anchor can be retrieved in a subsequent session and is anchored in the same location in the world.
To persist an anchor, use anchor.persist()
as shown
here:
val uuid = anchor.persist()
Your app can retrieve the anchor by using the UUID
in a
future session:
when (val result = Anchor.load(session, uuid)) { is AnchorCreateSuccess -> { // Loading was successful. The anchor is stored in result.anchor. } else -> { // handle failure } }
When you don't need an anchor anymore, call
unpersist()
. This removes the anchor from your app's
storage and makes the given UUID unretrievable for calls to
Anchor.load()
.
Anchor.unpersist(session, uuid)
Your app can also request a list of all anchors that have been persisted that are still present in your app's storage:
val uuids = Anchor.getPersistedAnchorUuids(session)