public final class Session

A session is the main entrypoint to features provided by ARCore for Jetpack XR. It manages the system's state and its lifecycle, and contains the state of objects tracked by ARCore for Jetpack XR.

This class owns a significant amount of native heap memory. Apps using a Session consider its lifecycle to ensure that native resources are released when the session is no longer needed. If your activity is a single XR-enabled activity, it is recommended to call the Session object's lifecycle methods from the activity's lifecycle methods using a lifecycle-aware component. See create, resume, pause, and destroy for more details.

Summary

Public methods
final @NonNull SessionConfigureResult

Sets or changes the configuration to use.
static final @NonNull SessionCreateResult
create(
    @NonNull Activity activity,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Creates a new Session.
final void

Destroys the session, releasing any resources acquired by the session.
final @NonNull StateFlow<@NonNull CoreState>

A StateFlow of the current state.
final void

Pauses execution of the session.
final @NonNull SessionResumeResult

Starts or resumes the session.

Public methods

configure

Added in 1.0.0-alpha03
public final @NonNull SessionConfigureResult configure()

Sets or changes the configuration to use.

Returns
@NonNull SessionConfigureResult

the result of the operation. This will be a SessionConfigureSuccess if the configuration was successful, or a SessionConfigureConfigurationNotSupported if the SessionConfiguration is not supported.
Throws
kotlin.IllegalStateException

if the session has been destroyed.

create

Added in 1.0.0-alpha03
public static final @NonNull SessionCreateResult create(
    @NonNull Activity activity,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Creates a new Session.

Creating a session requires the android.permission.SCENE_UNDERSTANDING and android.permission.HAND_TRACKING permissions to be granted.

Parameters
@NonNull Activity activity

the Activity that owns the session.
@NonNull CoroutineDispatcher coroutineDispatcher

the CoroutineDispatcher that will be used to handle the session's coroutines.
Returns
@NonNull SessionCreateResult

the result of the operation. Can be SessionCreateSuccess, which contains the newly created session, or SessionCreatePermissionsNotGranted if the required permissions haven't been granted.

destroy

Added in 1.0.0-alpha03
public final void destroy()

Destroys the session, releasing any resources acquired by the session. Objects tracked by the system will not receive updates.

Calling this method on a destroyed session is a no-op. Additionally, calling this method on an active session will first call pause.

getState

Added in 1.0.0-alpha03
public final @NonNull StateFlow<@NonNull CoreState> getState()

A StateFlow of the current state.

pause

Added in 1.0.0-alpha03
public final void pause()

Pauses execution of the session. Objects tracked by the session will not receive updates. The system state will be retained in memory.

Calling this method on an inactive session is a no-op.

Throws
kotlin.IllegalStateException

if the session has been destroyed.

resume

Added in 1.0.0-alpha03
public final @NonNull SessionResumeResult resume()

Starts or resumes the session.

Resuming a session requires the android.permission.SCENE_UNDERSTANDING and android.permission.HAND_TRACKING permissions to be granted.

Returns
@NonNull SessionResumeResult

the result of the operation. Can be SessionResumeSuccess if the session was successfully resumed, or SessionResumePermissionsNotGranted if the required permissions haven't been granted.
Throws
kotlin.IllegalStateException

if the session has been destroyed.