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 companion functions
suspend SessionCreateResult
create(
    context: Context,
    coroutineContext: CoroutineContext,
    lifecycleOwner: LifecycleOwner
)

Creates a new Session.

Public functions
SessionConfigureResult
configure(config: Config)

Sets or changes the Config to use for the Session.

Public properties
Config
@GuardedBy(value = "configurationMutex")
config

The current state of the runtime configuration.
Context

the Context the Session belongs to
CoroutineScope

the CoroutineScope for coroutines within the Session
LifecycleOwner

the owner of the Android Lifecycle the Session belongs to
StateFlow<CoreState>

A StateFlow of the current state.

Extension properties
Scene

Gets the Scene associated with this Session.

Public companion functions

create

suspend fun create(
    context: Context,
    coroutineContext: CoroutineContext = EmptyCoroutineContext,
    lifecycleOwner: LifecycleOwner = context as LifecycleOwner
): SessionCreateResult

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
context: Context

the context provided for the session's resources.
coroutineContext: CoroutineContext = EmptyCoroutineContext

the CoroutineContext that will be used to handle the session's coroutines.
lifecycleOwner: LifecycleOwner = context as LifecycleOwner

the lifecycleOwner whose lifecycle controls the runtime state of the session. Defaults to using the context as the owner if not provided.
Returns
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.

Public functions

configure

Added in 1.0.0-beta01
fun configure(config: Config): SessionConfigureResult

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
config: Config

the Config that will be enabled if successful.
Returns
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.

Public properties

config

Added in 1.0.0-beta01
@GuardedBy(value = "configurationMutex")
val config: Config

The current state of the runtime configuration.

context

Added in 1.0.0-beta01
val context: Context

the Context the Session belongs to

coroutineScope

Added in 1.0.0-beta01
val coroutineScope: CoroutineScope

the CoroutineScope for coroutines within the Session

lifecycleOwner

Added in 1.0.0-beta01
val lifecycleOwner: LifecycleOwner

the owner of the Android Lifecycle the Session belongs to

state

Added in 1.0.0-beta01
val state: StateFlow<CoreState>

A StateFlow of the current state.

Extension properties

Session.scene

val Session.scene: Scene

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