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 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

Public methods
@Nullable CameraExtensionsControl

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

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

Returns the estimated capture latency range in milliseconds for the target camera and extension mode.
@NonNull CameraSelector
getExtensionEnabledCameraSelector(
    @NonNull CameraSelector baseCameraSelector,
    int mode
)

Returns a modified CameraSelector that will enable the specified extension mode.
static @NonNull ListenableFuture<ExtensionsManager>
getInstanceAsync(
    @NonNull Context context,
    @NonNull CameraProvider cameraProvider
)

Retrieves the ExtensionsManager associated with the current process.
boolean
isExtensionAvailable(
    @NonNull CameraSelector baseCameraSelector,
    int mode
)

Returns true if the particular extension mode is available for the specified CameraSelector.
boolean
isImageAnalysisSupported(
    @NonNull CameraSelector cameraSelector,
    int mode
)

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

Public methods

getCameraExtensionsControl

Added in 1.4.0
public @Nullable CameraExtensionsControl getCameraExtensionsControl(@NonNull CameraControl cameraControl)

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

Parameters
@NonNull CameraControl cameraControl

the camera control for a camera with a specific extension mode turned on.
Returns
@Nullable 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
public @NonNull CameraExtensionsInfo getCameraExtensionsInfo(@NonNull CameraInfo cameraInfo)

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
@NonNull CameraInfo cameraInfo

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

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

getEstimatedCaptureLatencyRange

Added in 1.1.0
public @Nullable Range<Long> getEstimatedCaptureLatencyRange(
    @NonNull 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
@NonNull CameraSelector cameraSelector

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

The extension mode to check.
Returns
@Nullable 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
public @NonNull CameraSelector getExtensionEnabledCameraSelector(
    @NonNull CameraSelector baseCameraSelector,
    int mode
)

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
@NonNull CameraSelector baseCameraSelector

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.
int mode

The target extension mode.
Returns
@NonNull CameraSelector

a CameraSelector for the specified Extensions mode.
Throws
java.lang.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.

getInstanceAsync

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

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
@NonNull Context context

The context to initialize the extensions library.
@NonNull 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 getInstance.

isExtensionAvailable

Added in 1.1.0
public boolean isExtensionAvailable(
    @NonNull CameraSelector baseCameraSelector,
    int mode
)

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

Note that Extensions are not supported for use with 10-bit capture output (e.g. setting a dynamic range other than SDR).

Parameters
@NonNull CameraSelector baseCameraSelector

The base CameraSelector to find a camera to use.
int mode

The target extension mode to support.

isImageAnalysisSupported

Added in 1.3.0
public boolean isImageAnalysisSupported(
    @NonNull CameraSelector cameraSelector,
    int mode
)

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
@NonNull CameraSelector cameraSelector

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

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.