class AnchorEntity : BaseEntity

kotlin.Any
   ↳ androidx.xr.scenecore.BaseScenePose
     ↳ androidx.xr.scenecore.BaseEntity
       ↳ androidx.xr.scenecore.AnchorEntity

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 companion functions
AnchorEntity
create(session: Session, anchor: Anchor)

Public factory for an AnchorEntity which uses an Anchor from ARCore for Jetpack XR.
AnchorEntity
create(
    session: Session,
    minimumPlaneExtents: FloatSize2d,
    planeOrientation: Int,
    planeSemanticType: Int,
    timeout: Duration
)

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.

Public functions
open Unit

Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children.
Anchor?

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

Returns the pose of the AnchorEntity relative to the specified coordinate space.
open Float
getScale(relativeTo: Space)

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

Registers a listener to be called when the Anchor moves relative to its underlying space.
Unit
setOnSpaceUpdatedListener(executor: Executor, listener: Runnable?)

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

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.
Unit
setOnStateChangedListener(
    executor: Executor,
    listener: Consumer<AnchorEntity.State>?
)

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.

Public properties
AnchorEntity.State

The current tracking state for this AnchorEntity.

Inherited functions
From androidx.xr.scenecore.BaseEntity
open Unit
addChild(child: Entity)

Sets an Entity to be a child of this Entity in the scene graph.
open Boolean
addComponent(component: Component)

Adds a Component to this Entity.
open Float
getAlpha(relativeTo: Space)

Returns the alpha transparency set for this Entity, relative to given Space.
open List<Component>

Retrieves all components attached to this Entity.
open List<T>

Retrieves all Components of the given type T and its sub-types attached to this Entity.
open Boolean
isEnabled(includeParents: Boolean)

Returns the enabled status of this Entity.
open Unit

Remove all components from this Entity.
open Unit

Removes the given Component from this Entity.
open Unit
setAlpha(alpha: Float, relativeTo: Space)

Sets the alpha transparency of the Entity relative to given Space.
open Unit
setEnabled(enabled: Boolean)

Sets the local enabled state of this Entity.
From androidx.xr.scenecore.Entity
open @FloatRange(from = 0.0, to = 1.0) Float

Returns the alpha transparency set for this Entity.
open Pose

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

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

Sets the alpha transparency of the Entity and its children.
open Unit
setPose(pose: Pose)

Sets the Pose for this Entity, relative to its parent.
open Unit
setScale(scale: @FloatRange(from = 0.0) Float)

Sets the scale of this Entity relative to its parent.
From androidx.xr.scenecore.ScenePose
abstract suspend HitTestResult?
hitTest(origin: Vector3, direction: Vector3)

Perform a hit test from the specified origin in the specified direction into the Scene.
abstract suspend HitTestResult?
hitTest(origin: Vector3, direction: Vector3, hitTestFilter: Int)

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

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

Inherited properties
From androidx.xr.scenecore.BaseEntity
open List<Entity>

Provides the list of all children of this entity.
open CharSequence

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

The parent of this Entity, from which this Entity will inherit most of its properties.
From androidx.xr.scenecore.ScenePose
abstract Pose

The current Pose relative to the activity space root.

Public companion functions

create

Added in 1.0.0-alpha09
fun create(session: Session, anchor: Anchor): AnchorEntity

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

Parameters
session: Session

Session in which to create the AnchorEntity.
anchor: Anchor

The Anchor to use for this AnchorEntity.

create

Added in 1.0.0-alpha09
fun create(
    session: Session,
    minimumPlaneExtents: FloatSize2d,
    planeOrientation: Int,
    planeSemanticType: Int,
    timeout: Duration = Duration.ZERO
): AnchorEntity

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
session: Session

Session in which to create the AnchorEntity.
minimumPlaneExtents: FloatSize2d

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

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

PlaneSemanticType of the plane to which this AnchorEntity should attach.
timeout: Duration = Duration.ZERO

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.

Public functions

dispose

open fun dispose(): Unit

Disposes of any system resources held by this Entity, and transitively calls dispose() on all its children. Once disposed, this Entity is invalid and cannot be used again.

getAnchor

Added in 1.0.0-alpha09
fun getAnchor(): Anchor?

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

open fun getPose(relativeTo: Space): Pose

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

Parameters
relativeTo: Space

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

The current pose of the AnchorEntity.
Throws
kotlin.IllegalArgumentException

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

getScale

open fun getScale(relativeTo: Space): Float

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

Parameters
relativeTo: Space

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

The current scale of the AnchorEntity.
Throws
kotlin.IllegalArgumentException

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

setOnSpaceUpdatedListener

Added in 1.0.0-alpha09
fun setOnSpaceUpdatedListener(listener: Runnable?): Unit

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. It will be automatically unregistered when the entity is disposed.

Parameters
listener: Runnable?

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

setOnSpaceUpdatedListener

Added in 1.0.0-alpha09
fun setOnSpaceUpdatedListener(executor: Executor, listener: Runnable?): Unit

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. It will be automatically unregistered when the entity is disposed.

Parameters
executor: Executor

The executor to run the listener on.
listener: Runnable?

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

setOnStateChangedListener

Added in 1.0.0-alpha09
fun setOnStateChangedListener(listener: Consumer<AnchorEntity.State>?): Unit

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. It will be automatically unregistered when the entity is disposed.

setOnStateChangedListener

Added in 1.0.0-alpha09
fun setOnStateChangedListener(
    executor: Executor,
    listener: Consumer<AnchorEntity.State>?
): Unit

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. It will be automatically unregistered when the entity is disposed.

Parameters
executor: Executor

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

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

Public properties

state

Added in 1.0.0-alpha09
val state: AnchorEntity.State

The current tracking state for this AnchorEntity.