ArSession

Session management.

Summary

Enumerations
ArSessionFeature{
  AR_SESSION_FEATURE_END_OF_LIST = 0,
  AR_SESSION_FEATURE_FRONT_CAMERA = 1
} 		enum
Feature names for use with ArSession_createWithFeatures.

Typedefs
ArSession typedef
struct ArSession_
The ARCore session (value type).

Functions
ArSession_acquireEarth(const ArSession *session, ArEarth **out_earth)
void
Returns the ArEarth object for the session.
ArSession_acquireNewAnchor(ArSession *session, const ArPose *pose, ArAnchor **out_anchor)
Defines a tracked location in the physical world.
ArSession_checkSupported(const ArSession *session, const ArConfig *config) Deprecated. Deprecated in release 1.2.0. Please refer to the release notes (release notes 1.2.0)
Before release 1.2.0: Checks if the provided configuration is usable on the this device.
ArSession_checkVpsAvailabilityAsync(ArSession *session, double latitude_degrees, double longitude_degrees, void *context, ArVpsAvailabilityCallback callback, ArVpsAvailabilityFuture **out_future)
Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position.
ArSession_configure(ArSession *session, const ArConfig *config)
Configures the session and verifies that the enabled features in the specified session config are supported with the currently set camera config.
ArSession_create(void *env, void *context, ArSession **out_session_pointer)
Creates a new ARCore session.
ArSession_createWithFeatures(void *env, void *context, const ArSessionFeature *features, ArSession **out_session_pointer)
Creates a new ARCore session requesting additional features.
ArSession_destroy(ArSession *session)
void
Releases resources used by an ARCore session.
ArSession_estimateFeatureMapQualityForHosting(const ArSession *session, const ArPose *pose, ArFeatureMapQuality *out_feature_map_quality)
Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera pose.
ArSession_getAllAnchors(const ArSession *session, ArAnchorList *out_anchor_list)
void
Returns all known anchors, including those not currently tracked.
ArSession_getAllTrackables(const ArSession *session, ArTrackableType filter_type, ArTrackableList *out_trackable_list)
void
Returns the list of all known ArTrackable objects.
ArSession_getCameraConfig(const ArSession *session, ArCameraConfig *out_camera_config)
void
Gets the ArCameraConfig that the ArSession is currently using.
ArSession_getConfig(ArSession *session, ArConfig *out_config)
void
Gets the current config.
ArSession_getPlaybackStatus(ArSession *session, ArPlaybackStatus *out_playback_status)
void
Gets the playback status.
ArSession_getRecordingStatus(ArSession *session, ArRecordingStatus *out_recording_status)
void
Returns the current recording status.
ArSession_getSupportedCameraConfigs(const ArSession *session, ArCameraConfigList *list)
void
Deprecated. Deprecated in release 1.11.0. Use ArSession_getSupportedCameraConfigsWithFilter instead.
Gets a list of camera configs supported by the camera being used by the session.
ArSession_getSupportedCameraConfigsWithFilter(const ArSession *session, const ArCameraConfigFilter *filter, ArCameraConfigList *list)
void
Gets the list of supported camera configs that satisfy the provided filter settings.
ArSession_hostAndAcquireNewCloudAnchor(ArSession *session, const ArAnchor *anchor, ArAnchor **out_cloud_anchor) Deprecated. Use ArSession_hostCloudAnchorAsync with ttl_days = 1 instead.
This creates a new Cloud Anchor using the pose and other metadata from anchor.
ArSession_hostAndAcquireNewCloudAnchorWithTtl(ArSession *session, const ArAnchor *anchor, int32_t ttl_days, ArAnchor **out_cloud_anchor) 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.
ArSession_hostCloudAnchorAsync(ArSession *session, const ArAnchor *anchor, int32_t ttl_days, void *context, ArHostCloudAnchorCallback callback, ArHostCloudAnchorFuture **out_future)
Uses the pose and other data from anchor to host a new Cloud Anchor.
ArSession_isDepthModeSupported(const ArSession *session, ArDepthMode depth_mode, int32_t *out_is_supported)
void
Checks whether the provided ArDepthMode is supported on this device with the selected camera configuration.
ArSession_isGeospatialModeSupported(const ArSession *session, ArGeospatialMode geospatial_mode, int32_t *out_is_supported)
void
Checks whether the provided ArGeospatialMode is supported on this device.
ArSession_isImageStabilizationModeSupported(const ArSession *session, ArImageStabilizationMode image_stabilization_mode, int32_t *out_is_supported)
void
Checks whether the provided ArImageStabilizationMode is supported on this device with the selected camera configuration.
ArSession_isSemanticModeSupported(const ArSession *session, ArSemanticMode semantic_mode, int32_t *out_is_supported)
void
Checks whether the provided ArSemanticMode is supported on this device with the selected camera configuration.
ArSession_pause(ArSession *session)
Pause the current session.
ArSession_resolveAndAcquireNewCloudAnchor(ArSession *session, const char *cloud_anchor_id, ArAnchor **out_cloud_anchor) Deprecated. Use ArSession_resolveCloudAnchorAsync instead.
This creates a new Cloud Anchor and schedules a task to resolve the anchor's pose using the given Cloud Anchor ID.
ArSession_resolveCloudAnchorAsync(ArSession *session, const char *cloud_anchor_id, void *context, ArResolveCloudAnchorCallback callback, ArResolveCloudAnchorFuture **out_future)
Attempts to resolve a Cloud Anchor using the provided cloud_anchor_id.
ArSession_resume(ArSession *session)
Starts or resumes the ARCore Session.
ArSession_setCameraConfig(const ArSession *session, const ArCameraConfig *camera_config)
Sets the ArCameraConfig that the ArSession should use.
ArSession_setCameraTextureName(ArSession *session, uint32_t texture_id)
void
Sets the OpenGL texture name (ID) that will allow GPU access to the camera image.
ArSession_setCameraTextureNames(ArSession *session, int32_t number_of_textures, const uint32_t *texture_ids)
void
Sets the OpenGL texture names (IDs) that will be assigned to incoming camera frames in sequence in a ring buffer.
ArSession_setDisplayGeometry(ArSession *session, int32_t rotation, int32_t width, int32_t height)
void
Sets the aspect ratio, coordinate scaling, and display rotation.
ArSession_setPlaybackDataset(ArSession *session, const char *mp4_dataset_file_path) 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.
ArSession_setPlaybackDatasetUri(ArSession *session, const char *mp4_dataset_uri)
Sets a MP4 dataset file to play back instead of using the live camera feed and IMU sensor data.
ArSession_startRecording(ArSession *session, const ArRecordingConfig *recording_config)
Starts a new MP4 dataset file recording that is written to the specific filesystem path.
ArSession_stopRecording(ArSession *session)
Stops recording and flushes unwritten data to disk.
ArSession_update(ArSession *session, ArFrame *out_frame)
Updates the state of the ARCore system.

Enumerations

ArSessionFeature

 ArSessionFeature

Feature names for use with ArSession_createWithFeatures.

All currently defined features are mutually compatible.

Properties
AR_SESSION_FEATURE_END_OF_LIST

Indicates the end of a features list.

This must be the last entry in the array passed to ArSession_createWithFeatures.

AR_SESSION_FEATURE_FRONT_CAMERA

Use the front-facing (selfie) camera.

When the front camera is selected, ARCore's behavior changes in the following ways:

Deprecated. To create a session using the front-facing (selfie) camera, use ArSession_setCameraConfig with the desired config retrieved from ArSession_getSupportedCameraConfigsWithFilter.

Typedefs

ArSession

struct ArSession_ ArSession

The ARCore session (value type).

Functions

ArSession_acquireEarth

void ArSession_acquireEarth(
  const ArSession *session,
  ArEarth **out_earth
)

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.

Details
Parameters
session
The ARCore session.
out_earth
Pointer to ArEarth to receive the earth object, or NULL if the session's config ArGeospatialMode is set to AR_GEOSPATIAL_MODE_DISABLED.

ArSession_acquireNewAnchor

ArStatus ArSession_acquireNewAnchor(
  ArSession *session,
  const ArPose *pose,
  ArAnchor **out_anchor
)

Defines a tracked location in the physical world.

Details
Returns

ArSession_checkSupported

ArStatus ArSession_checkSupported(
  const ArSession *session,
  const ArConfig *config
)

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)

Details
Parameters
session
The ARCore session
config
The configuration to test
Returns
AR_SUCCESS or:

ArSession_checkVpsAvailabilityAsync

ArStatus ArSession_checkVpsAvailabilityAsync(
  ArSession *session,
  double latitude_degrees,
  double longitude_degrees,
  void *context,
  ArVpsAvailabilityCallback callback,
  ArVpsAvailabilityFuture **out_future
)

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.

Details
Parameters
session
The ARCore session.
latitude_degrees
The latitude to query, in degrees.
longitude_degrees
The longitude to query, in degrees.
context
An optional void pointer passed when using a callback.
callback
out_future
An optional ArFuture which can be polled.
Returns
AR_SUCCESS, or any of:

ArSession_configure

ArStatus ArSession_configure(
  ArSession *session,
  const ArConfig *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 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:

Details
Parameters
session
The ARCore session.
config
The new configuration setting for the session.
Returns
AR_SUCCESS or any of:

ArSession_create

ArStatus ArSession_create(
  void *env,
  void *context,
  ArSession **out_session_pointer
)

Creates a new ARCore session.

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

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.

Details
Parameters
env
The application's JNIEnv object
context
A JObject for an Android Context
out_session_pointer
A pointer to an ArSession* to receive the address of the newly allocated session.
Returns
AR_SUCCESS or any of:

ArSession_createWithFeatures

ArStatus ArSession_createWithFeatures(
  void *env,
  void *context,
  const ArSessionFeature *features,
  ArSession **out_session_pointer
)

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:

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.

Details
Parameters
env
The application's JNIEnv object
context
A JObject for an Android Context
features
The list of requested features, terminated by with AR_SESSION_FEATURE_END_OF_LIST.
out_session_pointer
A pointer to an ArSession* to receive the address of the newly allocated session.
Returns
AR_SUCCESS or any of:

ArSession_destroy

void ArSession_destroy(
  ArSession *session
)

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.

ArSession_estimateFeatureMapQualityForHosting

ArStatus ArSession_estimateFeatureMapQualityForHosting(
  const ArSession *session,
  const ArPose *pose,
  ArFeatureMapQuality *out_feature_map_quality
)

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
session
The ARCore session.
pose
The camera pose to use in estimating the quality.
out_feature_map_quality
The estimated quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera pose.
Returns

ArSession_getAllAnchors

void ArSession_getAllAnchors(
  const ArSession *session,
  ArAnchorList *out_anchor_list
)

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.

Details
Parameters
session
The ARCore session
out_anchor_list
The list to fill. This list must have already been allocated with ArAnchorList_create. If previously used, the list will first be cleared.

ArSession_getAllTrackables

void ArSession_getAllTrackables(
  const ArSession *session,
  ArTrackableType filter_type,
  ArTrackableList *out_trackable_list
)

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.

Details
Parameters
session
The ARCore session
filter_type
The type(s) of trackables to return. See ArTrackableType for legal values.
out_trackable_list
The list to fill. This list must have already been allocated with ArTrackableList_create. If previously used, the list will first be cleared.

ArSession_getCameraConfig

void ArSession_getCameraConfig(
  const ArSession *session,
  ArCameraConfig *out_camera_config
)

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.

Details
Parameters
session
The ARCore session
out_camera_config
The camera config object to fill. This object must have already been allocated with ArCameraConfig_create. Use ArCameraConfig_destroy to release memory associated with out_camera_config once it is no longer needed.

ArSession_getConfig

void ArSession_getConfig(
  ArSession *session,
  ArConfig *out_config
)

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

ArSession_getPlaybackStatus

void ArSession_getPlaybackStatus(
  ArSession *session,
  ArPlaybackStatus *out_playback_status
)

Gets the playback status.

Details
Parameters
session
The ARCore session.
out_playback_status
The current playback status.

ArSession_getRecordingStatus

void ArSession_getRecordingStatus(
  ArSession *session,
  ArRecordingStatus *out_recording_status
)

Returns the current recording status.

Details
Parameters
session
The ARCore session.
out_recording_status
The current recording status.

ArSession_getSupportedCameraConfigs

void ArSession_getSupportedCameraConfigs(
  const ArSession *session,
  ArCameraConfigList *list
)

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.

Details
Parameters
session
The ARCore session
list
The list to fill. This list must have already been allocated with ArCameraConfigList_create. The list is cleared to remove any existing elements. Once it is no longer needed, the list must be destroyed using ArCameraConfigList_destroy to release allocated memory.

ArSession_getSupportedCameraConfigsWithFilter

void ArSession_getSupportedCameraConfigsWithFilter(
  const ArSession *session,
  const ArCameraConfigFilter *filter,
  ArCameraConfigList *list
)

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.

Details
Returns
list of supported camera configs.

ArSession_hostAndAcquireNewCloudAnchor

ArStatus ArSession_hostAndAcquireNewCloudAnchor(
  ArSession *session,
  const ArAnchor *anchor,
  ArAnchor **out_cloud_anchor
)

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.

Details
Parameters
session
The ARCore session
anchor
The anchor to be hosted
out_cloud_anchor
The new Cloud Anchor
Returns

ArSession_hostAndAcquireNewCloudAnchorWithTtl

ArStatus ArSession_hostAndAcquireNewCloudAnchorWithTtl(
  ArSession *session,
  const ArAnchor *anchor,
  int32_t ttl_days,
  ArAnchor **out_cloud_anchor
)

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.

Details
Parameters
session
The ARCore session.
anchor
The anchor with the desired pose to be used to create a hosted Cloud Anchor.
ttl_days
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.
out_cloud_anchor
The new Cloud Anchor.
Returns

ArSession_hostCloudAnchorAsync

ArStatus ArSession_hostCloudAnchorAsync(
  ArSession *session,
  const ArAnchor *anchor,
  int32_t ttl_days,
  void *context,
  ArHostCloudAnchorCallback callback,
  ArHostCloudAnchorFuture **out_future
)

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.

Details
Parameters
session
The ARCore session.
anchor
The anchor with the desired pose to be used to host a Cloud Anchor.
ttl_days
The lifetime of the anchor in days. Must be positive.
context
An optional void pointer passed when using a callback.
callback
out_future
An optional ArFuture which can be polled.
Returns
AR_SUCCESS or any of:

ArSession_isDepthModeSupported

void ArSession_isDepthModeSupported(
  const ArSession *session,
  ArDepthMode depth_mode,
  int32_t *out_is_supported
)

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.

Details
Parameters
session
The ARCore session.
depth_mode
The desired depth mode to check.
out_is_supported
Non zero if the depth mode is supported on this device.

ArSession_isGeospatialModeSupported

void ArSession_isGeospatialModeSupported(
  const ArSession *session,
  ArGeospatialMode geospatial_mode,
  int32_t *out_is_supported
)

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.

Details
Parameters
session
The ARCore session.
geospatial_mode
The desired geospatial mode to check.
out_is_supported
Non-zero if the ArGeospatialMode is supported on this device.

ArSession_isImageStabilizationModeSupported

void ArSession_isImageStabilizationModeSupported(
  const ArSession *session,
  ArImageStabilizationMode image_stabilization_mode,
  int32_t *out_is_supported
)

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

See Enabling Electronic Image Stabilization for more information.

Details
Parameters
session
The ARCore session.
image_stabilization_mode
The desired image stabilization mode to check.
out_is_supported
Non zero if given ArImageStabilizationMode is supported on this device.

ArSession_isSemanticModeSupported

void ArSession_isSemanticModeSupported(
  const ArSession *session,
  ArSemanticMode semantic_mode,
  int32_t *out_is_supported
)

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.

Details
Parameters
session
The ARCore session.
semantic_mode
The desired semantic mode to check.
out_is_supported
Non zero if the semantic mode is supported on this device.

ArSession_pause

ArStatus ArSession_pause(
  ArSession *session
)

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.

Details
Returns

ArSession_resolveAndAcquireNewCloudAnchor

ArStatus ArSession_resolveAndAcquireNewCloudAnchor(
  ArSession *session,
  const char *cloud_anchor_id,
  ArAnchor **out_cloud_anchor
)

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.

Details
Parameters
session
The ARCore session
cloud_anchor_id
The cloud ID of the anchor to be resolved
out_cloud_anchor
The new Cloud Anchor
Returns

ArSession_resolveCloudAnchorAsync

ArStatus ArSession_resolveCloudAnchorAsync(
  ArSession *session,
  const char *cloud_anchor_id,
  void *context,
  ArResolveCloudAnchorCallback callback,
  ArResolveCloudAnchorFuture **out_future
)

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.

Details
Parameters
session
The ARCore session
cloud_anchor_id
The cloud ID of the anchor to be resolved.
context
An optional void pointer passed when using a callback.
callback
out_future
An optional ArFuture which can be polled.
Returns

ArSession_resume

ArStatus ArSession_resume(
  ArSession *session
)

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.

Details
Returns

ArSession_setCameraConfig

ArStatus ArSession_setCameraConfig(
  const ArSession *session,
  const ArCameraConfig *camera_config
)

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.

Details
Parameters
session
The ARCore session
camera_config
The provided ArCameraConfig must be from a list returned by ArSession_getSupportedCameraConfigsWithFilter.
Returns

ArSession_setCameraTextureName

void ArSession_setCameraTextureName(
  ArSession *session,
  uint32_t texture_id
)

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.

ArSession_setCameraTextureNames

void ArSession_setCameraTextureNames(
  ArSession *session,
  int32_t number_of_textures,
  const uint32_t *texture_ids
)

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.

Details
Parameters
session
The ARCore session
number_of_textures
The number of textures being passed. This must always be at least 1.
texture_ids
Pointer to the array of textures names (IDs)

ArSession_setDisplayGeometry

void ArSession_setDisplayGeometry(
  ArSession *session,
  int32_t rotation,
  int32_t width,
  int32_t height
)

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.

Details
Parameters
session
The ARCore session
rotation
Display rotation specified by android.view.Surface constants: ROTATION_0, ROTATION_90, ROTATION_180 and ROTATION_270
width
Width of the view, in pixels
height
Height of the view, in pixels

ArSession_setPlaybackDataset

ArStatus ArSession_setPlaybackDataset(
  ArSession *session,
  const char *mp4_dataset_file_path
)

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:

Deprecated. Deprecated in release 1.26.0. Use ArRecordingConfig_setMp4DatasetUri instead.

Details
Parameters
session
The ARCore session
mp4_dataset_file_path
A string file path to a MP4 dataset file or NULL to use the live camera feed.
Returns
AR_SUCCESS or any of:

ArSession_setPlaybackDatasetUri

ArStatus ArSession_setPlaybackDatasetUri(
  ArSession *session,
  const char *mp4_dataset_uri
)

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.

Details
Parameters
session
The ARCore session
mp4_dataset_uri
The percent encoded, null terminated URI for the dataset
Returns
AR_SUCCESS or any of:

ArSession_startRecording

ArStatus ArSession_startRecording(
  ArSession *session,
  const ArRecordingConfig *recording_config
)

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
session
The ARCore session
recording_config
The configuration defined for recording.
Returns

ArSession_stopRecording

ArStatus ArSession_stopRecording(
  ArSession *session
)

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.

Details
Parameters
session
The ARCore session
Returns

ArSession_update

ArStatus ArSession_update(
  ArSession *session,
  ArFrame *out_frame
)

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.

Details
Parameters
session
The ARCore session
out_frame
The Frame object to populate with the updated world state. This frame must have been previously created using ArFrame_create. The same ArFrame instance may be used when calling this repeatedly.
Returns