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

Sets or changes the Config to use for the Session.
static final @NonNull SessionCreateResult
create(
    @NonNull Activity activity,
    @NonNull CoroutineContext coroutineContext
)

Creates a new Session.
static final @NonNull SessionCreateResult
create(
    @NonNull Activity activity,
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull CoroutineContext coroutineContext
)

Creates a new Session with a provided LifecycleOwner.
final @NonNull Config

The current state of the runtime configuration.
final @NonNull StateFlow<@NonNull CoreState>

A StateFlow of the current state.

Extension functions
final @NonNull Flowable<@NonNull CoreState>

A Flowable of the current CoreState.
final @NonNull Scene

Gets the Scene associated with this Session.

Public methods

configure

Added in 1.0.0-alpha09
public final @NonNull SessionConfigureResult configure(@NonNull Config config)

Sets or changes the Config to use for the Session.

The passed config will overwrite all ConfigMode values. Not all runtimes will support every ConfigMode, and the desired modes should first be queried for availability using ConfigMode.isSupported before configuring.

It is recommended to use and modify the Config.copy of the current Session.config to maintain the current configuration state aside from the desired changes.

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
kotlin.IllegalStateException

if the session has been destroyed.
kotlin.UnsupportedOperationException

if the configuration is not supported.
java.lang.SecurityException

if the necessary permissions have not been granted to the calling application for the provided configuration.

create

Added in 1.0.0-alpha09
public static final @NonNull SessionCreateResult create(
    @NonNull Activity activity,
    @NonNull CoroutineContext coroutineContext
)

Creates a new Session.

import androidx.activity.result.ActivityResultLauncher
import androidx.activity.result.contract.ActivityResultContracts
import androidx.xr.runtime.Config
import androidx.xr.runtime.Session
import androidx.xr.runtime.SessionConfigureCalibrationRequired
import androidx.xr.runtime.SessionConfigureSuccess
import androidx.xr.runtime.SessionCreateApkRequired
import androidx.xr.runtime.SessionCreateSuccess
import androidx.xr.runtime.SessionCreateUnsupportedDevice

val permissionLauncher: ActivityResultLauncher<Array<String>> =
    activity.registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) {
        permissions ->
        val allPermissionsGranted = permissions.all { it.value }
        if (!allPermissionsGranted) {
            Toast.makeText(
                    activity,
                    "Required permissions were not granted, closing activity. ",
                    Toast.LENGTH_LONG,
                )
                .show()
            activity.finish()
        } else {
            activity.recreate()
        }
    }

val config = generateConfig()

try {
    // First, we need to create the session.
    when (val result = Session.create(activity)) {
        // Having successfully created the session, we now need to configure it.
        is SessionCreateSuccess -> {
            val session = result.session
            try {
                when (val configResult = session.configure(config)) {
                    is SessionConfigureCalibrationRequired -> {
                        // Certain runtimes require user calibration in order to operate
                        // effectively.
                        // Either launch the calibration activity, or inform the user they must
                        // do so.
                        handleSessionCalibration(configResult.calibrationType)
                    }
                    is SessionConfigureSuccess -> {
                        // Our Session was successfully configured, so now we can continue
                        // initializing the rest of our application.
                        handleConfiguredSession(session)
                    }
                    else -> {
                        Toast.makeText(
                                activity,
                                "Unexpected session configuration result, closing activity. ",
                                Toast.LENGTH_LONG,
                            )
                            .show()
                        activity.finish()
                    }
                }
            } catch (e: SecurityException) {
                // Session configuration failed due to missing permission. Try asking the user
                // for those permissions and then relaunching the app (which will then try and
                // create the session again).
                permissionLauncher.launch(yourPermissionsForConfig(config).toTypedArray())
            } catch (e: UnsupportedOperationException) {
                // Session configuration is not supported. This means we likely won't have the
                // required feature support, so we probably just need to report an error and
                // then close.
                Toast.makeText(
                        activity,
                        "Unable to configure ARCore session, closing activity. ",
                        Toast.LENGTH_LONG,
                    )
                    .show()
                activity.finish()
            }
        }

        is SessionCreateApkRequired -> {
            // Certain runtimes (notably, ARCore for Play Services) require additional APKs in
            // order to function.
            when (
                val result =
                    ArCoreApk.getInstance().requestInstall(activity, !userRequestedInstall)
            ) {
                ArCoreApk.InstallStatus.INSTALLED -> {
                    // ARCore has been successfully installed, so try running this creation
                    // function again.
                }
                ArCoreApk.InstallStatus.INSTALL_REQUESTED -> {
                    // The current application will be paused to offer to install the ARCore
                    // apk. When it resumes, this creation function should be called again, but
                    // userRequestedInstall should be explicitly set to true.
                }
            }
        }
        is SessionCreateUnsupportedDevice -> {
            // Session creation is not supported on this device, so we just need to report an
            // error and then close.
            Toast.makeText(
                    activity,
                    "Unable to create ARCore session; device unsupported, closing activity. ",
                    Toast.LENGTH_LONG,
                )
                .show()
            activity.finish()
        }
    }
} catch (e: SecurityException) {
    // Session creation failed due to missing permission. Try asking the user for those
    // permissions and then relaunching the app (which will then try and create the session
    // again).
    permissionLauncher.launch(yourPermissionsForConfig(config).toTypedArray())
}
Parameters
@NonNull Activity activity

the Activity that provides the context for the session's resources and controls the session's runtime state based on the activity's lifecycle.
@NonNull CoroutineContext coroutineContext

the CoroutineContext 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 another SessionCreateResult if a certain criteria was not met.
Throws
java.lang.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.

create

Added in 1.0.0-alpha09
public static final @NonNull SessionCreateResult create(
    @NonNull Activity activity,
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull CoroutineContext coroutineContext
)

Creates a new Session with a provided LifecycleOwner.

Only use this version of the constructor if you desire to have finer control over the session's lifecycle. The lifecycleOwner's lifecycle must still be bounded within the lifecycle of the provided activity. The session will be automatically destroyed if the activity's lifecycle becomes destroyed.

import androidx.activity.result.ActivityResultLauncher
import androidx.activity.result.contract.ActivityResultContracts
import androidx.xr.runtime.Config
import androidx.xr.runtime.Session
import androidx.xr.runtime.SessionConfigureCalibrationRequired
import androidx.xr.runtime.SessionConfigureSuccess
import androidx.xr.runtime.SessionCreateApkRequired
import androidx.xr.runtime.SessionCreateSuccess
import androidx.xr.runtime.SessionCreateUnsupportedDevice

val permissionLauncher: ActivityResultLauncher<Array<String>> =
    activity.registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) {
        permissions ->
        val allPermissionsGranted = permissions.all { it.value }
        if (!allPermissionsGranted) {
            Toast.makeText(
                    activity,
                    "Required permissions were not granted, closing activity. ",
                    Toast.LENGTH_LONG,
                )
                .show()
            activity.finish()
        } else {
            activity.recreate()
        }
    }

val config = generateConfig()

try {
    // First, we need to create the session.
    when (val result = Session.create(activity)) {
        // Having successfully created the session, we now need to configure it.
        is SessionCreateSuccess -> {
            val session = result.session
            try {
                when (val configResult = session.configure(config)) {
                    is SessionConfigureCalibrationRequired -> {
                        // Certain runtimes require user calibration in order to operate
                        // effectively.
                        // Either launch the calibration activity, or inform the user they must
                        // do so.
                        handleSessionCalibration(configResult.calibrationType)
                    }
                    is SessionConfigureSuccess -> {
                        // Our Session was successfully configured, so now we can continue
                        // initializing the rest of our application.
                        handleConfiguredSession(session)
                    }
                    else -> {
                        Toast.makeText(
                                activity,
                                "Unexpected session configuration result, closing activity. ",
                                Toast.LENGTH_LONG,
                            )
                            .show()
                        activity.finish()
                    }
                }
            } catch (e: SecurityException) {
                // Session configuration failed due to missing permission. Try asking the user
                // for those permissions and then relaunching the app (which will then try and
                // create the session again).
                permissionLauncher.launch(yourPermissionsForConfig(config).toTypedArray())
            } catch (e: UnsupportedOperationException) {
                // Session configuration is not supported. This means we likely won't have the
                // required feature support, so we probably just need to report an error and
                // then close.
                Toast.makeText(
                        activity,
                        "Unable to configure ARCore session, closing activity. ",
                        Toast.LENGTH_LONG,
                    )
                    .show()
                activity.finish()
            }
        }

        is SessionCreateApkRequired -> {
            // Certain runtimes (notably, ARCore for Play Services) require additional APKs in
            // order to function.
            when (
                val result =
                    ArCoreApk.getInstance().requestInstall(activity, !userRequestedInstall)
            ) {
                ArCoreApk.InstallStatus.INSTALLED -> {
                    // ARCore has been successfully installed, so try running this creation
                    // function again.
                }
                ArCoreApk.InstallStatus.INSTALL_REQUESTED -> {
                    // The current application will be paused to offer to install the ARCore
                    // apk. When it resumes, this creation function should be called again, but
                    // userRequestedInstall should be explicitly set to true.
                }
            }
        }
        is SessionCreateUnsupportedDevice -> {
            // Session creation is not supported on this device, so we just need to report an
            // error and then close.
            Toast.makeText(
                    activity,
                    "Unable to create ARCore session; device unsupported, closing activity. ",
                    Toast.LENGTH_LONG,
                )
                .show()
            activity.finish()
        }
    }
} catch (e: SecurityException) {
    // Session creation failed due to missing permission. Try asking the user for those
    // permissions and then relaunching the app (which will then try and create the session
    // again).
    permissionLauncher.launch(yourPermissionsForConfig(config).toTypedArray())
}
Parameters
@NonNull Activity activity

the Activity that provides the context for the session's resources.
@NonNull LifecycleOwner lifecycleOwner

the LifecycleOwner whose lifecycle controls the runtime state of the session.
@NonNull CoroutineContext coroutineContext

the CoroutineContext 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 another SessionCreateResult if a certain criteria was not met.
Throws
java.lang.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-alpha09
public final @NonNull Config getConfig()

The current state of the runtime configuration.

getState

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

A StateFlow of the current state.

Extension functions

RxJava3SessionKt.getStateAsFlowable

public final @NonNull Flowable<@NonNull CoreState> RxJava3SessionKt.getStateAsFlowable(@NonNull Session receiver)

A Flowable of the current CoreState.

SessionExtKt.getScene

public final @NonNull Scene SessionExtKt.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