ExtensionsManager

class ExtensionsManager

Provides interfaces for third party app developers to get capabilities info of extension functions.

Many Android devices contain powerful cameras, with manufacturers devoting a lot of effort to build many cutting-edge features, or special effects, into these camera devices. CameraX Extensions allows third party apps to enable the available extension modes on the supported devices. The extension modes which might be supported via CameraX Extensions are ExtensionMode.BOKEH, ExtensionMode.HDR, ExtensionMode.NIGHT, ExtensionMode.FACE_RETOUCH and ExtensionMode.AUTO. The known supported devices are listed in the Supported devices page.

CameraX Extensions are built on the top of CameraX Core libraries. To enable an extension mode, an ExtensionsManager instance needs to be retrieved first. For kotlin users, it is recommended to use ExtensionsManager.getInstance which is a suspend function. For Java users, please use getInstanceAsync.

After retrieving the ExtensionsManager instance, the availability of a specific extension mode can be checked by isExtensionAvailable. For an available extension mode, an extension enabled CameraSelector can be obtained by calling getExtensionEnabledCameraSelector. After binding use cases by the extension enabled CameraSelector, the extension mode will be applied to the bound Preview and ImageCapture. The following sample code describes how to enable an extension mode for use cases.

suspend fun bindUseCasesWithBokehMode(context: Context, lifecycleOwner: LifecycleOwner) {
    // Create a camera provider.
    val cameraProvider = ProcessCameraProvider.awaitInstance(context)

    // Retrieve the ExtensionsManager instance.
    val extensionsManager = ExtensionsManager.getInstance(context, cameraProvider)

    val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
    // Query if extension is available.
    if (extensionsManager.isExtensionAvailable(cameraSelector, ExtensionMode.BOKEH)) {
        // Create an ExtensionSessionConfig.
        val imageCapture = ImageCapture.Builder().build()
        val preview = Preview.Builder().build()
        ExtensionSessionConfig sessionConfig = ExtensionSessionConfig(
                ExtensionMode.BOKEH,
                extensionsManager,
                imageCapture,
                preview
        )
        cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, sessionConfig)
    }
}

Without enabling CameraX Extensions, any device should be able to support the use cases combination of ImageCapture, Preview and ImageAnalysis. To support the CameraX Extensions functionality, the ImageCapture or Preview might need to occupy a different format of stream. This might restrict the app to not be able to bind ImageCapture, Preview and ImageAnalysis at the same time if the device's hardware level is not CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_FULL or above. If enabling an extension mode is more important and the ImageAnalysis could be optional to the app design, the extension mode can be enabled successfully when only binding ImageCapture, Preview even if the device's hardware level is CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED.

While CameraX Extensions dose not directly support androidx.camera.video.VideoCapture, androidx.camera.video.VideoCapture can still be used when any extension mode is enabled. When the app binds androidx.camera.video.VideoCapture and enables any extension mode, androidx.camera.video.VideoCapture can obtain the shared stream of Preview and record it as a video.

For some devices, the vendor library implementation might only support a subset of the all supported sizes retrieved by StreamConfigurationMap.getOutputSizes. CameraX will select the supported sizes for the use cases according to the use cases' configuration and combination.

Summary

Public companion functions
suspend ExtensionsManager
getInstance(context: Context, cameraProvider: CameraProvider)

Retrieves the ExtensionsManager.
ListenableFuture<ExtensionsManager>
getInstanceAsync(context: Context, cameraProvider: CameraProvider)

Retrieves the ExtensionsManager associated with the current process.

Public functions
CameraExtensionsControl?

Retrieves a CameraExtensionsControl object that allows customization of capture request settings for supported camera extensions.
CameraExtensionsInfo

Retrieves a CameraExtensionsInfo object that allows to observe or monitor capture request settings and results for supported camera extensions.
Range<Long>?
getEstimatedCaptureLatencyRange(
    cameraSelector: CameraSelector,
    mode: Int
)

Returns the estimated capture latency range in milliseconds for the target camera and extension mode.
CameraSelector
getExtensionEnabledCameraSelector(
    cameraSelector: CameraSelector,
    mode: Int
)

Returns a modified CameraSelector that will enable the specified extension mode.
Boolean
isExtensionAvailable(cameraSelector: CameraSelector, mode: Int)

Checks if a specific extension mode is available for a given CameraSelector.
Boolean
isImageAnalysisSupported(cameraSelector: CameraSelector, mode: Int)

Returns whether the given extension mode supports the ImageAnalysis use case on the camera specified by the given CameraSelector.

Public companion functions

getInstance

suspend fun getInstance(context: Context, cameraProvider: CameraProvider): ExtensionsManager

Retrieves the ExtensionsManager.

Parameters
context: Context

The application context.
cameraProvider: CameraProvider

A CameraProvider will be used to query the information of cameras on the device.
Returns
ExtensionsManager

A fully initialized ExtensionsManager for the current process.
See also
getInstanceAsync

getInstanceAsync

Added in 1.6.0-alpha02
fun getInstanceAsync(context: Context, cameraProvider: CameraProvider): ListenableFuture<ExtensionsManager>

Retrieves the ExtensionsManager associated with the current process.

An application must wait until the ListenableFuture completes to get an ExtensionsManager instance. The ExtensionsManager instance can be used to access the extensions related functions.

Parameters
context: Context

The context to initialize the extensions library.
cameraProvider: CameraProvider

A CameraProvider will be used to query the information of cameras on the device. The CameraProvider can be the androidx.camera.lifecycle.ProcessCameraProvider which is obtained by androidx.camera.lifecycle.ProcessCameraProvider.getInstance.

Public functions

getCameraExtensionsControl

Added in 1.4.0
fun getCameraExtensionsControl(cameraControl: CameraControl): CameraExtensionsControl?

Retrieves a CameraExtensionsControl object that allows customization of capture request settings for supported camera extensions.

Parameters
cameraControl: CameraControl

the camera control for a camera with a specific extension mode turned on.
Returns
CameraExtensionsControl?

a CameraExtensionsControl object to manage extension-related settings. Or returns null if the provided CameraControl doesn't represent a camera with enabled extensions.

getCameraExtensionsInfo

Added in 1.4.0
fun getCameraExtensionsInfo(cameraInfo: CameraInfo): CameraExtensionsInfo

Retrieves a CameraExtensionsInfo object that allows to observe or monitor capture request settings and results for supported camera extensions.

If the provided CameraInfo doesn't represent a camera with enabled extensions, a placeholder CameraExtensionsInfo object will be returned, indicating no extension type and strength support.

Parameters
cameraInfo: CameraInfo

the camera info for a camera with a specific extension mode turned on.
Returns
CameraExtensionsInfo

a CameraExtensionsInfo object for observing extension-specific capture request settings and results.

getEstimatedCaptureLatencyRange

Added in 1.1.0
fun getEstimatedCaptureLatencyRange(
    cameraSelector: CameraSelector,
    mode: Int
): Range<Long>?

Returns the estimated capture latency range in milliseconds for the target camera and extension mode.

This includes the time spent processing the multi-frame capture request along with any additional time for encoding of the processed buffer in the framework if necessary.

Parameters
cameraSelector: CameraSelector

The CameraSelector to find a camera which supports the specified extension mode.
mode: Int

The extension mode to check.
Returns
Range<Long>?

the range of estimated minimal and maximal capture latency in milliseconds. Returns null if no capture latency info can be provided or if the device doesn't support the extension mode on this camera.

getExtensionEnabledCameraSelector

Added in 1.1.0
fun getExtensionEnabledCameraSelector(
    cameraSelector: CameraSelector,
    mode: Int
): CameraSelector

Returns a modified CameraSelector that will enable the specified extension mode.

The returned extension CameraSelector can be used to bind use cases to a desired LifecycleOwner and then the specified extension mode will be enabled on the camera.

Parameters
cameraSelector: CameraSelector

The base CameraSelector on top of which the extension config is applied. isExtensionAvailable can be used to check whether any camera can support the specified extension mode for the base camera selector.
mode: Int

The target extension mode.
Returns
CameraSelector

a CameraSelector for the specified Extensions mode.
Throws
kotlin.IllegalArgumentException

If this device doesn't support extensions function, no camera can be found to support the specified extension mode, or the base CameraSelector has contained extension related configuration in it.

isExtensionAvailable

Added in 1.1.0
fun isExtensionAvailable(cameraSelector: CameraSelector, mode: Int): Boolean

Checks if a specific extension mode is available for a given CameraSelector.

To use Ultra HDR, you must first check for support and then enable the format. This feature is available on capable devices starting from API level 34.

  1. Obtain a CameraInfo instance by calling CameraProvider.getCameraInfo with the extension-enabled CameraSelector from getExtensionEnabledCameraSelector.

  2. Use this CameraInfo to get the ImageCaptureCapabilities via ImageCapture.getImageCaptureCapabilities.

  3. Check the supported formats by calling ImageCaptureCapabilities.getSupportedOutputFormats. The presence of ImageCapture.OUTPUT_FORMAT_JPEG_ULTRA_HDR indicates Ultra HDR support.

  4. When Ultra HDR is supported, configure the ImageCapture to use it by calling ImageCapture.Builder.setOutputFormat with ImageCapture.OUTPUT_FORMAT_JPEG_ULTRA_HDR.

Note: Camera extensions do not support 10-bit preview or video capture. When using extensions, the dynamic range must be DynamicRange.SDR (the default).

Parameters
cameraSelector: CameraSelector

The base CameraSelector used to select the camera.
mode: Int

The extension mode to verify.
Returns
Boolean

true if the extension mode is available for the camera selector, false otherwise.

isImageAnalysisSupported

Added in 1.3.0
fun isImageAnalysisSupported(cameraSelector: CameraSelector, mode: Int): Boolean

Returns whether the given extension mode supports the ImageAnalysis use case on the camera specified by the given CameraSelector. If it returns false, invoking ProcessCameraProvider.bindToLifecycle with an ImageAnalysis use case will throw an IllegalArgumentException.

Parameters
cameraSelector: CameraSelector

The CameraSelector to find a camera which supports the specified extension mode.
mode: Int

The extension mode to check.
Returns
Boolean

true if ImageAnalysis can be bound when the specified extension mode is enabled on the camera specified by the given CameraSelector. Returns false otherwise. If the device doesn't support this extension mode on this camera, it will also return false.