# Class ARSession

java.lang.Object
com.codename1.ar.ARSession

All Implemented Interfaces:
  `AutoCloseable`

public final class ARSession extends Object implements AutoCloseable

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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addAnchorListener(ARAnchorListener l)`
  Registers an anchor listener.
  `void`
  `addPlaneListener(ARPlaneListener l)`
  Registers a plane listener.
  `void`
  `addTrackingListener(ARTrackingListener l)`
  Registers a tracking state listener.
  `void`
  `close()`
  Releases the session.
  `ARAnchor`
  `createAnchor(ARPose pose)`
  Creates an anchor at an arbitrary world pose and registers it with the session.
  `ARView`
  `createView()`
  Creates the AR view that renders the camera image composited with the anchored content.
  `ARAnchor[]`
  `getAnchors()`
  The anchors currently registered with the session, in registration order.
  `ARPose`
  `getCameraPose()`
  The latest device pose in world space.
  `ARLightEstimate`
  `getLightEstimate()`
  The latest estimate of real-world lighting.
  `ARSessionOptions`
  `getOptions()`
  The options the session was opened with.
  `ARPlane[]`
  `getPlanes()`
  The planes the session currently tracks, in detection order.
  `ARTrackingFailureReason`
  `getTrackingFailureReason()`
  Why tracking is degraded, or `ARTrackingFailureReason#NONE` when it is not.
  `ARTrackingState`
  `getTrackingState()`
  The session's overall tracking quality as of the latest update.
  `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.
  `boolean`
  `isClosed()`
  True once `#close()` has been called on this session.
  `void`
  `pause()`
  Suspends tracking and the camera while keeping this session object alive.
  `void`
  `removeAnchorListener(ARAnchorListener l)`
  Removes an anchor listener.
  `void`
  `removePlaneListener(ARPlaneListener l)`
  Removes a plane listener.
  `void`
  `removeTrackingListener(ARTrackingListener l)`
  Removes a tracking state listener.
  `void`
  `resume()`
  Re-acquires the camera and resumes tracking after `#pause()`.

  ### Methods inherited from class Object

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

- ## 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`: the horizontal view coordinate, `0.0` to `1.0`

    - `yNorm`: 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`: 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.
    Specified by:
      `close` in interface `AutoCloseable`

  - ### isClosed

    public boolean isClosed()
    True once `#close()` has been called on this session.