Session

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_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. 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_configure(ArSession *session, const ArConfig *config)
Configures the session with the given 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_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 trackables.
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_getSupportedCameraConfigs(const ArSession *session, ArCameraConfigList *list)
void
Deprecated. in release 1.11.0. Please use instead:
void ArSession_getSupportedCameraConfigsWithFilter(const ArSession* session,
const ArCameraConfigFilter* filter, ArCameraConfigList* list); 
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
Enumerates the list of supported camera configs that satisfy the provided filter settings.
ArSession_hostAndAcquireNewCloudAnchor(ArSession *session, const ArAnchor *anchor, ArAnchor **out_cloud_anchor)
This will create a new cloud anchor using pose and other metadata from anchor.
ArSession_pause(ArSession *session)
Pause the current session.
ArSession_resolveAndAcquireNewCloudAnchor(ArSession *session, const char *cloud_anchor_id, ArAnchor **out_cloud_anchor)
This will create a new cloud anchor, and schedule a resolving task to resolve the anchor's pose using the given 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_setDisplayGeometry(ArSession *session, int32_t rotation, int32_t width, int32_t height)
void
Sets the aspect ratio, coordinate scaling, and display rotation.
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:

Typedefs

ArSession

struct ArSession_ ArSession

The ARCore session (value type).

Create with ArSession_create()
Release with ArSession_destroy()

Functions

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 method returns AR_ERROR_UNSUPPORTED_CONFIGURATION, calls to ArSession_configure(Config) 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. 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_configure

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

Configures the session with the given config.

Note: a session is always initially configured with the default config. This should be called if a configuration different than default is needed.

The following configurations are not supported:

Details
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 method 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_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 trackables.

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

Deprecated. in release 1.11.0. Please use instead:

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

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
)

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

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

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

  1. Prefer AR_CAMERA_CONFIG_TARGET_FPS_60 over AR_CAMERA_CONFIG_TARGET_FPS_30
  2. 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.

Can be called at any time.

Details
Returns
list of supported camera configs.

ArSession_hostAndAcquireNewCloudAnchor

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

This will create a new cloud anchor using 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.

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

ArSession_pause

ArStatus ArSession_pause(
  ArSession *session
)

Pause the current session.

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

Details
Returns

ArSession_resolveAndAcquireNewCloudAnchor

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

This will create a new cloud anchor, and schedule a resolving task to resolve the anchor's pose using the given cloud anchor ID.

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.

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_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 via ArImage_release before calling resume(). Failure to do so will cause resume() to return AR_ERROR_ILLEGAL_STATE error.

Starting in ARCore 1.12, changing the active camera config will make existing anchors and trackables fail to regain tracking.

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 provided ID should have been created with glGenTextures(). The resulting texture must be bound to the GL_TEXTURE_EXTERNAL_OES target for use. Shaders accessing this texture must use a samplerExternalOES sampler. See sample code for an example.

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 doesn't fail. 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_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().

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