SessionConfig
@ExperimentalSessionConfig
open class SessionConfig
HighSpeedVideoSessionConfig |
A |
Represents a session configuration to start a camera session. When used with camera-lifecycle, this SessionConfig is expected to be used for starting a camera session (e.g. by being bound to the androidx.lifecycle.LifecycleOwner via androidx.camera.lifecycle.ProcessCameraProvider.bindToLifecycle API which allows the lifecycle events to start and stop the camera session with this given configuration).
It consists of a collection of UseCase, session parameters to be applied on the camera session, and common properties like the field-of-view defined by ViewPort, the CameraEffect, frame rate, required or preferred GroupableFeature groups etc.
When configuring a session config with GroupableFeatures (i.e. requiredFeatureGroup or preferredFeatureGroup is used), avoid using non-grouping APIs for any feature that is groupable (see GroupableFeature to know which features are groupable). Doing so can lead to conflicting configurations and an IllegalArgumentException. The following code sample explains this further.
import androidx.camera.core.DynamicRange import androidx.camera.core.Preview import androidx.camera.core.SessionConfig import androidx.camera.core.featuregroup.GroupableFeature.Companion.FPS_60 import androidx.camera.core.featuregroup.GroupableFeature.Companion.HDR_HLG10 import androidx.camera.core.featuregroup.GroupableFeature.Companion.PREVIEW_STABILIZATION // Create a session config where HDR is mandatory while 60 FPS (higher priority) and preview // stabilization are optional SessionConfig( useCases = listOf(Preview.Builder().build()), requiredFeatureGroup = setOf(HDR_HLG10), preferredFeatureGroup = listOf(FPS_60, PREVIEW_STABILIZATION), ) // Creating the following SessionConfig will throw an exception as there are conflicting // information. HDR is mentioned once as required and then again as preferred, it can't be both! SessionConfig( useCases = listOf(Preview.Builder().build()), requiredFeatureGroup = setOf(HDR_HLG10), preferredFeatureGroup = listOf(FPS_60, HDR_HLG10), ) // Creating the following SessionConfig will throw an exception as a groupable feature (HDR) is // configured with non-grouping API while using grouping API as well. HDR is configured to the // with a non-grouping API through the Preview use case, so it can't be grouped together // properly with the other groupable features. Instead, it should be configured like the first // SessionConfig construction in this code snippet. SessionConfig( useCases = listOf(Preview.Builder().apply { setDynamicRange(DynamicRange.HLG_10_BIT) }.build()), preferredFeatureGroup = listOf(FPS_60, PREVIEW_STABILIZATION), )
| Throws | |
|---|---|
kotlin.IllegalArgumentException |
If the combination of config options are conflicting or unsupported. |
| See also | |
|---|---|
bindToLifecycle |
Summary
Nested types |
|---|
|
Builder for |
Public constructors |
|---|
SessionConfig(vararg useCases: UseCase)Creates the SessionConfig from use cases only. |
SessionConfig( |
Public functions |
|
|---|---|
Unit |
setFeatureSelectionListener(Sets a listener to know which features are finally selected when a session config is bound, based on the user-defined priorities/ordering for |
Public properties |
|
|---|---|
List<CameraEffect> |
The list of |
Consumer<Set<GroupableFeature>> |
Gets the feature selection listener set to this session config. |
Executor |
Gets the executor set to this session config for feature selection listener invocation. |
Range<Int> |
The desired frame rate range for the camera session. |
List<GroupableFeature> |
A list of preferred |
Set<GroupableFeature> |
A set of |
List<UseCase> |
The list of |
ViewPort? |
The |
Public constructors
SessionConfig
SessionConfig(vararg useCases: UseCase)
Creates the SessionConfig from use cases only.
SessionConfig
SessionConfig(
useCases: List<UseCase>,
viewPort: ViewPort? = null,
effects: List<CameraEffect> = emptyList(),
frameRateRange: Range<Int> = FRAME_RATE_RANGE_UNSPECIFIED,
requiredFeatureGroup: Set<GroupableFeature> = emptySet(),
preferredFeatureGroup: List<GroupableFeature> = emptyList()
)
Public functions
setFeatureSelectionListener
fun setFeatureSelectionListener(
executor: Executor = CameraXExecutors.mainThreadExecutor(),
listener: Consumer<Set<GroupableFeature>>
): Unit
Sets a listener to know which features are finally selected when a session config is bound, based on the user-defined priorities/ordering for preferredFeatureGroup and device capabilities.
Both the required and the selected preferred features are notified to the listener. The listener is invoked when this session config is bound to camera (e.g. when the androidx.camera.lifecycle.ProcessCameraProvider.bindToLifecycle API is invoked). It is invoked even when no preferred features are selected, providing either the required features or an empty set (if no feature was set as required).
Alternatively, the CameraInfo.isFeatureGroupSupported API can be used to query if a set of features is supported before binding.
| Parameters | |
|---|---|
executor: Executor = CameraXExecutors.mainThreadExecutor() |
The executor in which the listener will be invoked. If not set, the main thread is used by default. |
listener: Consumer<Set<GroupableFeature>> |
The consumer to accept the final set of features when they are selected. |
Public properties
effects
val effects: List<CameraEffect>
The list of CameraEffect to be applied on the camera session. If not set, the default is no effects.
featureSelectionListener
val featureSelectionListener: Consumer<Set<GroupableFeature>>
Gets the feature selection listener set to this session config.
| See also | |
|---|---|
setFeatureSelectionListener |
featureSelectionListenerExecutor
val featureSelectionListenerExecutor: Executor
Gets the executor set to this session config for feature selection listener invocation.
| See also | |
|---|---|
setFeatureSelectionListener |
frameRateRange
val frameRateRange: Range<Int>
The desired frame rate range for the camera session. The value must be one of the supported frame rates queried by CameraInfo.getSupportedFrameRateRanges with a specific SessionConfig, or an IllegalArgumentException will be thrown during SessionConfig binding (i.e. when calling androidx.camera.lifecycle.ProcessCameraProvider.bindToLifecycle or androidx.camera.lifecycle.LifecycleCameraProvider.bindToLifecycle). When this value is set, any target frame rate set on individual UseCase will be ignored during SessionConfig binding. If this value is not set, the default is FRAME_RATE_RANGE_UNSPECIFIED, which means no specific frame rate. The range defines the acceptable minimum and maximum frame rate for the camera session. A dynamic range (e.g., [15, 30]) allows the camera to adjust its frame rate within the bounds, which will benefit previewing in low light by enabling longer exposures for brighter, less noisy images; conversely, a fixed range (e.g., [30, 30]) ensures a stable frame rate crucial for video recording, though it can lead to darker, noisier video in low light due to shorter exposure times.
preferredFeatureGroup
val preferredFeatureGroup: List<GroupableFeature>
A list of preferred GroupableFeature ordered according to priority in descending order, i.e. a feature with a lower index in the list is considered to have a higher priority. If not set, the default is an empty list. See SessionConfig.Builder.setPreferredFeatureGroup for more info.
requiredFeatureGroup
val requiredFeatureGroup: Set<GroupableFeature>
A set of GroupableFeature that are mandatory for the camera session configuration. If not set, the default is an empty set. See SessionConfig.Builder.setRequiredFeatureGroup for more info.
useCases
val useCases: List<UseCase>
The list of UseCase to be attached to the camera and receive camera data. This can't be empty.
viewPort
val viewPort: ViewPort?
The ViewPort to be applied on the camera session. If not set, the default is no viewport.