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 BOKEH, HDR, NIGHT, FACE_RETOUCH and 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 with getInstanceAsync. Only a single ExtensionsManager instance can exist within a process. 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.

void bindUseCasesWithBokehMode() {
    // Create a camera provider
    ProcessCameraProvider cameraProvider = ... // Get the provider instance
    // Call the getInstance function to retrieve a ListenableFuture object
    ListenableFuture future = ExtensionsManager.getInstance(context, cameraProvider);

    // Obtain the ExtensionsManager instance from the returned ListenableFuture object
    future.addListener(() -> {
        try {
            ExtensionsManager extensionsManager = future.get()

            // Query if extension is available.
            if (mExtensionsManager.isExtensionAvailable(DEFAULT_BACK_CAMERA,
                       ExtensionMode.BOKEH)) {
                // Needs to unbind all use cases before enabling different extension mode.
                cameraProvider.unbindAll();

                // Retrieve extension enabled camera selector
                CameraSelector extensionCameraSelector;
                extensionCameraSelector = extensionsManager.getExtensionEnabledCameraSelector(
                        DEFAULT_BACK_CAMERA, ExtensionMode.BOKEH);

                // Bind image capture and preview use cases with the extension enabled camera
                // selector.
                ImageCapture imageCapture = new ImageCapture.Builder().build();
                Preview preview = new Preview.Builder().build();
                cameraProvider.bindToLifecycle(lifecycleOwner, extensionCameraSelector,
                        imageCapture, preview);
            }
        } catch (ExecutionException | InterruptedException e) {
            // This should not happen unless the future is cancelled or the thread is
            // interrupted by applications.
        }
    }, ContextCompact.getMainExecutor(context));
}

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 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 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 getOutputSizes. CameraX will select the supported sizes for the use cases according to the use cases' configuration and combination.

Summary

fun getCameraExtensionsControl(cameraControl: CameraControl): CameraExtensionsControl?

fun getCameraExtensionsInfo(cameraInfo: CameraInfo): CameraExtensionsInfo

fun getEstimatedCaptureLatencyRange(
    cameraSelector: CameraSelector,
    mode: Int
): Range<Long!>?

fun getExtensionEnabledCameraSelector(
    baseCameraSelector: CameraSelector,
    mode: Int
): CameraSelector

java-static fun getInstanceAsync(context: Context, cameraProvider: CameraProvider): ListenableFuture<ExtensionsManager!>

fun isExtensionAvailable(baseCameraSelector: CameraSelector, mode: Int): Boolean

fun isImageAnalysisSupported(cameraSelector: CameraSelector, mode: Int): Boolean