public final class AnchorEntity extends Entity

java.lang.Object
   ↳ androidx.xr.scenecore.BaseScenePose
     ↳ androidx.xr.scenecore.Entity
       ↳ androidx.xr.scenecore.AnchorEntity

An AnchorEntity tracks a 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.

AnchorEntity users must maintain a strong reference while the instance is in use. If there's no strong references to anchor instance in client code, anchor instance may become phantom reachable, and it will be garbage collected.

Summary

Nested types
public final class AnchorEntity.State

Public methods
final void

Adds a listener to be called when the Anchor's origin moves relative to its underlying space.
final void
addOriginChangedListener(
    @NonNull Executor executor,
    @NonNull Runnable listener
)

Adds a listener to be called when the Anchor's origin moves relative to its underlying space.
final void

Adds a listener to be invoked on the main thread when the AnchorEntity's state changes.
final void

Adds a listener to be invoked on the given Executor when the AnchorEntity's state changes.
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,
    @NonNull Set<@NonNull PlaneOrientation> planeOrientations,
    @NonNull Set<@NonNull PlaneSemanticType> planeSemanticTypes,
    @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 Anchor

Returns the ARCore for Jetpack XR Anchor associated with this AnchorEntity.
@NonNull Pose
getPose(@NonNull Space relativeTo)

Returns the pose of the AnchorEntity relative to the specified coordinate space.
float
getScale(@NonNull Space relativeTo)

Returns the scale of the AnchorEntity relative to the specified coordinate space.
final @NonNull AnchorEntity.State

The current tracking state for this AnchorEntity.
final void

Removes the listener to be called when the Anchor's origin moves relative to its underlying space.
final void

Removes the given state changed listener.

Inherited methods
From androidx.xr.scenecore.BaseScenePose
@NonNull Pose

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

Perform a hit test from the specified origin in the specified direction into the Scene.
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.
@NonNull Vector3
transformDirectionTo(
    @NonNull Vector3 direction,
    @NonNull ScenePose destination
)

Transforms a direction from this ScenePose's local space to the destination ScenePose's local space.
@NonNull Pose
transformPoseTo(@NonNull Pose pose, @NonNull ScenePose destination)

Returns a Pose relative to this ScenePose, transformed into a Pose relative to the destination.
@NonNull Vector3
transformPositionTo(
    @NonNull Vector3 position,
    @NonNull ScenePose destination
)

Transforms a position from this ScenePose's local space to the destination ScenePose's local space.
@NonNull Vector3

Transforms a vector from this ScenePose's local space to the destination ScenePose's local space.
From androidx.xr.scenecore.Entity
final void

Sets an Entity to be a child of this Entity in the scene graph.
final boolean

Adds a Component to this Entity.
final @FloatRange(from = 0.0, to = 1.0) float
getAlpha(@NonNull Space relativeTo)

Returns the alpha transparency set for this Entity, relative to given Space.
final @NonNull List<@NonNull Entity>

Provides the list of all children of this entity.
final @NonNull List<@NonNull Component>

Retrieves all components attached to this Entity.
final @NonNull List<@NonNull T>

Retrieves all Components of the given type T and its subtypes attached to this Entity.
final @NonNull CharSequence

Alternate text for this Entity to be consumed by Accessibility systems.
final Entity

The parent of this Entity, from which this Entity will inherit most of its properties.
final boolean
isEnabled(boolean includeParents)

Returns the enabled status of this Entity.
final void

Remove all components from this Entity.
final void

Removes the given Component from this Entity.
final void
setAlpha(@FloatRange(from = 0.0, to = 1.0) float alpha)

Sets the alpha transparency of the Entity relative to the parent Space.
final void

Alternate text for this Entity to be consumed by Accessibility systems.
final void
setEnabled(boolean enabled)

Sets the local enabled state of this Entity.
final void

The parent of this Entity, from which this Entity will inherit most of its properties.

Public methods

addOriginChangedListener

Added in 1.0.0-alpha16
public final void addOriginChangedListener(@NonNull Runnable listener)

Adds a listener to be called when the Anchor's origin moves relative to its underlying space.

The callback is triggered on the main thread by any anchor movements, for example when the perception system moves the anchor's origin 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. It will be automatically unregistered when the entity is disposed.

Parameters
@NonNull Runnable listener

The listener to register. Events will fire on the main thread.

addOriginChangedListener

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

Adds a listener to be called when the Anchor's origin moves relative to its underlying space.

The callback is triggered on the supplied Executor by any anchor movements, for example when the perception system moves the anchor's origin 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. It will be automatically unregistered when the entity is disposed.

Parameters
@NonNull Executor executor

The executor to run the listener on.
@NonNull Runnable listener

The listener to register.

addStateChangedListener

Added in 1.0.0-alpha16
public final void addStateChangedListener(
    @NonNull Consumer<@NonNull AnchorEntity.State> listener
)

Adds a listener to be invoked on the main thread when the AnchorEntity's state changes.

The listener will fire on the main thread with the current AnchorEntity.State value immediately upon registration. It will be automatically unregistered when the entity is disposed.

addStateChangedListener

Added in 1.0.0-alpha16
public final void addStateChangedListener(
    @NonNull Executor executor,
    @NonNull Consumer<@NonNull AnchorEntity.State> listener
)

Adds a listener to be invoked on the given Executor when the AnchorEntity's state changes.

The listener will fire with the current State value immediately upon registration. It will be automatically unregistered when the entity is disposed.

Parameters
@NonNull Executor executor

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

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

create

Added in 1.0.0-alpha16
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-alpha16
public static final @NonNull AnchorEntity create(
    @NonNull Session session,
    @NonNull FloatSize2d minimumPlaneExtents,
    @NonNull Set<@NonNull PlaneOrientation> planeOrientations,
    @NonNull Set<@NonNull PlaneSemanticType> planeSemanticTypes,
    @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.
@NonNull Set<@NonNull PlaneOrientation> planeOrientations

PlaneOrientations of the plane to which this AnchorEntity should attach.
@NonNull Set<@NonNull PlaneSemanticType> planeSemanticTypes

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

The amount of time as a Duration to search for the suitable plane to attach to. If a plane is not found within the timeout, the returned AnchorEntity state will be set to AnchorEntity.State.TIMED_OUT. 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
IllegalStateException

if Session.config is set to PlaneTrackingMode.DISABLED.

getAnchor

Added in 1.0.0-alpha16
public final Anchor getAnchor()

Returns the ARCore for Jetpack XR Anchor associated with this AnchorEntity.

Returns
Anchor

the ARCore for Jetpack XR Anchor associated with this AnchorEntity. This may be null if the AnchorEntity is still searching for a suitable anchor.

getPose

public @NonNull Pose getPose(@NonNull Space relativeTo)

Returns the pose of the AnchorEntity relative to the specified coordinate space.

Parameters
@NonNull Space relativeTo

The coordinate space to get the pose relative to. Defaults to Space.PARENT.
Returns
@NonNull Pose

The current pose of the AnchorEntity.
Throws
IllegalArgumentException

if called with Space.PARENT since AnchorEntity has no parents.

getScale

public float getScale(@NonNull Space relativeTo)

Returns the scale of the AnchorEntity relative to the specified coordinate space.

Parameters
@NonNull Space relativeTo

The coordinate space to get the scale relative to. Defaults to Space.PARENT.
Returns
float

The current scale of the AnchorEntity.
Throws
IllegalArgumentException

if called with Space.PARENT since AnchorEntity has no parents.

getState

Added in 1.0.0-alpha16
public final @NonNull AnchorEntity.State getState()

The current tracking state for this AnchorEntity.

removeOriginChangedListener

Added in 1.0.0-alpha16
public final void removeOriginChangedListener(@NonNull Runnable listener)

Removes the listener to be called when the Anchor's origin moves relative to its underlying space.

Parameters
@NonNull Runnable listener

The listener to remove.

removeStateChangedListener

Added in 1.0.0-alpha16
public final void removeStateChangedListener(
    @NonNull Consumer<@NonNull AnchorEntity.State> listener
)

Removes the given state changed listener.

Parameters
@NonNull Consumer<@NonNull AnchorEntity.State> listener

: The listener to be removed.