ExtensionsManager

public final 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 final CameraExtensionsControl getCameraExtensionsControl(@NonNull CameraControl cameraControl)

public final @NonNull CameraExtensionsInfo getCameraExtensionsInfo(@NonNull CameraInfo cameraInfo)

public final Range<@NonNull Long> getEstimatedCaptureLatencyRange(
    @NonNull CameraSelector cameraSelector,
    int mode
)

public final @NonNull CameraSelector getExtensionEnabledCameraSelector(
    @NonNull CameraSelector cameraSelector,
    int mode
)

public static final @NonNull ExtensionsManager getInstance(
    @NonNull Context context,
    @NonNull CameraProvider cameraProvider
)

public static final @NonNull ListenableFuture<@NonNull ExtensionsManager> getInstanceAsync(
    @NonNull Context context,
    @NonNull CameraProvider cameraProvider
)

public final boolean isExtensionAvailable(@NonNull CameraSelector cameraSelector, int mode)

public final boolean isImageAnalysisSupported(
    @NonNull CameraSelector cameraSelector,
    int mode
)