ArSession

Feature names for use with ArSession_createWithFeatures.

All currently defined features are mutually compatible.

The ARCore session (value type).

• Create with: ArSession_create
• Release with: ArSession_destroy

Returns the ArEarth object for the session.

This object is long-lived; it should be used for the entire duration of the ARCore session or until an ArConfig with AR_GEOSPATIAL_MODE_DISABLED is applied on the ArSession.

ArEarth can only be acquired when an ArConfig with AR_GEOSPATIAL_MODE_ENABLED is active on the ArSession. See ArConfig_setGeospatialMode to enable the Geospatial API.

ArEarth must be released by calling ArTrackable_release.

Defines a tracked location in the physical world.

Before release 1.2.0: Checks if the provided configuration is usable on the this device.

If this function returns AR_ERROR_UNSUPPORTED_CONFIGURATION, calls to ArSession_configure with this configuration will fail.

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

Deprecated. Deprecated in release 1.2.0. Please refer to the release notes (release notes 1.2.0)

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. See Check VPS Availability for more details.

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

This may be called without first calling ArSession_resume or ArSession_configure, for example to present an "Enter AR" button only when VPS is available.

Your app must be properly set up to communicate with the Google Cloud ARCore API in order to obtain a result from this call.

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

The following configurations are unsupported and will return AR_ERROR_UNSUPPORTED_CONFIGURATION:

• When using the (default) back-facing camera:
  • AR_AUGMENTED_FACE_MODE_MESH3D.
  • AR_GEOSPATIAL_MODE_ENABLED on devices that do not support this Geospatial mode. See ArSession_isGeospatialModeSupported.
• When using the front-facing (selfie) camera:
  • Any config using ArConfig_setAugmentedImageDatabase.
  • AR_CLOUD_ANCHOR_MODE_ENABLED.
  • AR_LIGHT_ESTIMATION_MODE_ENVIRONMENTAL_HDR.
  • AR_GEOSPATIAL_MODE_ENABLED.
• When on an Android device with API level 26 or below:
  • AR_TEXTURE_UPDATE_MODE_EXPOSE_HARDWARE_BUFFER.

Creates a new ARCore session.

Prior to calling this function, your app must check that ARCore is installed by verifying that either:

• ArCoreApk_requestInstall or ArCoreApk_requestInstallCustom returns AR_INSTALL_STATUS_INSTALLED, or
• ArCoreApk_checkAvailability returns AR_AVAILABILITY_SUPPORTED_INSTALLED.

This check must be performed prior to creating an ArSession, otherwise ArSession creation will fail, and subsequent installation or upgrade of ARCore will require an app restart and might cause Android to kill your app.

Creates a new ARCore session requesting additional features.

Prior to calling this function, your app must check that ARCore is installed by verifying that either:

• ArCoreApk_requestInstall or ArCoreApk_requestInstallCustom returns AR_INSTALL_STATUS_INSTALLED, or
• ArCoreApk_checkAvailability returns AR_AVAILABILITY_SUPPORTED_INSTALLED.

This check must be performed prior to creating an ArSession, otherwise ArSession creation will fail, and subsequent installation or upgrade of ARCore will require an app restart and might cause Android to kill your app.

Releases resources used by an ARCore session.

This function will take several seconds to complete. To prevent blocking the main thread, call ArSession_pause on the main thread, and then call ArSession_destroy on a background thread.

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.

Returns all known anchors, including those not currently tracked.

Anchors forgotten by ARCore due to a call to ArAnchor_detach or entering the AR_TRACKING_STATE_STOPPED state will not be included.

Returns the list of all known ArTrackable objects.

This includes ArPlane objects if plane detection is enabled, as well as ArPoint objects created as a side effect of calls to ArSession_acquireNewAnchor or ArFrame_hitTest.

Gets the ArCameraConfig that the ArSession is currently using.

If the camera config was not explicitly set then it returns the default camera config. Use ArCameraConfig_destroy to release memory associated with the returned camera config once it is no longer needed.

Gets the current config.

More specifically, fills the given ArConfig object with the copy of the configuration most recently set by ArSession_configure. Note: if the session was not explicitly configured, a default configuration is returned (same as ArConfig_create).

Gets the playback status.

Returns the current recording status.

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

Can be called at any time. The provided list populated with the camera configs supported by the configured session and camera.

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 1920x1080, 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 1280x720, 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.0, the middle CPU image resolution was guaranteed to be 1280x720 on all devices.
• In ARCore SDK 1.7.0 and 1.8.0, when the session camera was a front-facing (selfie) camera, the list contained three identical camera configs.

Deprecated. Deprecated in release 1.11.0. Use ArSession_getSupportedCameraConfigsWithFilter instead.

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.

Can be called at any time.

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. These additional resolutions are only returned when the filter is not a nullptr. See the ARCore supported devices (https://developers.google.com/ar/devices) page for an up to date list of supported devices.

Beginning with ARCore SDK 1.21.0, some devices will return additional camera configs for supported stereo cameras. See the ARCore supported devices (https://developers.google.com/ar/devices) page for available camera configs by device.

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 AR_SESSION_FEATURE_FRONT_CAMERA feature was used.

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

1. Stereo camera usage: prefer AR_CAMERA_CONFIG_STEREO_CAMERA_USAGE_REQUIRE_AND_USE over AR_CAMERA_CONFIG_STEREO_CAMERA_USAGE_DO_NOT_USE
2. Target FPS: prefer AR_CAMERA_CONFIG_TARGET_FPS_60 over AR_CAMERA_CONFIG_TARGET_FPS_30
3. Depth sensor usage: prefer AR_CAMERA_CONFIG_DEPTH_SENSOR_USAGE_REQUIRE_AND_USE over AR_CAMERA_CONFIG_DEPTH_SENSOR_USAGE_DO_NOT_USE

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

This creates a new Cloud Anchor using the pose and other metadata from anchor.

If the function returns AR_SUCCESS, the cloud state of out_cloud_anchor will be set to AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS and the initial pose will be set to the pose of anchor. However, the new out_cloud_anchor is completely independent of anchor, and the poses may diverge over time. If the return value of this function is not AR_SUCCESS, then out_cloud_anchor will be set to NULL.

Deprecated. Use ArSession_hostCloudAnchorAsync with ttl_days = 1 instead.

This creates a new Cloud Anchor with a given lifetime in days, using the pose of the provided anchor.

The cloud state of the returned anchor will be set to AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS and the initial pose will be set to the pose of the provided anchor. However, the returned anchor is completely independent of the original anchor, and the two poses might diverge over time.

Hosting requires an active session for which the ArTrackingState is AR_TRACKING_STATE_TRACKING, as well as a working internet connection. ARCore will continue to retry silently in the background if it is unable to establish a connection to the ARCore Cloud Anchor service.

Deprecated. Use ArSession_hostCloudAnchorAsync with ttl_days = 1 instead.

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 ArAnchor in the same position in subsequent sessions across devices using ArSession_resolveCloudAnchorAsync. See the Cloud Anchors developer guide for more information.

The duration that a Cloud Anchor can be resolved for is specified by ttl_days. 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.

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

Cloud Anchors requires a ArConfig with AR_CLOUD_ANCHOR_MODE_ENABLED set on this session. Use ArConfig_setCloudAnchorMode to set the Cloud Anchor API mode and ArSession_configure to configure the session.

Hosting a Cloud Anchor works best when ARCore is able to create a good feature map around the ArAnchor. Use ArSession_estimateFeatureMapQualityForHosting 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.

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

Checks whether the provided ArDepthMode is supported on this device with the selected camera configuration.

The current list of supported devices is documented on the ARCore supported devices page.

Checks whether the provided ArGeospatialMode 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 ArGeospatialMode due to insufficient sensor capabilities.

Checks whether the provided ArImageStabilizationMode is supported on this device with the selected camera configuration.

See Enabling Electronic Image Stabilization for more information.

Checks whether the provided ArSemanticMode is supported on this device with the selected camera configuration.

The current list of supported devices is documented on the ARCore supported devices page.

Pause the current session.

This function will stop the camera feed and release resources. The session can be restarted again by calling ArSession_resume.

Typically this should be called from Activity.onPause() .

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

This creates a new Cloud Anchor and schedules a task to resolve the anchor's pose using the given Cloud Anchor ID.

You don't need to wait for a call to resolve a Cloud Anchor to complete before initiating another call. A session can be resolving up to 40 Cloud Anchors at a given time.

If this function returns AR_SUCCESS, the cloud state of out_cloud_anchor will be AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS, and its tracking state will be AR_TRACKING_STATE_PAUSED. This anchor will never start tracking until its pose has been successfully resolved. If the resolving task ends in an error, the tracking state will be set to AR_TRACKING_STATE_STOPPED. If the return value is not AR_SUCCESS, then out_cloud_anchor will be set to NULL.

Deprecated. Use ArSession_resolveCloudAnchorAsync instead.

Attempts to resolve a Cloud Anchor using the provided cloud_anchor_id.

The Cloud Anchor must previously have been hosted by ArSession_hostCloudAnchorAsync or another Cloud Anchor hosting method within the allotted ttl_days. See the Cloud Anchors developer guide for more information.

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

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.

Cloud Anchors requires a ArConfig with AR_CLOUD_ANCHOR_MODE_ENABLED set on this session. Use ArConfig_setCloudAnchorMode to set the Cloud Anchor API mode and ArSession_configure to configure the session.

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

Starts or resumes the ARCore Session.

Typically this should be called from Activity.onResume() .

Note that if the camera configuration has been changed by ArSession_setCameraConfig since the last call to ArSession_resume, all images previously acquired using ArFrame_acquireCameraImage must be released by calling ArImage_release before calling ArSession_resume. If there are open images, ArSession_resume will return AR_ERROR_ILLEGAL_STATE and the session will not resume.

Sets the ArCameraConfig that the ArSession should use.

Can only be called while the session is paused. The provided ArCameraConfig must be one of the configs returned by ArSession_getSupportedCameraConfigsWithFilter.

The camera config will be applied once the session is resumed. All previously acquired frame images must be released with ArImage_release before calling resume(). Failure to do so will cause resume() to return AR_ERROR_ILLEGAL_STATE error.

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

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

Sets the OpenGL texture name (ID) that will allow GPU access to the camera image.

The texture must be bound to the 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 ArSession_setCameraTextureName or ArSession_setCameraTextureNames, and additionally are not guaranteed to remain valid after a call to ArSession_pause or ArSession_destroy.

When a configuration is active using AR_TEXTURE_UPDATE_MODE_EXPOSE_HARDWARE_BUFFER, values provided to this function are ignored.

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 GL_TEXTURE_EXTERNAL_OES target for use. Shaders accessing these textures must use a samplerExternalOES sampler.

The texture contents are not guaranteed to remain valid after another call to ArSession_setCameraTextureName or ArSession_setCameraTextureNames, and additionally are not guaranteed to remain valid after a call to ArSession_pause or ArSession_destroy.

Passing multiple textures allows for a multithreaded rendering pipeline, unlike ArSession_setCameraTextureName.

Note: this function doesn't fail. If given invalid input, it logs an error without setting the texture names.

When a configuration is active using AR_TEXTURE_UPDATE_MODE_EXPOSE_HARDWARE_BUFFER, values provided to this function are ignored.

Sets the aspect ratio, coordinate scaling, and display rotation.

This data is used by UV conversion, projection matrix generation, and hit test logic.

Note: this function always returns successfully. If given invalid input, it logs a error and doesn't apply the changes.

Sets a MP4 dataset file to play back instead of using the live camera feed and IMU sensor data.

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 ArSession_resume), pausing the session (by calling ArSession_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 ArSession_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 (ArAnchor and ArTrackable) immediately enter tracking state AR_TRACKING_STATE_STOPPED.
• The desired focus mode (ArConfig_setFocusMode) is ignored, and will not affect the previously recorded camera images.
• The current camera configuration (ArCameraConfig) is immediately set to the default for the device the MP4 dataset file was recorded on.
• Calls to ArSession_getSupportedCameraConfigs will return camera configs supported by the device the MP4 dataset file was recorded on.
• Setting a previously obtained camera config to ArSession_setCameraConfig will have no effect.

Deprecated. Deprecated in release 1.26.0. Use ArRecordingConfig_setMp4DatasetUri instead.

Sets a MP4 dataset file to play back instead of using the live camera feed and IMU sensor data.

This overrides the last path set by ArSession_setPlaybackDataset. The URI must point to a resource that supports lseek. See ArSession_setPlaybackDataset for more restrictions and details.

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.

Stops recording and flushes unwritten data to disk.

The MP4 dataset file will be ready to read after this call.

Recording can be stopped automatically when ArSession_pause is called, if auto stop is enabled via ArRecordingConfig_setAutoStopOnPause. Recording errors that would be thrown in stopRecording() are silently ignored in ArSession_pause.

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

ArSession_update in blocking mode (see ArUpdateMode) 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 ArSession_update will return the most recent ArFrame 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 ArFrame_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.