SessionConfig
@ExperimentalSessionConfig
public 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 |
|---|
@ExperimentalSessionConfigBuilder for |
Public constructors |
|---|
SessionConfig(@NonNull UseCase... useCases)Creates the SessionConfig from use cases only. |
Public methods |
|
|---|---|
final @NonNull List<@NonNull CameraEffect> |
The list of |
final @NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>> |
Gets the feature selection listener set to this session config. |
final @NonNull Executor |
Gets the executor set to this session config for feature selection listener invocation. |
final @NonNull Range<@NonNull Integer> |
The desired frame rate range for the camera session. |
final @NonNull List<@NonNull GroupableFeature> |
A list of preferred |
final @NonNull Set<@NonNull GroupableFeature> |
A set of |
final @NonNull List<@NonNull UseCase> |
The list of |
final ViewPort |
The |
final void |
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 constructors
SessionConfig
public SessionConfig(@NonNull UseCase... useCases)
Creates the SessionConfig from use cases only.
SessionConfig
public SessionConfig(
@NonNull List<@NonNull UseCase> useCases,
ViewPort viewPort,
@NonNull List<@NonNull CameraEffect> effects,
@NonNull Range<@NonNull Integer> frameRateRange,
@NonNull Set<@NonNull GroupableFeature> requiredFeatureGroup,
@NonNull List<@NonNull GroupableFeature> preferredFeatureGroup
)
Public methods
getEffects
public final @NonNull List<@NonNull CameraEffect> getEffects()
The list of CameraEffect to be applied on the camera session. If not set, the default is no effects.
getFeatureSelectionListener
public final @NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>> getFeatureSelectionListener()
Gets the feature selection listener set to this session config.
| See also | |
|---|---|
setFeatureSelectionListener |
getFeatureSelectionListenerExecutor
public final @NonNull Executor getFeatureSelectionListenerExecutor()
Gets the executor set to this session config for feature selection listener invocation.
| See also | |
|---|---|
setFeatureSelectionListener |
getFrameRateRange
public final @NonNull Range<@NonNull Integer> getFrameRateRange()
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.
getPreferredFeatureGroup
public final @NonNull List<@NonNull GroupableFeature> getPreferredFeatureGroup()
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.
getRequiredFeatureGroup
public final @NonNull Set<@NonNull GroupableFeature> getRequiredFeatureGroup()
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.
getUseCases
public final @NonNull List<@NonNull UseCase> getUseCases()
The list of UseCase to be attached to the camera and receive camera data. This can't be empty.
getViewPort
public final ViewPort getViewPort()
The ViewPort to be applied on the camera session. If not set, the default is no viewport.
setFeatureSelectionListener
public final void setFeatureSelectionListener(
@NonNull Executor executor,
@NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>> listener
)
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.