# 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)

*** ** * ** ***


```
public final 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/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 methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/SessionConfigureResult` | `https://developer.android.com/reference/androidx/xr/runtime/Session#configure(androidx.xr.runtime.Config)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Config config)` Sets or changes the `https://developer.android.com/reference/androidx/xr/runtime/Config` to use for the Session. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/SessionCreateResult` | `https://developer.android.com/reference/androidx/xr/runtime/Session#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html context, @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html coroutineContext, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LifecycleOwner lifecycleOwner )` Creates a new `https://developer.android.com/reference/androidx/xr/runtime/Session`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Config` | `https://developer.android.com/reference/androidx/xr/runtime/Session#getConfig()()` The current state of the runtime configuration. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html` | `https://developer.android.com/reference/androidx/xr/runtime/Session#getContext()()` the `https://developer.android.com/reference/android/content/Context.html` the `Session` belongs to |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html` | `https://developer.android.com/reference/androidx/xr/runtime/Session#getCoroutineScope()()` the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html` for coroutines within the `Session` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LifecycleOwner` | `https://developer.android.com/reference/androidx/xr/runtime/Session#getLifecycleOwner()()` the owner of the Android `https://developer.android.com/reference/androidx/lifecycle/Lifecycle` the `Session` belongs to |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/CoreState>` | `https://developer.android.com/reference/androidx/xr/runtime/Session#getState()()` A `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` of the current state. |

| ### Extension functions |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/scenecore/Scene` | `https://developer.android.com/reference/androidx/xr/runtime/SessionExt.https://developer.android.com/reference/androidx/xr/runtime/Session#(androidx.xr.runtime.Session).getScene()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session receiver)` Gets the `https://developer.android.com/reference/androidx/xr/scenecore/Scene` associated with this Session. |

## Public methods

### configure

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

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

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

The passed `https://developer.android.com/reference/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/androidx/xr/runtime/XrDevice` before configuring. Example: `https://developer.android.com/reference/androidx/xr/runtime/XrDevice#isGeospatialModeSupported(androidx.xr.runtime.GeospatialMode)`.

It is recommended to modify the current `https://developer.android.com/reference/androidx/xr/runtime/Config` to avoid unnecessarily resetting the system. This can be done using `https://developer.android.com/reference/androidx/xr/runtime/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Config config` | the `https://developer.android.com/reference/androidx/xr/runtime/Config` that will be enabled if successful |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/SessionConfigureResult` | the result of the operation. This will be a `https://developer.android.com/reference/androidx/xr/runtime/SessionConfigureSuccess` if the configuration was successful, or another `https://developer.android.com/reference/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/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 |

### create

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

Creates a new `https://developer.android.com/reference/androidx/xr/runtime/Session`. If a session already exists for the given `https://developer.android.com/reference/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:**

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html context` | the `https://developer.android.com/reference/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)` provided for the session's resources |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html coroutineContext` | the `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html` that will be used to handle the session's coroutines |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LifecycleOwner lifecycleOwner` | the `https://developer.android.com/reference/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/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/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/SessionCreateResult` | the result of the operation. Can be `https://developer.android.com/reference/androidx/xr/runtime/SessionCreateSuccess`, which contains the newly created session, or another `https://developer.android.com/reference/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/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/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/androidx/xr/runtime/Session.Companion#create(android.content.Context,kotlin.coroutines.CoroutineContext,androidx.lifecycle.LifecycleOwner)`. |

### getConfig

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

```
public final @NonNull Config getConfig()
```

The current state of the runtime configuration.

### getContext

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

```
public final @NonNull Context getContext()
```

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

### getCoroutineScope

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

```
public final @NonNull CoroutineScope getCoroutineScope()
```

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

### getLifecycleOwner

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

```
public final @NonNull LifecycleOwner getLifecycleOwner()
```

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

### getState

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

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

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

## Extension functions

### SessionExt.getScene

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)

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

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