public final class ARSession

Object
ARSession

Active augmented reality session. Obtained from AR#open(ARSessionOptions).

Only one ARSession may be open at a time; opening a second throws IllegalStateException. Closing the session releases the camera and tracking hardware and invalidates the ARView returned by #createView().

All events are delivered on the EDT and every getter reflects the state as of the most recently delivered events. High-frequency refinements (anchor and plane updates, camera pose, light estimate) are coalesced so the EDT sees the latest value rather than a backlog.

Methods

`public` `ARView createView()`	Creates the AR view that renders the camera image composited with the anchored content.
`public` `ARSessionOptions getOptions()`	The options the session was opened with.
`public` `ARTrackingState getTrackingState()`	The session’s overall tracking quality as of the latest update.
`public` `ARTrackingFailureReason getTrackingFailureReason()`	Why tracking is degraded, or `ARTrackingFailureReason#NONE` when it is not.
`public` `ARPose getCameraPose()`	The latest device pose in world space.
`public` `ARLightEstimate getLightEstimate()`	The latest estimate of real-world lighting.
`public` `AsyncResource<ARHitResult[]> hitTest(float xNorm, float yNorm)`	Performs an asynchronous hit test from a normalized view coordinate (`0.0` top left to `1.0` bottom right) into the world.
`public` `ARAnchor createAnchor(ARPose pose)`	Creates an anchor at an arbitrary world pose and registers it with the session.
`public` `ARAnchor[] getAnchors()`	The anchors currently registered with the session, in registration order.
`public` `ARPlane[] getPlanes()`	The planes the session currently tracks, in detection order.
`public void addTrackingListener(ARTrackingListener l)`	Registers a tracking state listener.
`public void removeTrackingListener(ARTrackingListener l)`	Removes a tracking state listener.
`public void addPlaneListener(ARPlaneListener l)`	Registers a plane listener.
`public void removePlaneListener(ARPlaneListener l)`	Removes a plane listener.
`public void addAnchorListener(ARAnchorListener l)`	Registers an anchor listener.
`public void removeAnchorListener(ARAnchorListener l)`	Removes an anchor listener.
`public void pause()`	Suspends tracking and the camera while keeping this session object alive.
`public void resume()`	Re-acquires the camera and resumes tracking after `#pause()`.
`public void close()`	Releases the session.
`public boolean isClosed()`	True once `#close()` has been called on this session.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Method details

createView

public ARView createView()

Creates the AR view that renders the camera image composited with the anchored content. Each session owns one view; subsequent calls return the same instance.

getOptions

public ARSessionOptions getOptions()

The options the session was opened with. Read-only snapshot; mutating it after AR#open(ARSessionOptions) has no effect.

getTrackingState

public ARTrackingState getTrackingState()

The session’s overall tracking quality as of the latest update.

getTrackingFailureReason

public ARTrackingFailureReason getTrackingFailureReason()

Why tracking is degraded, or ARTrackingFailureReason#NONE when it is not.

getCameraPose

public ARPose getCameraPose()

The latest device pose in world space. Poll-style: the value refreshes every frame without firing events.

getLightEstimate

public ARLightEstimate getLightEstimate()

The latest estimate of real-world lighting. Poll-style: the value refreshes every frame without firing events. Before the first platform estimate this returns ARLightEstimate#INVALID.

hitTest

public AsyncResource<ARHitResult[]> hitTest(float xNorm, float yNorm)

Performs an asynchronous hit test from a normalized view coordinate (0.0 top left to 1.0 bottom right) into the world. The returned AsyncResource resolves on the EDT with the intersections ordered nearest first; an empty array means nothing was hit.

Parameters

xNorm float: the horizontal view coordinate, 0.0 to 1.0
yNorm float: the vertical view coordinate, 0.0 to 1.0

Returns

resolves with the hits; call ARHitResult#createAnchor() on one to place content there

createAnchor

public ARAnchor createAnchor(ARPose pose)

Creates an anchor at an arbitrary world pose and registers it with the session. Prefer ARHitResult#createAnchor() when placing content on detected geometry.

Parameters

pose ARPose: the world pose to anchor

Returns

the new anchor

getAnchors

public ARAnchor[] getAnchors()

The anchors currently registered with the session, in registration order.

getPlanes

public ARPlane[] getPlanes()

The planes the session currently tracks, in detection order.

addTrackingListener

public void addTrackingListener(ARTrackingListener l)

Registers a tracking state listener. Events fire on the EDT.

removeTrackingListener

public void removeTrackingListener(ARTrackingListener l)

Removes a tracking state listener.

addPlaneListener

public void addPlaneListener(ARPlaneListener l)

Registers a plane listener. Events fire on the EDT.

removePlaneListener

public void removePlaneListener(ARPlaneListener l)

Removes a plane listener.

addAnchorListener

public void addAnchorListener(ARAnchorListener l)

Registers an anchor listener. Events fire on the EDT.

removeAnchorListener

public void removeAnchorListener(ARAnchorListener l)

Removes an anchor listener.

pause

public void pause()

Suspends tracking and the camera while keeping this session object alive. Pair with #resume().

resume

public void resume()

Re-acquires the camera and resumes tracking after #pause().

close

public void close()

Releases the session. Idempotent.

isClosed

public boolean isClosed()

True once #close() has been called on this session.