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 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.