Typedefs
typedef struct ArSession_	ArSession

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

void	ArSession_destroy (ArSession *session)
	Releases resources used by an ARCore session.

ArStatus	ArSession_checkSupported (const ArSession session, const ArConfig config) AR_DEPRECATED("deprecated in release 1.2.0. Please see function documentation")

ArStatus	ArSession_configure (ArSession session, const ArConfig config)

ArStatus	ArSession_resume (ArSession *session)

ArStatus	ArSession_pause (ArSession *session)

void	ArSession_setCameraTextureName (ArSession *session, uint32_t texture_id)

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

ArStatus	ArSession_update (ArSession session, ArFrame out_frame)

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

void	ArSession_getAllAnchors (const ArSession session, ArAnchorList out_anchor_list)

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

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

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

Detailed Description

Session management.

Typedef Documentation

◆ ArSession

typedef struct ArSession_ ArSession

The ArCore session (value type).

Create with ArSession_create()
Release with ArSession_destroy()

Definition at line 164 of file arcore_c_api.h.

Function Documentation

◆ ArSession_acquireNewAnchor()

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

Defines a tracked location in the physical world.

Returns

#AR_SUCCESS or any of:

#AR_ERROR_NOT_TRACKING
#AR_ERROR_SESSION_PAUSED
#AR_ERROR_RESOURCE_EXHAUSTED

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

Parameters

[in]	session	The ARCore session
[in]	config	The configuration to test

Returns

#AR_SUCCESS or:

#AR_ERROR_INVALID_ARGUMENT if any of the arguments are null.

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

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

Returns

#AR_SUCCESS or any of:

#AR_ERROR_FATAL
#AR_ERROR_UNSUPPORTED_CONFIGURATION

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

Parameters

[in]	env	The application's `JNIEnv` object
[in]	application_context	A `jobject` referencing the application's Android `Context`
[out]	out_session_pointer	A pointer to an `ArSession*` to receive the address of the newly allocated session.

Returns

#AR_SUCCESS or any of:

#AR_UNAVAILABLE_ARCORE_NOT_INSTALLED
#AR_UNAVAILABLE_DEVICE_NOT_COMPATIBLE
#AR_UNAVAILABLE_APK_TOO_OLD
#AR_UNAVAILABLE_SDK_TOO_OLD
#AR_ERROR_CAMERA_PERMISSION_NOT_GRANTED

◆ ArSession_destroy()

void ArSession_destroy ( ArSession * session )

Releases resources used by an ARCore session.

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

Parameters

[in]	session	The ARCore session
[in,out]	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().

Parameters

[in]	session	The ARCore session
[in]	filter_type	The type(s) of trackables to return. See ::ArTrackableType for legal values.
[in,out]	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_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.

Parameters

[in]	session	The ARCore session
[in]	anchor	The anchor to be hosted
[in,out]	out_cloud_anchor	The new cloud anchor

Returns

#AR_SUCCESS or any of:

#AR_ERROR_NOT_TRACKING
#AR_ERROR_SESSION_PAUSED
#AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED
#AR_ERROR_RESOURCE_EXHAUSTED
#AR_ERROR_ANCHOR_NOT_SUPPORTED_FOR_HOSTING

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

Returns

#AR_SUCCESS or any of:

#AR_ERROR_FATAL

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

Parameters

[in]	session	The ARCore session
[in]	cloud_anchor_id	The cloud ID of the anchor to be resolved
[in,out]	out_cloud_anchor	The new cloud anchor

Returns

#AR_SUCCESS or any of:

#AR_ERROR_NOT_TRACKING
#AR_ERROR_SESSION_PAUSED
#AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED
#AR_ERROR_RESOURCE_EXHAUSTED

◆ ArSession_resume()

ArStatus ArSession_resume ( ArSession * session )

Starts or resumes the ARCore Session.

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

Returns

#AR_SUCCESS or any of:

#AR_ERROR_FATAL
#AR_ERROR_CAMERA_PERMISSION_NOT_GRANTED
#AR_ERROR_CAMERA_NOT_AVAILABLE

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

Parameters

[in]	session	The ARCore session
[in]	rotation	Display rotation specified by `android.view.Surface` constants: `ROTATION_0`, `ROTATION_90`, `ROTATION_180` and `ROTATION_270`
[in]	width	Width of the view, in pixels
[in]	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.

Parameters

[in]	session	The ARCore session
[in,out]	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

#AR_SUCCESS or any of:

#AR_ERROR_FATAL
#AR_ERROR_SESSION_PAUSED
#AR_ERROR_TEXTURE_NOT_SET
#AR_ERROR_MISSING_GL_CONTEXT
#AR_ERROR_CAMERA_NOT_AVAILABLE - camera was removed during runtime.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ArSession

Function Documentation

◆ ArSession_acquireNewAnchor()

◆ ArSession_checkSupported()

◆ ArSession_configure()

◆ ArSession_create()

◆ ArSession_destroy()

◆ ArSession_getAllAnchors()

◆ ArSession_getAllTrackables()

◆ ArSession_hostAndAcquireNewCloudAnchor()

◆ ArSession_pause()

◆ ArSession_resolveAndAcquireNewCloudAnchor()

◆ ArSession_resume()

◆ ArSession_setCameraTextureName()

◆ ArSession_setDisplayGeometry()

◆ ArSession_update()