SessionConfig
open class SessionConfig
ExtensionSessionConfig |
A |
HighSpeedVideoSessionConfig |
A |
Represents the configuration for establishing and managing a camera session within CameraX.
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.
Constraints
useCases: This cannot be empty.
-
The value must be one of the supported frame rates queried by
CameraInfo.getSupportedFrameRateRangeswith a specificSessionConfig, or anIllegalArgumentExceptionwill be thrown duringSessionConfigbinding (i.e. when callingandroidx.camera.lifecycle.ProcessCameraProvider.bindToLifecycleorandroidx.camera.lifecycle.LifecycleCameraProvider.bindToLifecycle). -
When this value is set, no individual
UseCasecan have a target frame rate set (e.g., viaPreview.Builder.setTargetFrameRateorVideoCapture.Builder.setTargetFrameRate); doing so will result in anIllegalArgumentException.
requiredFeatureGroup and preferredFeatureGroup:
-
Avoid using non-groupable APIs for any feature that is groupable (see
GroupableFeatureto know which features are groupable). Doing so can lead to conflicting configurations. -
Avoid setting multiple
GroupableFeatures with the sameGroupableFeature.featureTypeas required, as they conflict with each other. If they are set as preferred, only one will be selected according to the feature priorities, which are defined by the ordering in thepreferredFeatureGrouplist.
Not complying with these constraints will lead to an IllegalArgumentException. The following code sample explains this further.
import androidx.camera.core.CameraEffect import androidx.camera.core.DynamicRange import androidx.camera.core.ImageAnalysis 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 import androidx.camera.video.GroupableFeatures.FHD_RECORDING import androidx.camera.video.GroupableFeatures.UHD_RECORDING import androidx.camera.video.Recorder import androidx.camera.video.VideoCapture // 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), ) // Creating the following SessionConfig will throw an exception due to the conflicting // information. The features UHD_RECORDING and FHD_RECORDING share the same type // (FEATURE_TYPE_RECORDING_QUALITY), meaning both can't be simultaneously required. This is // akin to requesting the final video recording size to be both UHD and FHD at the same time. SessionConfig( useCases = listOf(Preview.Builder().build(), VideoCapture.withOutput(Recorder.Builder().build())), requiredFeatureGroup = setOf(HDR_HLG10, UHD_RECORDING, FHD_RECORDING), preferredFeatureGroup = listOf(FPS_60), ) // Creating the following SessionConfig will throw an exception as ImageAnalysis is not yet // supported with groupable features. SessionConfig( useCases = listOf(ImageAnalysis.Builder().build()), requiredFeatureGroup = setOf(HDR_HLG10), preferredFeatureGroup = listOf(FPS_60, HDR_HLG10), ) // Creating the following SessionConfig will throw an exception as CameraEffect is not yet // supported with groupable features. SessionConfig( useCases = listOf(Preview.Builder().build()), requiredFeatureGroup = setOf(HDR_HLG10), preferredFeatureGroup = listOf(FPS_60, HDR_HLG10), effects = effects, )
| Throws | |
|---|---|
kotlin.IllegalArgumentException |
If the combination of config options are conflicting or unsupported, or if the |
| See also | |
|---|---|
bindToLifecycle |
Summary
Nested types |
|---|
class SessionConfig.BuilderBuilder 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 |
open String |
toString() |
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.isSessionConfigSupported 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. 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, benefiting 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.