Thanks for tuning in to Google I/O! Watch AR content on-demand.

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 and up to date. 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 is installed and up to date by:

Checking ArCoreApk.checkAvailability(Context) returns ArCoreApk.Availability.SUPPORTED_INSTALLED, or by checking
ArCoreApk.requestInstall(Activity, boolean) (or another form of requestInstall()) returns ArCoreApk.InstallStatus.INSTALLED.

This class owns a significant amount of native heap memory. When the AR session is no longer needed, call close() to release native resources. If your app contains a single AR-enabled activity, it is recommended that you call close() from the activity's onDestroy method. Failure to close the session explicitly may cause your app to run out of native memory and crash.

Nested Classes

`enum`	`Session.Feature`		Fundamental session features that can be requested using `Session.Session(Context, Set)`.
`enum`	`Session.FeatureMapQuality`		Indicates the quality of the visual features seen by ARCore in the preceding few seconds from a given camera `Pose`.

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.

Public Methods

`VpsAvailabilityFuture`	`checkVpsAvailabilityAsync(double latitude, double longitude, Consumer<VpsAvailability> callback)` Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position.
`void`	`close()` Releases resources (a significant amount of native heap memory) used by an ARCore session.
`void`	`configure(Config config)` Configures the session and verifies that the enabled features in the specified session config are supported with the currently set camera config.
`Anchor`	`createAnchor(Pose pose)` Defines a tracked location in the physical world.
`Session.FeatureMapQuality`	`estimateFeatureMapQualityForHosting(Pose pose)` Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera pose.
`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.
`Earth`	`getEarth()` Returns the `Earth` object for the session.
`PlaybackStatus`	`getPlaybackStatus()` Returns the current playback status.
`RecordingStatus`	`getRecordingStatus()` Returns the current recording status.
`SharedCamera`	`getSharedCamera()` Gets the SharedCamera object if the session was created for camera sharing using `Session.Feature.SHARED_CAMERA`.
`List<CameraConfig>`	`getSupportedCameraConfigs()` This method is deprecated. Please use instead: `getSupportedCameraConfigs(CameraConfigFilter)`.
`List<CameraConfig>`	`getSupportedCameraConfigs(CameraConfigFilter cameraConfigFilter)` Gets the list of supported camera configs that satisfy the provided filter settings.
`Anchor`	`hostCloudAnchor(Anchor anchor)` This method is deprecated. Use `hostCloudAnchorAsync(Anchor, int, BiConsumer)` with ttlDays=1 instead.
`HostCloudAnchorFuture`	`hostCloudAnchorAsync(Anchor anchor, int ttlDays, BiConsumer<String, Anchor.CloudAnchorState> callback)` Uses the pose and other data from `anchor` to host a new Cloud Anchor.
`Anchor`	`hostCloudAnchorWithTtl(Anchor anchor, int ttlDays)` This method is deprecated. Use `hostCloudAnchorAsync(Anchor, int, BiConsumer)` with ttlDays=1 instead.
`boolean`	`isDepthModeSupported(Config.DepthMode mode)` Checks whether the provided `Config.DepthMode` is supported on this device with the selected camera configuration.
`boolean`	`isGeospatialModeSupported(Config.GeospatialMode geospatialMode)` Checks whether the provided `Config.GeospatialMode` is supported on this device.
`boolean`	`isImageStabilizationModeSupported(Config.ImageStabilizationMode imageStabilizationMode)` Checks whether the provided `Config.ImageStabilizationMode` is supported on this device with the selected camera configuration.
`boolean`	`isSemanticModeSupported(Config.SemanticMode mode)` Checks whether the provided `Config.SemanticMode` is supported on this device with the selected camera configuration.
`boolean`	`isSupported(Config config)` This method is deprecated. Please refer to (release notes 1.2.0).
`void`	`pause()` Pause the current session.
`Anchor`	`resolveCloudAnchor(String cloudAnchorId)` This method is deprecated. Use `resolveCloudAnchorAsync(String, BiConsumer)` instead.
`ResolveCloudAnchorFuture`	`resolveCloudAnchorAsync(String cloudAnchorId, BiConsumer<Anchor, Anchor.CloudAnchorState> callback)` Attempts to resolve a Cloud Anchor using the provided `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`	`setCameraTextureNames(int[] textureIds)` Sets the OpenGL texture names (ids) that will be assigned to incoming camera frames in sequence in a ring buffer.
`void`	`setDisplayGeometry(int displayRotation, int widthPx, int heightPx)` Sets the aspect ratio, coordinate scaling, and display rotation.
`void`	`setPlaybackDataset(String mp4DatasetFilePath)` This method is deprecated. Please use `setPlaybackDatasetUri(Uri)` to play back datasets.
`void`	`setPlaybackDatasetUri(Uri mp4DatasetUri)` Sets a MP4 dataset to play back instead of live camera feed.
`void`	`startRecording(RecordingConfig recordingConfig)` Starts a new MP4 dataset file recording that is written to the specific filesystem path.
`void`	`stopRecording()` Stops recording and flushes unwritten data to disk.
`Frame`	`update()` Updates the state of the ARCore system.

Inherited Methods

From

class
            java.lang.Object

`Object`	`clone()`
`boolean`	`equals(Object arg0)`
`void`	`finalize()`
`final Class<?>`	`getClass()`
`int`	`hashCode()`
`final void`	`notify()`
`final void`	`notifyAll()`
`String`	`toString()`
`final void`	`wait(long arg0, int arg1)`
`final void`	`wait(long arg0)`
`final void`	`wait()`

Public Constructors

public Session (Context context)

Session

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 Session.Feature.SHARED_CAMERA.

Details

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 `Manifest.permission.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)

Session

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.

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 `Manifest.permission.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.

Public Methods

public VpsAvailabilityFuture checkVpsAvailabilityAsync (double latitude, double longitude, Consumer<VpsAvailability> callback)

checkVpsAvailabilityAsync

public VpsAvailabilityFuture checkVpsAvailabilityAsync(
  double latitude,
  double longitude,
  Consumer<VpsAvailability> callback
)

Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position. The availability of VPS in a given location helps to improve the quality of Geospatial localization and tracking accuracy.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See Future for information on obtaining results and cancelling the operation.

This may be called without calling resume() or configure(Config).

Your app must be properly set up to communicate with the Google Cloud ARCore API in order to obtain a result from this call. See Check VPS Availability for more details on setup steps and usage examples.

Details

Parameters

`latitude`	The latitude in degrees.
`longitude`	The longitude in degrees.
`callback`	An optional callback, called when the operation is finished, unless the future is cancelled. May be null.

Returns A handler that can be polled or cancelled.

Throws

SecurityException if the Android INTERNET permission has not been granted.

public void close ()

close

public void close()

Releases resources (a significant amount of native heap memory) used by an ARCore session.

Failure to close sessions explicitly may cause your app to run out of native memory and crash. If your app contains a single AR-enabled activity, it is recommended that you call close() from the activity's onDestroy method.

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 Session.Feature.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)

configure

public void configure(
  Config config
)

Configures the session and verifies that the enabled features in the specified session config are supported with the currently set camera config.

Should be called after setCameraConfig(CameraConfig) to verify that all requested session config features are supported. Features not supported with the current camera config will otherwise be silently disabled when the session is resumed by calling resume().

The following configurations are unsupported and will throw UnsupportedConfigurationException:

When using the default back-facing (world) camera:
- The Config.AugmentedFaceMode.MESH3D enum in Config.AugmentedFaceMode.
- The Config.DepthMode.AUTOMATIC enum in Config.DepthMode on devices that do not support this Depth API mode. See isDepthModeSupported(Config.DepthMode).
- The Config.GeospatialMode.ENABLED enum in Config.GeospatialMode on devices that do not support this Geospatial mode. See isGeospatialModeSupported(Config.GeospatialMode).
When using the front-facing (selfie) camera:
- Any config using Config.setAugmentedImageDatabase(AugmentedImageDatabase).
- The Config.CloudAnchorMode.ENABLED enum in Config.CloudAnchorMode.
- The Config.LightEstimationMode.ENVIRONMENTAL_HDR enum in Config.LightEstimationMode.
- The Config.DepthMode.AUTOMATIC enum in Config.DepthMode.
- The Config.GeospatialMode.ENABLED enum in Config.GeospatialMode.

Details

Parameters

config The new configuration setting for the session.

Throws

`UnsupportedConfigurationException`	if the requested session config is not supported. See above restrictions.
`GooglePlayServicesLocationLibraryNotLinkedException`	if `Config.GeospatialMode` is `Config.GeospatialMode.ENABLED` and the Google Play Services Location Library could not be found. See `GooglePlayServicesLocationLibraryNotLinkedException` for additional troubleshooting steps.
`FineLocationPermissionNotGrantedException`	if `Config.GeospatialMode` is `Config.GeospatialMode.ENABLED` and the `ACCESS_FINE_LOCATION` has not been granted.
`SecurityException`	if `Config.GeospatialMode` is `Config.GeospatialMode.ENABLED` or `Config.CloudAnchorMode` is `Config.CloudAnchorMode.ENABLED` and the Android `INTERNET` permission has not been granted.

public Anchor createAnchor (Pose pose)

createAnchor

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

Details

Parameters

pose a pose to anchor to the physical world

Throws

`SessionPausedException`	if the Session is currently paused.
`NotTrackingException`	if the Camera is not currently tracking.
`ResourceExhaustedException`	if too many resources have already been acquired.

estimateFeatureMapQualityForHosting

public Session.FeatureMapQuality estimateFeatureMapQualityForHosting(
  Pose pose
)

Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera pose.

Cloud Anchors hosted using higher quality features will generally result in easier and more accurately resolved Cloud Anchor poses.

Details

Parameters

pose The camera pose to use in estimating the quality.

Returns The estimated quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera pose.

Throws

`SessionPausedException`	if the Session is currently paused.
`NotTrackingException`	if the Session is not currently tracking.
`CloudAnchorsNotConfiguredException`	if support for Cloud Anchors has not been enabled in the Session Config.

public Collection<Anchor> getAllAnchors ()

getAllAnchors

public Collection<Anchor> getAllAnchors()

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

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

getAllTrackables

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 Frame.hitTest(float, float).

Details

Parameters

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

public CameraConfig getCameraConfig ()

getCameraConfig

public CameraConfig getCameraConfig()

Gets the current camera config used by the session.

Details
Returns	The object `CameraConfig` that contains the current camera config. If the camera config was not explicitly set using `setCameraConfig(CameraConfig)` then it returns the default camera config.

public void getConfig (Config configToFill)

getConfig

public void getConfig(
  Config configToFill
)

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

Details

Parameters

configToFill

getConfig

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 Earth getEarth ()

getEarth

public Earth getEarth()

Returns the Earth object for the session. This object is long-lived; it may be used for the entire duration of the ARCore session or until a Config with Config.GeospatialMode.DISABLED is applied on the Session.

Earth can only be obtained when a Config with Config.GeospatialMode.ENABLED has been set on this session. See Config.setGeospatialMode(GeospatialMode) to enable the Geospatial API.

Details
Returns	The `Earth` object for the session, or `null` if the session's config `Config.GeospatialMode` is set to `Config.GeospatialMode.DISABLED`.

public PlaybackStatus getPlaybackStatus ()

getPlaybackStatus

public PlaybackStatus getPlaybackStatus()

Returns the current playback status.

public RecordingStatus getRecordingStatus ()

getRecordingStatus

public RecordingStatus getRecordingStatus()

Returns the current recording status.

public SharedCamera getSharedCamera ()

getSharedCamera

public SharedCamera getSharedCamera()

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

Details

Throws

IllegalStateException if session is not created for shared camera.

public List<CameraConfig> getSupportedCameraConfigs ()

getSupportedCameraConfigs

public List<CameraConfig> getSupportedCameraConfigs()

This method was deprecated.
Please use instead: 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.

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

public List<CameraConfig> getSupportedCameraConfigs (CameraConfigFilter cameraConfigFilter)

getSupportedCameraConfigs

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 and ARCore supported cameras. Overly restrictive filtering can result in the returned list being empty on some devices.

Beginning with ARCore SDK 1.15.0, some devices support additional camera configs with lower GPU texture resolutions than the device's default GPU texture resolution. See the ARCore supported devices page for details.

Beginning with ARCore SDK 1.23.0, the list of returned camera configs will include front-facing (selfie) and back-facing (world) camera configs. In previous SDKs, returned camera configs included only front-facing (selfie) or only back-facing (world) camera configs, depending on whether the deprecated Session.Feature.FRONT_CAMERA feature was used.

In the case of a non-empty list, element 0 will contain the camera config that best matches the session feature and filter settings, according to the following priority:

Prefer CameraConfig.StereoCameraUsage.REQUIRE_AND_USE over CameraConfig.StereoCameraUsage.DO_NOT_USE
Prefer CameraConfig.TargetFps.TARGET_FPS_60 over CameraConfig.TargetFps.TARGET_FPS_30
Prefer CameraConfig.DepthSensorUsage.REQUIRE_AND_USE over CameraConfig.DepthSensorUsage.DO_NOT_USE

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

Can be called at any time.

Details

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 Anchor hostCloudAnchor (Anchor anchor)

hostCloudAnchor

public Anchor hostCloudAnchor(
  Anchor anchor
)

This method was deprecated.
Use hostCloudAnchorAsync(Anchor, int, BiConsumer) with ttlDays=1 instead.

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 Anchor.CloudAnchorState.TASK_IN_PROGRESS.

Details

Parameters

anchor The anchor whose pose is to be hosted.

Returns The new anchor with the same pose as anchor which will be hosted.

Throws

`NotTrackingException`	if the Camera is not currently tracking.
`CloudAnchorsNotConfiguredException`	if support for Cloud Anchors has not been enabled in the Session Config.
`ResourceExhaustedException`	if too many resources have already been acquired.
`SessionPausedException`	if the session is currently paused.
`AnchorNotSupportedForHostingException`	if the anchor is not supported for hosting.

public HostCloudAnchorFuture hostCloudAnchorAsync (Anchor anchor, int ttlDays, BiConsumer<String, Anchor.CloudAnchorState> callback)

hostCloudAnchorAsync

public HostCloudAnchorFuture hostCloudAnchorAsync(
  Anchor anchor,
  int ttlDays,
  BiConsumer<String, Anchor.CloudAnchorState> callback
)

Uses the pose and other data from anchor to host a new Cloud Anchor. A Cloud Anchor is assigned an identifier that can be used to create an Anchor in the same position in subsequent sessions across devices using resolveCloudAnchorAsync(String, BiConsumer). See the Cloud Anchors developer guide for more information.

The duration that a Cloud Anchor can be resolved for is specified by ttlDays. When using Keyless authorization, the maximum allowed value is 365 days. When using an API Key to authenticate with the ARCore API, the maximum allowed value is 1 day.

Cloud Anchors requires a Config with Config.CloudAnchorMode.ENABLED set on this session. Use Config.setCloudAnchorMode(Config.CloudAnchorMode) to set the Cloud Anchor API mode and configure(Config) to configure the session.

Hosting a Cloud Anchor works best when ARCore is able to create a good feature map around the Anchor. Use estimateFeatureMapQualityForHosting(Pose) to determine the quality of visual features seen by ARCore in the preceding few seconds. Cloud Anchors hosted using higher quality features will generally result in quicker and more accurately resolved Cloud Anchor poses.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See Future for information on obtaining results and cancelling the operation.

ARCore can have up to 40 simultaneous Cloud Anchor operations, including resolved anchors and active hosting operations.

Details

Parameters

`anchor`	The anchor whose pose is to be hosted.
`ttlDays`	The lifetime of the anchor in days. Must be positive.
`callback`	An optional callback, called when the operation is finished, unless the future is cancelled. May be null.

Returns A handler that can be polled or cancelled.

Throws

`IllegalArgumentException`	if the provided anchor or TTL are invalid.
`NotTrackingException`	if the Camera is not currently tracking.
`CloudAnchorsNotConfiguredException`	if the Cloud Anchors API has not been enabled in the session configuration.
`ResourceExhaustedException`	if too many resources have already been acquired.
`SessionPausedException`	if the session is currently paused.
`AnchorNotSupportedForHostingException`	if the anchor is not supported for hosting.

public Anchor hostCloudAnchorWithTtl (Anchor anchor, int ttlDays)

hostCloudAnchorWithTtl

public Anchor hostCloudAnchorWithTtl(
  Anchor anchor,
  int ttlDays
)

This method was deprecated.
Use hostCloudAnchorAsync(Anchor, int, BiConsumer) with ttlDays=1 instead.

Uses the pose and other data from anchor to create a new anchor with a given lifetime in days that will be hosted. The returned anchor will have the Cloud Anchor state Anchor.CloudAnchorState.TASK_IN_PROGRESS.

Details

Parameters

`anchor`	The anchor whose pose is to be hosted.
`ttlDays`	The lifetime of the anchor in days. Must be positive. The maximum allowed value is 1 if using an API Key to authenticate with the ARCore Cloud Anchor service, otherwise the maximum allowed value is 365.

Returns The new anchor with the same pose as anchor which will be hosted.

public boolean isDepthModeSupported (Config.DepthMode mode)

isDepthModeSupported

public boolean isDepthModeSupported(
  Config.DepthMode mode
)

Checks whether the provided Config.DepthMode is supported on this device with the selected camera configuration. The current list of supported devices is documented on the ARCore supported devices page.

Details

Parameters

mode The desired depth mode to check.

Returns true if the depth mode is supported on this device.

public boolean isGeospatialModeSupported (Config.GeospatialMode geospatialMode)

isGeospatialModeSupported

public boolean isGeospatialModeSupported(
  Config.GeospatialMode geospatialMode
)

Checks whether the provided Config.GeospatialMode is supported on this device. The current list of supported devices is documented on the ARCore supported devices page. A device may be incompatible with a given Config.GeospatialMode due to insufficient sensor capabilities.

Details

Parameters

geospatialMode The desired Geospatial mode to check.

Returns true if the given Config.GeospatialMode is supported on this device.

public boolean isImageStabilizationModeSupported (Config.ImageStabilizationMode imageStabilizationMode)

isImageStabilizationModeSupported

public boolean isImageStabilizationModeSupported(
  Config.ImageStabilizationMode imageStabilizationMode
)

Checks whether the provided Config.ImageStabilizationMode is supported on this device with the selected camera configuration. See Enabling Electronic Image Stabilization for more information.

Attempting to use configure(Config) to configure a Config.ImageStabilizationMode mode on a device that isn't supported, configure(Config) will throw UnsupportedConfigurationException.

Details

Parameters

imageStabilizationMode Desired image stabilization mode to check.

Returns true if the image stabilization mode requested is supported.

public boolean isSemanticModeSupported (Config.SemanticMode mode)

isSemanticModeSupported

public boolean isSemanticModeSupported(
  Config.SemanticMode mode
)

Checks whether the provided Config.SemanticMode is supported on this device with the selected camera configuration. The current list of supported devices is documented on the ARCore supported devices page.

Details

Parameters

mode The desired semantic mode to check.

Returns true if the semantic mode is supported on this device.

public boolean isSupported (Config config)

isSupported

public boolean isSupported(
  Config config
)

This method was deprecated.
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.

Details

Parameters

config the configuration to test

public void pause ()

pause

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)

resolveCloudAnchor

public Anchor resolveCloudAnchor(
  String cloudAnchorId
)

This method was deprecated.
Use resolveCloudAnchorAsync(String, BiConsumer) instead.

Creates a new anchor, the pose of which ARCore will try to resolve using the ARCore Cloud Anchor service and the provided cloudAnchorId. The returned anchor will have the Cloud Anchor state Anchor.CloudAnchorState.TASK_IN_PROGRESS. ARCore will try to resolve up to 40 Cloud Anchors simultaneously. ARCore will begin attempting additional Cloud Anchors once one or more of the pending resolve requests succeeds or is cancelled.

Details

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 ResolveCloudAnchorFuture resolveCloudAnchorAsync (String cloudAnchorId, BiConsumer<Anchor, Anchor.CloudAnchorState> callback)

resolveCloudAnchorAsync

public ResolveCloudAnchorFuture resolveCloudAnchorAsync(
  String cloudAnchorId,
  BiConsumer<Anchor, Anchor.CloudAnchorState> callback
)

Attempts to resolve a Cloud Anchor using the provided cloudAnchorId. The Cloud Anchor must previously have been hosted by hostCloudAnchorAsync(Anchor, int, BiConsumer) or another Cloud Anchor hosting method within the allotted ttlDays. See the Cloud Anchors developer guide for more information.

When resolving a Cloud Anchor, the ARCore API periodically compares visual features from the scene against the anchor's 3D feature map to pinpoint the user's position and orientation relative to the anchor. When it finds a match, the task completes.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See Future for information on obtaining results and cancelling the operation.

ARCore can have up to 40 simultaneous Cloud Anchor operations, including resolved anchors and active hosting operations.

Details

Parameters

`cloudAnchorId`	The Cloud Anchor ID of the Cloud Anchor.
`callback`	An optional callback, called when the operation is finished, unless the future is cancelled. May be null.

Returns A handler that can be polled or cancelled.

Throws

`IllegalArgumentException`	if the provided Cloud Anchor ID is invalid.
`CloudAnchorsNotConfiguredException`	if the Cloud Anchors API has not been enabled in the session configuration.
`ResourceExhaustedException`	if too many resources have already been acquired.
`SessionPausedException`	if the session is currently paused.

public void resume ()

resume

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 Frame.acquireCameraImage() must be released by calling Image.close() before resuming. If there are open images, resume() will throw IllegalStateException.

Details

Throws

`SessionNotPausedException`	if the session was not paused.
`CameraNotAvailableException`	if the camera isn't available yet.
`SecurityException`	if the camera permission is not granted.
`IllegalStateException`	if there are any acquired images still open.
`FatalException`	if an unrecoverable error occurs. Check the logcat for more details.

public void setCameraConfig (CameraConfig cameraConfig)

setCameraConfig

public void setCameraConfig(
  CameraConfig cameraConfig
)

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

The new camera config will be applied once the session is resumed.

The session must be paused. All previously acquired frame images must be released via Image.close() before resuming. Failure to do so will cause resume() to throw IllegalStateException.

Changing the camera config for an existing session may affect which ARCore features can be used. Unsupported session features are silently disabled when the session is resumed. Call configure(Config) after setting a camera config to verify that all configured session features are supported with the new camera config.

Changing the current session's camera config to one that uses a different camera will cause all internal session states to be reset when the session is next resumed by calling resume().

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

Details

Parameters

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

Throws

SessionNotPausedException if called when session is not paused.

public void setCameraTextureName (int textureId)

setCameraTextureName

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 GLES20.glGenTextures(int, int[], int). The resulting texture must be bound to the GLES11Ext.GL_TEXTURE_EXTERNAL_OES target for use. Shaders accessing this texture must use a samplerExternalOES sampler.

The texture contents are not guaranteed to remain valid after another call to setCameraTextureName(int) or setCameraTextureNames(int[]), and additionally are not guaranteed to remain valid after a call to pause() or close().

Details

Parameters

textureId a valid OpenGL texture name (id)

public void setCameraTextureNames (int[] textureIds)

setCameraTextureNames

public void setCameraTextureNames(
  int[] textureIds
)

Sets the OpenGL texture names (ids) that will be assigned to incoming camera frames in sequence in a ring buffer. The textures must be bound to the GLES11Ext.GL_TEXTURE_EXTERNAL_OES target for use. Shaders accessing these textures must use a samplerExternalOES sampler.

Passing multiple textures allows for a multithreaded rendering pipeline, unlike setCameraTextureName(int).

Details

Parameters

textureIds an array of valid OpenGL texture names (ids)

Throws

IllegalArgumentException if textureIds is null or empty.

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

setDisplayGeometry

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.

Details

Parameters

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

public void setPlaybackDataset (String mp4DatasetFilePath)

setPlaybackDataset

public void setPlaybackDataset(
  String mp4DatasetFilePath
)

This method was deprecated.
Please use setPlaybackDatasetUri(Uri) to play back datasets.

Sets a MP4 dataset file to play back instead of live camera feed.

Restrictions:

Can only be called while the session is paused. Playback of the MP4 dataset file will start once the session is resumed.
The MP4 dataset file must use the same camera facing direction as is configured in the session.
Due to the way session data is processed, ARCore APIs may sometimes produce different results during playback than during recording and produce different results during subsequent playback sessions. For example, the number of detected planes and other trackables, the precise timing of their detection and their pose over time may be different in subsequent playback sessions.
Once playback has started (due to the first call to resume()), pausing the session (by calling pause()) will suspend processing of all camera image frames and any other recorded sensor data in the dataset. Camera image frames and sensor frame data that is discarded in this way will not be reprocessed when the session is again resumed (by calling resume()). AR tracking for the session will generally suffer due to the gap in processed data.

When an MP4 dataset file is set:

All existing trackables (Anchor and Trackable) immediately enter tracking state TrackingState.STOPPED.
The desired focus mode Config.setFocusMode(Config.FocusMode) is ignored, and will not affect the previously recorded camera images.
The current camera configuration (CameraConfig) is immediately set to the default for the device the MP4 dataset file was recorded on.
Calls to getSupportedCameraConfigs(CameraConfigFilter) will return camera configs supported by the device the MP4 dataset file was recorded on.
Setting a previously obtained camera config to setCameraConfig(CameraConfig) will have no effect.

Throws SessionUnsupportedException when incompatible session features are specified:

Session.Feature.SHARED_CAMERA

Details

Parameters

mp4DatasetFilePath

Throws

`SessionNotPausedException`	if called when session is not paused.
`SessionUnsupportedException`	if playback is incompatible with selected features.
`PlaybackFailedException`	for other playback failures.

public void setPlaybackDatasetUri (Uri mp4DatasetUri)

setPlaybackDatasetUri

public void setPlaybackDatasetUri(
  Uri mp4DatasetUri
)

Sets a MP4 dataset to play back instead of live camera feed.

The Uri must represent a seekable resource. File descriptors opened with ContentResolver.openAssetFileDescriptor(android.net.Uri, String) must support Os.lseek(java.io.FileDescriptor, long, int).

See setPlaybackDataset(String) for additional restrictions and details.

Details

Parameters

mp4DatasetUri

Throws

`IllegalArgumentException`	if `mp4DatasetUri` does not represent a seekable resource.
`SessionNotPausedException`	if called when session is not paused.
`SessionUnsupportedException`	if playback is incompatible with selected feature.
`PlaybackFailedException`	for other playback failures.

public void startRecording (RecordingConfig recordingConfig)

startRecording

public void startRecording(
  RecordingConfig recordingConfig
)

Starts a new MP4 dataset file recording that is written to the specific filesystem path.

Existing files will be overwritten.

The MP4 video stream (VGA) bitrate is 5Mbps (40Mb per minute).

Recording introduces additional overhead and may affect app performance.

Session recordings may contain sensitive information. See documentation on Recording and Playback to learn which data is saved in a recording.

Details

Parameters

recordingConfig The RecordingConfig that defines the recording configuration.

Throws

`IllegalArgumentException`	if `recordingConfig` is null or ARCore cannot write to the configured output.
`IllegalStateException`	if recording has been started already. In this case, the existing recording continues.
`RecordingFailedException`	for other recording failures.

public void stopRecording ()

stopRecording

public void stopRecording()

Stops recording and flushes unwritten data to disk. The MP4 dataset file is ready to read after this call returns.

Recording can also be stopped automatically when pause() is called if RecordingConfig.getAutoStopOnPause() is true in RecordingConfig. Recording errors that would be thrown in stopRecording() are silently ignored in pause().

Calling this method when no recording is in progress is a no-op.

Details

Throws

RecordingFailedException if the file cannot be written and fully flushed to disk.

public Frame update ()

update

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

Details

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.