GroupableFeature

Kotlin |Java

@ExperimentalSessionConfig
abstract class GroupableFeature

Represents distinct, groupable camera functionalities that can be requested for a camera session.

CameraX provides various implementations of this class as objects to denote various groupable features, i.e. HDR_HLG10, FPS_60, IMAGE_ULTRA_HDR. Since features may not be supported together as a combination even if each of them are supported individually, these groupable features can be configured as a group in a androidx.camera.core.SessionConfig to ensure compatibility when they are used together. When configuring the camera with a session config containing groups of features, their impact on the camera session as a combination will also be considered and compatibility issue will be reported or handled properly based on the exact API used (i.e. exception will be thrown if SessionConfig.requiredFeatureGroup is not supported, or some/all features from SessionConfig.preferredFeatureGroup will be dropped based on priority).

Additionally, the androidx.camera.core.CameraInfo.isFeatureGroupSupported API can be used to check if a group of features is supported together on a device.

import androidx.camera.core.CameraSelector
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

// Bind a session config with some high quality features configured as per app requirements.

cameraProvider.bindToLifecycle(
    lifecycleOwner,
    CameraSelector.DEFAULT_BACK_CAMERA,
    SessionConfig(
            useCases = useCases,
            requiredFeatureGroup = setOf(HDR_HLG10),
            preferredFeatureGroup = listOf(FPS_60, PREVIEW_STABILIZATION),
            // The preferred features will be set according to device capabilities and priority,
            // FPS_60 will be prioritized higher than PREVIEW_STABILIZATION here as FPS_60 is
            // placed earlier in the list.
        )
        .apply {
            setFeatureSelectionListener { features ->
                // Update app UI based on the features selected if required, e.g. a menu with
                // the options of HDR and SDR can be updated to show that HDR is the current
                // selected option
                updateFeatureMenuUi(selectedFeatures = features)
            }
        },
)

See also
`setRequiredFeatureGroup`
`setPreferredFeatureGroup`

Summary

Constants
`const Int`	`FEATURE_TYPE_DYNAMIC_RANGE = 0` Represents the dynamic range feature that can be used for functionalities like HDR video recording.
`const Int`	`FEATURE_TYPE_FPS_RANGE = 1` Represents the FPS range feature that can be used for functionalities like 60 FPS video recording.
`const Int`	`FEATURE_TYPE_IMAGE_FORMAT = 3` Represents the image format feature that can be used to capture JPEG Ultra HDR images.
`const Int`	`FEATURE_TYPE_VIDEO_STABILIZATION = 2` Represents the video stabilization feature that can be used to apply stabilization to the preview and recorded video.

Public companion properties
`GroupableFeature`	`FPS_60` A feature object of type `FEATURE_TYPE_FPS_RANGE` representing 60 FPS (i.e. both the lower and upper bound of the FPS range is 60).
`GroupableFeature`	`HDR_HLG10` A feature object of type `FEATURE_TYPE_DYNAMIC_RANGE` representing the 10-bit High Log-Gamma (HLG) HDR.
`GroupableFeature`	`IMAGE_ULTRA_HDR` A feature object of type `FEATURE_TYPE_IMAGE_FORMAT` that makes the `ImageCapture` use case capture Ultra HDR JPEG images.
`GroupableFeature`	`PREVIEW_STABILIZATION` A feature object of type `FEATURE_TYPE_VIDEO_STABILIZATION` representing a video stabilization mode that applies to the preview as well.

Public properties
`Int`	`featureType` The type of this feature, which will be one of the following values.

Constants

FEATURE_TYPE_DYNAMIC_RANGE

const val FEATURE_TYPE_DYNAMIC_RANGE = 0: Int

Represents the dynamic range feature that can be used for functionalities like HDR video recording.

See also
`HDR_HLG10`

FEATURE_TYPE_FPS_RANGE

const val FEATURE_TYPE_FPS_RANGE = 1: Int

Represents the FPS range feature that can be used for functionalities like 60 FPS video recording.

See also
`FPS_60`

FEATURE_TYPE_IMAGE_FORMAT

const val FEATURE_TYPE_IMAGE_FORMAT = 3: Int

Represents the image format feature that can be used to capture JPEG Ultra HDR images.

See also
`IMAGE_ULTRA_HDR`

FEATURE_TYPE_VIDEO_STABILIZATION

const val FEATURE_TYPE_VIDEO_STABILIZATION = 2: Int

Represents the video stabilization feature that can be used to apply stabilization to the preview and recorded video.

See also
`PREVIEW_STABILIZATION`

Public companion properties

FPS_60

val FPS_60: GroupableFeature

A feature object of type FEATURE_TYPE_FPS_RANGE representing 60 FPS (i.e. both the lower and upper bound of the FPS range is 60).

When used, this feature ensures the camera always operates at a constant 60 FPS.

HDR_HLG10

val HDR_HLG10: GroupableFeature

A feature object of type FEATURE_TYPE_DYNAMIC_RANGE representing the 10-bit High Log-Gamma (HLG) HDR.

The dynamic range is applied to both the Preview and VideoCapture use cases when they are added together with this feature.

See also
`HLG_10_BIT`

IMAGE_ULTRA_HDR

val IMAGE_ULTRA_HDR: GroupableFeature

A feature object of type FEATURE_TYPE_IMAGE_FORMAT that makes the ImageCapture use case capture Ultra HDR JPEG images.

See also
`OUTPUT_FORMAT_JPEG_ULTRA_HDR`

PREVIEW_STABILIZATION

val PREVIEW_STABILIZATION: GroupableFeature

A feature object of type FEATURE_TYPE_VIDEO_STABILIZATION representing a video stabilization mode that applies to the preview as well.

See also
`setPreviewStabilizationEnabled`

Public properties

featureType

Added in 1.5.0-beta02

val featureType: Int

The type of this feature, which will be one of the following values.