ExtensionsManager

public final class ExtensionsManager
extends Object

java.lang.Object
   ↳ androidx.camera.extensions.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 CameraX devices page. Please see the ones that the Extensions support column is checked.

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(Context, CameraProvider). 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(CameraSelector, int). For an available extension mode, an extension enabled CameraSelector can be obtained by calling getExtensionEnabledCameraSelector(CameraSelector, int). 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 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.

CameraX Extensions currently can only support ImageCapture and Preview. The VideoCapture can't be supported yet. If the app binds VideoCapture and enables any extension mode, an IllegalArgumentException will be thrown.

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

Summary

Public methods

Range<Long> getEstimatedCaptureLatencyRange(CameraSelector cameraSelector, int mode)

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

CameraSelector getExtensionEnabledCameraSelector(CameraSelector baseCameraSelector, int mode)

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

static ListenableFuture<ExtensionsManager> getInstanceAsync(Context context, CameraProvider cameraProvider)

Retrieves the ExtensionsManager associated with the current process.

boolean isExtensionAvailable(CameraSelector baseCameraSelector, int mode)

Returns true if the particular extension mode is available for the specified CameraSelector.

Inherited methods

Public methods

getEstimatedCaptureLatencyRange

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

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.

Throws
IllegalArgumentException If this device doesn't support extensions function, or no camera can be found to support the specified extension mode.