Session

public class Session

Manages AR system state and handles the session lifecycle. This class is the main entry point to ARCore API. This class allows the user to create a session, configure it, start/stop it, and most importantly receive frames that allow access to camera image and device pose.

Public Constructors

Session(Context context)
Creates a new ARCore session.

Protected Constructors

Session()
(FOR TESTING) Constructs a new instance for use as a mock.

Public Methods

void
configure(Config config)
Configures the session.
Anchor
createAnchor(Pose pose)
Defines a tracked location in the physical world.
Collection<Anchor>
getAllAnchors()
Returns all known anchors, including those not currently tracked.
<T extends Trackable> Collection<T>
getAllTrackables(Class<T> filterType)
Returns the list of all known trackables.
boolean
isSupported(Config config)
Checks if the provided configuration is usable on the this device.
void
pause()
Pause the current session.
void
resume()
Starts or resumes the ARCore Session.
void
setCameraTextureName(int textureId)
Sets the OpenGL texture name (id) that will allow GPU access to the camera image.
void
setDisplayGeometry(int displayRotation, int widthPx, int heightPx)
Sets the aspect ratio, coordinate scaling, and display rotation.
Frame
update()
Updates the state of the ARCore system.

Protected Methods

long[]
nativeAcquireAllTrackables(long sessionHandle, int filterType)

Inherited Methods

Public Constructors

public Session (Context context)

Creates a new ARCore session. This must be the first ARCore action that your application takes.

Parameters
context the Context for your app
Throws
FatalException if an internal error occurred while creating the session. adb logcat may contain useful information.
UnavailableArcoreNotInstalledException if the ARCore APK is not present
UnavailableSdkTooOldException if the ARCore SDK that this application was built with is too old and no longer supported by the installed ARCore APK.
UnavailableApkTooOldException if the installed ARCore APK is too old for the ARCore SDK with which this application was built.
SecurityException if client app fails to grant CameraPermission.
FatalException if initialization failed for any other reason.

Protected Constructors

protected Session ()

(FOR TESTING) Constructs a new instance for use as a mock. Calling any base method implementation on this instance may return unexpected results, throw an exception, or even crash.

To create a Session normally, use Session(Context).

Public Methods

public void configure (Config config)

Configures the session.

A session initially has a default configuration. This should be called if a configuration different than default is needed. Before calling this method, the configuration should be checked with isSupported(Config).

Parameters
config The new configuration setting for the session.
See Also

public Anchor createAnchor (Pose pose)

Defines a tracked location in the physical world. See Anchor for more details.

Parameters
pose a pose to anchor to the physical world
See Also

public Collection<Anchor> getAllAnchors ()

Returns all known anchors, including those not currently tracked. Anchors forgotten by ARCore due to a call to detach() or entering the STOPPED state will not be included.

public Collection<T> getAllTrackables (Class<T> filterType)

Returns the list of all known trackables. This includes Planes if plane detection is enabled, as well as Points created as a side effect of calls to createAnchor(Pose) or hitTest(float, float).

Parameters
filterType The desired trackable type, or Trackable.class to retrieve all trackables.

public boolean isSupported (Config config)

Checks if the provided configuration is usable on the this device. If this method returns false, calls to configure(Config) with this configuration will throw an exception.

Parameters
config the configuration to test

public void pause ()

Pause the current session. This method will stop the camera feed and release resources. The session can be restarted again by calling resume().

Typically this should be called from onPause().

public void resume ()

Starts or resumes the ARCore Session.

Typically this should be called from onResume().

public void setCameraTextureName (int textureId)

Sets the OpenGL texture name (id) that will allow GPU access to the camera image. The provided ID should have been created with glGenTextures(int, int[], int). The resulting texture must be bound to the GL_TEXTURE_EXTERNAL_OES target for use. Shaders accessing this texture must use a samplerExternalOES sampler. See sample code for an example.

Parameters
textureId a valid OpenGL texture name (id)

public void setDisplayGeometry (int displayRotation, int widthPx, int heightPx)

Sets the aspect ratio, coordinate scaling, and display rotation. This data is used by UV conversion, projection matrix generation, and hit test logic.

Parameters
displayRotation display rotation specified by Surface constants: ROTATION_0, ROTATION_90, ROTATION_180, ROTATION_270,
widthPx width of the view, in pixels
heightPx height of the view, in pixels

public Frame update ()

Updates the state of the ARCore system. This includes: receiving a new camera frame, updating the location of the device, updating the location of tracking anchors, updating detected planes, etc.

This call may cause off-screen OpenGL activity. Because of this, to avoid unnecessary frame buffer flushes and reloads, this call should not be made in the middle of rendering an frame or offscreen buffer.

This call may update the pose of all created Anchors and detected Planes. The set of updated objects is accessible through getUpdatedTrackables(Class).

This call may block until a new camera frame is available. See Config.UpdateMode for details.

Returns
  • The most recent Frame received

Protected Methods

protected long[] nativeAcquireAllTrackables (long sessionHandle, int filterType)

Parameters
sessionHandle
filterType

Send feedback about...