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_getConfig(ArSession *session, ArConfig *out_config)
void
Gets the current config.
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_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_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_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() .

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