Session

public class Session

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

Important:

Before creating a Session, you must first verify that ARCore is installed.. If ARCore isn't installed, then session creation will fail and any subsequent installation or upgrade of ARCore will require an app restart, and might cause Android to kill the app. You can verify ARCore's installation status by:

The Java garbage collector automatically releases the session resources. To explicitly release resources call close().

Nested Classes

enum Session.Feature Fundamental session features that can be requested using Session(Context, Set)

Public Constructors

Session(Context context)
Creates a new ARCore session.
Session(Context context, Set<Session.Feature> features)
Creates a new ARCore session requesting additional features.

Protected Constructors

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

Public Methods

void
close()
Releases resources used by an ARCore session.
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.
CameraConfig
getCameraConfig()
Gets the current camera config used by the session.
void
getConfig(Config configToFill)
Similar to getConfig(), but takes a config object to fill.
Config
getConfig()
Gets the current config.
SharedCamera
getSharedCamera()
Gets the SharedCamera object if the session was created for camera sharing using SHARED_CAMERA.
List<CameraConfig>
getSupportedCameraConfigs(CameraConfigFilter cameraConfigFilter)
Gets the list of supported camera configs that satisfy the provided filter settings.
List<CameraConfig>
getSupportedCameraConfigs()
This method is deprecated. in release 1.11.0. Please use instead: Session#getSupportedCameraConfigs(CameraConfigFilter).
Anchor
hostCloudAnchor(Anchor anchor)
Uses the pose and other data from anchor to create a new anchor that will be hosted.
boolean
isSupported(Config config)
This method is deprecated. in release 1.2.0. Please refer to (release notes 1.2.0).
void
pause()
Pause the current session.
Anchor
resolveCloudAnchor(String cloudAnchorId)
Creates a new anchor whose pose will be resolved from the ARCore Cloud using the given cloudAnchorId.
void
resume()
Starts or resumes the ARCore Session.
void
setCameraConfig(CameraConfig cameraConfig)
Sets the camera config to use.
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.

Inherited Methods

Public Constructors

public Session (Context context)

Creates a new ARCore session.

Before calling this constructor, your app must check that a compatible version of ARCore is installed. See the Session class-level documentation for details.

When created through this constructor, ARCore holds exclusive access to the camera while the session is running. If you want to share the camera with ARCore (for example, to enable fast switching between AR and non-AR modes), consider using SHARED_CAMERA.

Parameters
context the Context for your app
Throws
FatalException if an internal error occurred while creating the session. adb logcat may contain useful information.
SecurityException if your app does not have the CAMERA permission.
UnavailableArcoreNotInstalledException if the ARCore APK is not present. This can be prevented by the installation check described in the Session class-level documentation.
UnavailableSdkTooOldException if the ARCore SDK that this app was built with is too old and is no longer supported by the installed ARCore APK.
UnavailableApkTooOldException if the installed ARCore APK is too old for the ARCore SDK with which this app was built. This can be prevented by the installation check described in the Session class-level documentation.
UnavailableDeviceNotCompatibleException if the device is not compatible with ARCore. If encountered after completing the installation check, this usually indicates that ARCore has been side-loaded onto an incompatible device.

public Session (Context context, Set<Session.Feature> features)

Creates a new ARCore session requesting additional features.

Before calling this constructor, your app must check that a compatible version of ARCore is installed. See the Session class-level documentation for details.

Parameters
context the Context for your app
features the features requested
Throws
FatalException if an internal error occurred while creating the session. adb logcat may contain useful information.
SecurityException if your app does not have the CAMERA permission.
UnavailableArcoreNotInstalledException if the ARCore APK is not present. This can be prevented by the installation check described in the Session class-level documentation.
UnavailableSdkTooOldException if the ARCore SDK that this app was built with is too old and is no longer supported by the installed ARCore APK.
UnavailableApkTooOldException if the installed ARCore APK is too old for the ARCore SDK with which this app was built. This can be prevented by the installation check described in the Session class-level documentation.
IllegalArgumentException if the requested features are mutually incompatible. See Session.Feature for details. This is not possible with the currently available features.
UnavailableDeviceNotCompatibleException if the device is not compatible with ARCore. If encountered after completing the installation check, this usually indicates that ARCore has been side-loaded onto an incompatible device.

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 close ()

Releases resources used by an ARCore session.

This method will take several seconds to complete. To prevent blocking the main thread, call pause() on the main thread, and then call close() on a background thread.

It is not safe to call methods on this session or other objects obtained from this session while the session is being closed and after the session is closed.

When closing a session that was created with SHARED_CAMERA, the camera device must be closed via CameraDevice#close() before calling this method.

Creation of a new session on a different thread will not be blocked by the ongoing call to close() on a background thread.

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.

The following configurations are unsupported:

Parameters
config The new configuration setting for the session.
Throws
UnsupportedConfigurationException if the configuration requested is not supported. See above restrictions.
See Also

public Anchor createAnchor (Pose pose)

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

Anchors incur ongoing processing overhead within ARCore. To release unneeded anchors use detach().

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 CameraConfig getCameraConfig ()

Gets the current camera config used by the session.

Returns

public void getConfig (Config configToFill)

Similar to getConfig(), but takes a config object to fill. Use this form to avoid extra object allocations.

Parameters
configToFill
See Also

public Config getConfig ()

Gets the current config. More specifically, returns a copy of the config most recently set by configure(Config).

Note: if the session was not explicitly configured, a default configuration is returned (same as new Config(session)).

To avoid allocations, use getConfig(Config) instead.

public SharedCamera getSharedCamera ()

Gets the SharedCamera object if the session was created for camera sharing using SHARED_CAMERA.

Throws
IllegalStateException if session is not created for shared camera.

public List<CameraConfig> getSupportedCameraConfigs (CameraConfigFilter cameraConfigFilter)

Gets the list of supported camera configs that satisfy the provided filter settings.

The returned camera configs might vary at runtime depending on device capabilities. Overly restrictive filtering can result in the returned list being empty on one or more devices.

Element 0 will contain the camera config that best matches the filter settings, according to the following priority:

  1. Prefer TARGET_FPS_60 over TARGET_FPS_30
  2. Prefer REQUIRE_AND_USE over DO_NOT_USE

No guarantees are made about the order in which the remaining elements are returned.

Can be called at any time.

Parameters
cameraConfigFilter The CameraConfigFilter that defines the configuration filter(s).
Returns
  • The list of CameraConfig CameraConfig objects that provide supported configurations.
Throws
IllegalArgumentException if the cameraConfigFilter is null.

public List<CameraConfig> getSupportedCameraConfigs ()

This method was deprecated in API level .
in release 1.11.0. Please use instead: Session#getSupportedCameraConfigs(CameraConfigFilter).

Gets a list of camera configs supported by the camera being used by the session.

Can be called at any time.

Each config will contain a different CPU resolution. The GPU texture resolutions will be the same in all configs. Most devices provide a GPU texture resolution of 1920 x 1080, but the actual resolution will vary with device capabilities.

When the session camera is a back-facing camera:

  • The list will always contain three camera configs.
  • The CPU image resolutions returned will be VGA, a middle resolution, and a large resolution matching the GPU texture resolution. The middle resolution is typically 1280 x 720, but the actual resolution will vary with device capabilities.

When the session camera is front-facing (selfie) camera, the list will contain at least one supported camera config.

Notes:

  • Prior to ARCore SDK 1.6, the middle CPU image resolution was guaranteed to be 1280 x 720 on all devices.
  • In ARCore SDK 1.7 and 1.8, when the session camera was a front-facing (selfie) camera, the list contained three identical camera configs.

Returns
  • The list of CameraConfig CameraConfig objects supported by the camera being used by the session.

public Anchor hostCloudAnchor (Anchor anchor)

Uses the pose and other data from anchor to create a new anchor that will be hosted. The returned anchor will have the cloud anchor state TASK_IN_PROGRESS.

Parameters
anchor The anchor whose pose is to be hosted.
Returns
  • The new anchor with the same pose as anchor which will be hosted.

public boolean isSupported (Config config)

This method was deprecated in API level .
in release 1.2.0. Please refer to (release notes 1.2.0).

Before release 1.2.0: 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.

This function now always returns true. See documentation for each configuration entry to know which configuration options & combinations are supported.

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

Note that ARCore might continue consuming substantial computing resources for up to 10 seconds after calling this method.

public Anchor resolveCloudAnchor (String cloudAnchorId)

Creates a new anchor whose pose will be resolved from the ARCore Cloud using the given cloudAnchorId. The returned anchor will have the cloud anchor state TASK_IN_PROGRESS.

Parameters
cloudAnchorId The cloud anchor ID of the cloud anchor.
Returns
  • The new anchor whose pose will be resolved in a later call to update().

public void resume ()

Starts or resumes the ARCore Session.

Typically this should be called from onResume().

Note that if the camera configuration has been changed by setCameraConfig(CameraConfig) since the last call to resume(), all images previously acquired using acquireCameraImage() must be released by calling close() before resuming. If there are open images, resume() will throw IllegalStateException.

public void setCameraConfig (CameraConfig cameraConfig)

Sets the camera config to use. The config must be one returned by getSupportedCameraConfigs(CameraConfigFilter).

The session must be paused. The camera config will be applied once the session is resumed. All previously acquired frame images must be released via close() before resuming. Failure to do so will cause resume() to throw IllegalStateException.

Note: Starting in ARCore 1.12, changing the active camera config may cause the tracking state on certain devices to become permanently PAUSED. For consistent behavior across all supported devices, release any previously created anchors and trackables when setting a new camera config.

Parameters
cameraConfig Reference to one of the CameraConfig that was obtained by the call to getSupportedCameraConfigs(CameraConfigFilter) method.

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 a 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 in blocking mode (see Config.UpdateMode) will wait until a new camera image is available, or until the built-in timeout (currently 66ms) is reached. If the camera image does not arrive by the built-in timeout, then update() will return the most recent Frame object. For some applications it may be important to know if a new frame was actually obtained (for example, to avoid redrawing if the camera did not produce a new frame). To do that, compare the current frame's timestamp, obtained via getTimestamp(), with the previously recorded frame timestamp. If they are different, this is a new frame.

During startup the camera system may not produce actual images immediately. In this common case, a frame with timestamp = 0 will be returned.

Returns
  • The most recent Frame received
Throws
CameraNotAvailableException if the camera could not be opened.
SessionPausedException if the session is currently paused.
MissingGlContextException if there is no OpenGL context available.