public final class AnchorEntity implements ScenePose, Entity

An AnchorEntity tracks a androidx.xr.runtime.math.Pose relative to some position or surface in the "Real World." Children of this Entity will remain positioned relative to that location in the real world, for the purposes of creating Augmented Reality experiences.

Note that Anchors are only relative to the "real world", and not virtual environments. Also, setting the Entity.parent property on an AnchorEntity has no effect, as the parenting of an Anchor is controlled by the system.

Summary

Nested types
public static class AnchorEntity.State

Public methods
static final @NonNull AnchorEntity
create(@NonNull Session session, @NonNull Anchor anchor)

Public factory for an AnchorEntity which uses an Anchor from ARCore for Jetpack XR.
static final @NonNull AnchorEntity
create(
    @NonNull Session session,
    @NonNull FloatSize2d minimumPlaneExtents,
    int planeOrientation,
    int planeSemanticType,
    @NonNull Duration timeout
)

Factory for an AnchorEntity which searches for a real-world surface on which to anchor, from the set of tracked planes available to the perception system.
final @NonNull Anchor

Loads the ARCore for Jetpack XR Anchor using a Jetpack XR Runtime session.
final int

The current tracking state for this AnchorEntity.
final void

Registers a listener to be called when the Anchor moves relative to its underlying space.
final void

Registers a listener to be called when the Anchor moves relative to its underlying space.
final void

Registers a listener to be invoked on the main thread when the AnchorEntity's state changes, or unregisters the current listener if set to null.
final void
setOnStateChangedListener(
    @NonNull Executor executor,
    Consumer<@NonNull Integer> listener
)

Registers a listener to be invoked on the given Executor when the AnchorEntity's state changes, or unregisters the current listener if set to null.

Inherited methods
From androidx.xr.scenecore.Entity
@FloatRange(from = 0.0, to = 1.0) float

Returns the alpha transparency set for this Entity.
@NonNull Pose

Returns the Pose for this Entity, relative to its parent.
@FloatRange(from = 0.0) float

Returns the local scale of this Entity, not inclusive of the parent's scale.
void
setAlpha(@FloatRange(from = 0.0, to = 1.0) float alpha)

Sets the alpha transparency of the Entity and its children.
void

Sets the Pose for this Entity, relative to its parent.
void
setScale(@FloatRange(from = 0.0) float scale)

Sets the scale of this Entity relative to its parent.
From androidx.xr.scenecore.ScenePose
abstract @NonNull Pose

The current Pose relative to the activity space root.
abstract @NonNull HitTestResult
hitTest(@NonNull Vector3 origin, @NonNull Vector3 direction)

Creates a hit test from the specified origin in the specified direction into the Scene.
abstract @NonNull HitTestResult
hitTest(
    @NonNull Vector3 origin,
    @NonNull Vector3 direction,
    int hitTestFilter
)

Creates a hit test from the specified origin in the specified direction into the scene.
abstract @NonNull Pose
transformPoseTo(@NonNull Pose pose, @NonNull ScenePose destination)

Returns a Pose relative to this ScenePose, transformed into a Pose relative to the destination.

Public methods

create

Added in 1.0.0-alpha05
public static final @NonNull AnchorEntity create(@NonNull Session session, @NonNull Anchor anchor)

Public factory for an AnchorEntity which uses an Anchor from ARCore for Jetpack XR.

Parameters
@NonNull Session session

Session in which to create the AnchorEntity.
@NonNull Anchor anchor

The Anchor to use for this AnchorEntity.

create

Added in 1.0.0-alpha05
public static final @NonNull AnchorEntity create(
    @NonNull Session session,
    @NonNull FloatSize2d minimumPlaneExtents,
    int planeOrientation,
    int planeSemanticType,
    @NonNull Duration timeout
)

Factory for an AnchorEntity which searches for a real-world surface on which to anchor, from the set of tracked planes available to the perception system.

Parameters
@NonNull Session session

Session in which to create the AnchorEntity.
@NonNull FloatSize2d minimumPlaneExtents

The minimum extents (in meters) of the plane to which this AnchorEntity should attach.
int planeOrientation

PlaneOrientation of the plane to which this AnchorEntity should attach.
int planeSemanticType

PlaneSemanticType of the plane to which this AnchorEntity should attach.
@NonNull Duration timeout

The amount of time as a Duration to search for the a suitable plane to attach to. If a plane is not found within the timeout, the returned AnchorEntity state will be set to AnchorEntity.State.TIMEDOUT. It may take longer than the timeout period before the anchor state is updated. If the timeout duration is zero it will search for the anchor indefinitely.
Throws
kotlin.IllegalStateException

if session.config.planeTracking is set to PlaneTrackingMode.DISABLED.

getAnchor

Added in 1.0.0-alpha05
public final @NonNull Anchor getAnchor(@NonNull Session session)

Loads the ARCore for Jetpack XR Anchor using a Jetpack XR Runtime session.

Parameters
@NonNull Session session

the Jetpack XR Runtime session from which to load the Anchor.
Returns
@NonNull Anchor

the ARCore for Jetpack XR Anchor corresponding to the native pointer.

getState

Added in 1.0.0-alpha05
public final int getState()

The current tracking state for this AnchorEntity.

setOnSpaceUpdatedListener

Added in 1.0.0-alpha05
public final void setOnSpaceUpdatedListener(Runnable listener)

Registers a listener to be called when the Anchor moves relative to its underlying space.

The callback is triggered on the default SceneCore Executor by any anchor movements such as those made by the underlying perception stack to maintain the anchor's position relative to the real world. Any cached data relative to the activity space or any other "space" should be updated when this callback is triggered.

Parameters
Runnable listener

The listener to register if non-null, else stops listening if null.

setOnSpaceUpdatedListener

Added in 1.0.0-alpha05
public final void setOnSpaceUpdatedListener(@NonNull Executor executor, Runnable listener)

Registers a listener to be called when the Anchor moves relative to its underlying space.

The callback is triggered on the supplied Executor by any anchor movements such as those made by the underlying perception stack to maintain the anchor's position relative to the real world. Any cached data relative to the activity space or any other "space" should be updated when this callback is triggered.

Parameters
@NonNull Executor executor

The executor to run the listener on.
Runnable listener

The listener to register if non-null, else stops listening if null.

setOnStateChangedListener

Added in 1.0.0-alpha05
public final void setOnStateChangedListener(Consumer<@NonNull Integer> listener)

Registers a listener to be invoked on the main thread when the AnchorEntity's state changes, or unregisters the current listener if set to null.

The listener will fire with the current AnchorEntity.State value immediately upon registration.

setOnStateChangedListener

Added in 1.0.0-alpha05
public final void setOnStateChangedListener(
    @NonNull Executor executor,
    Consumer<@NonNull Integer> listener
)

Registers a listener to be invoked on the given Executor when the AnchorEntity's state changes, or unregisters the current listener if set to null.

The listener will fire with the current State value immediately upon registration.

Parameters
@NonNull Executor executor

: The executor on which the specified listener will fire.
Consumer<@NonNull Integer> listener

: The listener to fire upon invoking this method, and all subsequent state changes.