# Session

Artifact: [androidx.xr.runtime:runtime](https://developer.android.com/jetpack/androidx/releases/xr-runtime) [View Source](https://cs.android.com/search?q=file:androidx/xr/runtime/Session.kt+class:androidx.xr.runtime.Session) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

*** ** * ** ***


```
class Session
```

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session`'s lifecycle will be scoped to the `https://developer.android.com/reference/android/app/Activity.html` that owns it.

## Summary

| ### Public companion functions |
|---|---|
| `suspend https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionCreateResult` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)( context: https://developer.android.com/reference/android/content/Context.html, coroutineContext: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html, lifecycleOwner: https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner )` Creates a new `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session`. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionConfigureResult` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#configure(androidx.xr.runtime.Config)(config: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config)` Sets or changes the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config` to use for the Session. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config` | `@https://developer.android.com/reference/kotlin/androidx/annotation/GuardedBy(value = "configurationMutex") https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#config()` The current state of the runtime configuration. |
| `https://developer.android.com/reference/android/content/Context.html` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#context()` the `https://developer.android.com/reference/android/content/Context.html` the `Session` belongs to |
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#coroutineScope()` the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html` for coroutines within the `Session` |
| `https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#lifecycleOwner()` the owner of the Android `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle` the `Session` belongs to |
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://developer.android.com/reference/kotlin/androidx/xr/runtime/CoreState>` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#state()` A `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` of the current state. |

| ### Extension properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Scene` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#(androidx.xr.runtime.Session).scene()` Gets the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/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 `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session`. If a session already exists for the given `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)`, that existing session is returned.
> **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 `https://developer.android.com/reference/android/os/StrictMode.html` `DiskReadViolation`.

**Example for calling on a worker thread:**

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

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)` provided for the session's resources |
| `coroutineContext: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html = EmptyCoroutineContext` | the `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html` that will be used to handle the session's coroutines |
| `lifecycleOwner: https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner = context as LifecycleOwner` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)` whose lifecycle controls the runtime state of the session. Defaults to using the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)` as the owner if not provided |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionCreateResult` | the result of the operation. Can be `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionCreateSuccess`, which contains the newly created session, or another `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionCreateResult` if a certain criteria was not met |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/SecurityException.html` | if the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` is backed by Google Play Services for AR and `https://developer.android.com/reference/android/Manifest.permission.html#CAMERA` has not been granted to the calling application |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if a session already exists for the given `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)` but was created with a different `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)`. |

## Public functions

### configure

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

```
fun configure(config: Config): SessionConfigureResult
```

Sets or changes the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config` to use for the Session.

The passed `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#configure(androidx.xr.runtime.Config)` will overwrite all mode values. Not all runtimes will support every mode, and the desired modes should first be queried for availability using `https://developer.android.com/reference/kotlin/androidx/xr/runtime/XrDevice` before configuring. Example: `https://developer.android.com/reference/kotlin/androidx/xr/runtime/XrDevice#isGeospatialModeSupported(androidx.xr.runtime.GeospatialMode)`.

It is recommended to modify the current `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config` to avoid unnecessarily resetting the system. This can be done using `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config.Builder` as follows:

```kotlin
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: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Config` that will be enabled if successful |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionConfigureResult` | the result of the operation. This will be a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionConfigureSuccess` if the configuration was successful, or another `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SessionConfigureResult` if a certain configuration criteria was not met. In the case of the latter, the previous `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#config()` will remain active |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the session has been destroyed |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html` | if the configuration is not supported |
| `https://developer.android.com/reference/java/lang/SecurityException.html` | if the necessary permissions have not been granted to the calling application for the provided configuration |

## Public properties

### config

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

```
@GuardedBy(value = "configurationMutex")
val config: Config
```

The current state of the runtime configuration.

### context

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

```
val context: Context
```

the `https://developer.android.com/reference/android/content/Context.html` the `Session` belongs to

### coroutineScope

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

```
val coroutineScope: CoroutineScope
```

the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html` for coroutines within the `Session`

### lifecycleOwner

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

```
val lifecycleOwner: LifecycleOwner
```

the owner of the Android `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle` the `Session` belongs to

### state

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-runtime#1.0.0)

```
val state: StateFlow<CoreState>
```

A `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` of the current state.

## Extension properties

### Session.scene

Artifact: [androidx.xr.scenecore:scenecore](https://developer.android.com/jetpack/androidx/releases/xr-scenecore) [View Source](https://cs.android.com/search?q=file:androidx/xr/scenecore/SessionExt.kt+symbol:scene) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-scenecore#1.0.0)

```
val Session.scene: Scene
```

Gets the `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/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 |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/scenecore/Scene` |   |