Session

Session management.

Summary

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 *application_context, ArSession **out_session_pointer)
Attempts to create a new ARCore session.
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
Enumerates the list of supported camera configs on the device.
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.

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.

Details
Returns

ArSession_create

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

Attempts to create a new ARCore session.

This is the entry point of ARCore. This function MUST be the first ARCore call made by an application.

Details
Parameters
env
The application's JNIEnv object
application_context
A jobject referencing the application's Android Context
out_session_pointer
A pointer to an ArSession* to receive the address of the newly allocated session.
Returns

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
)

Enumerates the list of supported camera configs on the device.

Can be called at any time. The supported camera configs will be filled in the provided list after clearing it.

The list will always return 3 camera configs. The GPU texture resolutions are the same in all three configs. Currently, most devices provide GPU texture resolution of 1920 x 1080, but devices might provide higher or lower resolution textures, depending on device capabilities. The CPU image resolutions returned are VGA, 720p, and a resolution matching the GPU texture.

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

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.

Details
Parameters
session
The ARCore session
camera_config
The provided ArCameraConfig must be from a list returned by ArSession_getSupportedCameraConfigs.
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.

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

Send feedback about...