Session

Kotlin |Java

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. The Session's lifecycle will be scoped to the Activity that owns it.

Summary

Public methods
`final @NonNull SessionConfigureResult`	`configure(@NonNull Config config)` Sets or changes the `Config` to use for the Session.
`static final @NonNull SessionCreateResult`	`create( @NonNull Context context, @NonNull CoroutineContext coroutineContext, @NonNull LifecycleOwner lifecycleOwner )` Creates a new `Session`.
`final @NonNull Config`	`getConfig()` The current state of the runtime configuration.
`final @NonNull Context`	`getContext()` the `Context` the `Session` belongs to
`final @NonNull CoroutineScope`	`getCoroutineScope()` the `CoroutineScope` for coroutines within the `Session`
`final @NonNull LifecycleOwner`	`getLifecycleOwner()` the owner of the Android `Lifecycle` the `Session` belongs to
`final @NonNull StateFlow<@NonNull CoreState>`	`getState()` A `StateFlow` of the current state.

Extension functions
`final @NonNull Scene`	`SessionExt.getScene(@NonNull Session receiver)` Gets the `Scene` associated with this Session.

Public methods

configure

Added in 1.0.0-beta01

public final @NonNull SessionConfigureResult configure(@NonNull Config config)

Sets or changes the Config to use for the Session.

The passed config will overwrite all mode values. Not all runtimes will support every mode, and the desired modes should first be queried for availability using androidx.xr.runtime.XrDevice before configuring. Example: androidx.xr.runtime.XrDevice.isGeospatialModeSupported.

It is recommended to modify the current Config to avoid unnecessarily resetting the system. This can be done using Config.Builder as follows:

val newConfig = Config.Builder(session.config)
    .setFeature(Feature.ENABLED)
    .build()
session.configure(newConfig)

Note that enabling most configurations will increase hardware resource consumption and should only be enabled if needed.

Parameters
`@NonNull Config config`	the `Config` that will be enabled if successful.

Returns
`@NonNull SessionConfigureResult`	the result of the operation. This will be a `SessionConfigureSuccess` if the configuration was successful, or another `SessionConfigureResult` if a certain configuration criteria was not met. In the case of the latter, the previous `Session.config` will remain active.

Throws
`IllegalStateException`	if the session has been destroyed.
`UnsupportedOperationException`	if the configuration is not supported.
`SecurityException`	if the necessary permissions have not been granted to the calling application for the provided configuration.

create

public static final @NonNull SessionCreateResult create(
    @NonNull Context context,
    @NonNull CoroutineContext coroutineContext,
    @NonNull LifecycleOwner lifecycleOwner
)

Creates a new Session.

Thread Safety Warning: This method performs significant disk I/O, including loading native libraries. If StrictMode is enabled, calling this on the Main Thread (UI Thread) will trigger a android.os.StrictMode DiskReadViolation.

Example for calling on a worker thread:

lifecycleScope.launch {
    val result = withContext(Dispatchers.IO) {
        Session.create(context)
    }
}

Parameters
`@NonNull Context context`	the `context` provided for the session's resources.
`@NonNull CoroutineContext coroutineContext`	the `CoroutineContext` that will be used to handle the session's coroutines.
`@NonNull LifecycleOwner lifecycleOwner`	the `lifecycleOwner` whose lifecycle controls the runtime state of the session. Defaults to using the `context` as the owner if not provided.

Returns
`@NonNull SessionCreateResult`	the result of the operation. Can be `SessionCreateSuccess`, which contains the newly created session, or another `SessionCreateResult` if a certain criteria was not met.

Throws
`SecurityException`	if the `Session` is backed by Google Play Services for AR and `android.Manifest.permission.CAMERA` has not been granted to the calling application.

getConfig

Added in 1.0.0-beta01

public final @NonNull Config getConfig()

The current state of the runtime configuration.

getContext

Added in 1.0.0-beta01

public final @NonNull Context getContext()

the Context the Session belongs to

getCoroutineScope

Added in 1.0.0-beta01

public final @NonNull CoroutineScope getCoroutineScope()

the CoroutineScope for coroutines within the Session

getLifecycleOwner

Added in 1.0.0-beta01

public final @NonNull LifecycleOwner getLifecycleOwner()

the owner of the Android Lifecycle the Session belongs to

getState

Added in 1.0.0-beta01

public final @NonNull StateFlow<@NonNull CoreState> getState()

A StateFlow of the current state.

Extension functions

SessionExt.getScene

Artifact: androidx.xr.scenecore:scenecore

View Source

public final @NonNull Scene SessionExt.getScene(@NonNull Session receiver)

Gets the Scene associated with this Session.

Accessing the scene in a destroyed activity can be dangerous.

The Scene is the primary interface for creating and managing spatial content. There is a single Scene instance for each Session.

See also
`Scene`