LifecycleCameraProvider


@ExperimentalCameraProviderConfiguration
public interface LifecycleCameraProvider extends CameraProvider


Provides access to a camera which has its opening and closing controlled by a LifecycleOwner.

This allows configuring multiple instances with different Context and CameraXConfig. The use cases can be bound to different camera providers simultaneously, but only one LifecycleOwner can be active at a time.

The sample shows how to configure and create two camera providers differently.

import androidx.camera.camera2.Camera2Config
import androidx.camera.core.CameraSelector
import androidx.camera.core.CameraXConfig
import androidx.camera.lifecycle.LifecycleCameraProvider

val cameraProvider1 =
    LifecycleCameraProvider.createInstance(
        context1,
        CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
            .setCameraExecutor(executor1)
            .build()
    )
cameraProvider1.bindToLifecycle(lifecycleOwner1, CameraSelector.DEFAULT_FRONT_CAMERA, useCase1)

// Switch to different lifecycle owner.

val cameraProvider2 =
    LifecycleCameraProvider.createInstance(
        context2,
        CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
            .setCameraExecutor(executor2)
            .build()
    )
cameraProvider2.bindToLifecycle(lifecycleOwner2, CameraSelector.DEFAULT_BACK_CAMERA, useCase2)

Summary

Public methods

abstract @NonNull ConcurrentCamera

Binds list of SingleCameraConfigs to LifecycleOwner.

abstract @NonNull Camera
bindToLifecycle(
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull CameraSelector cameraSelector,
    @NonNull UseCaseGroup useCaseGroup
)

Binds a UseCaseGroup to a LifecycleOwner.

abstract @NonNull Camera
bindToLifecycle(
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull CameraSelector cameraSelector,
    UseCase useCases
)

Binds the collection of UseCase to a LifecycleOwner.

default static final @NonNull LifecycleCameraProvider
createInstance(@NonNull Context context, CameraXConfig cameraXConfig)

Creates a lifecycle camera provider instance.

default static final @NonNull ListenableFuture<@NonNull LifecycleCameraProvider>
createInstanceAsync(
    @NonNull Context context,
    CameraXConfig cameraXConfig
)

Creates a lifecycle camera provider instance asynchronously.

abstract boolean

Returns true if this UseCase is bound to a lifecycle or included in a bound SessionConfig.

abstract void
unbind(UseCase useCases)

Unbinds all specified use cases from the lifecycle provider.

abstract void

Unbinds all use cases from the lifecycle provider and removes them from CameraX.

Inherited methods

From androidx.camera.core.CameraProvider
abstract @NonNull List<@NonNull CameraInfo>

The CameraInfo instances of the available cameras.

default @NonNull CameraInfo

Returns the CameraInfo instance of the camera resulted from the specified CameraSelector.

abstract boolean
hasCamera(@NonNull CameraSelector cameraSelector)

Checks whether this provider supports at least one camera that meets the requirements from a CameraSelector.

Public methods

bindToLifecycle

Added in 1.5.0-beta01
abstract @NonNull ConcurrentCamera bindToLifecycle(
    @NonNull List<ConcurrentCamera.SingleCameraConfig> singleCameraConfigs
)

Binds list of SingleCameraConfigs to LifecycleOwner.

The concurrent camera is only supporting two cameras currently. If the input list of SingleCameraConfigs have less or more than two SingleCameraConfigs, IllegalArgumentException will be thrown. If cameras are already used by other UseCases, UnsupportedOperationException will be thrown.

A logical camera is a grouping of two or more of those physical cameras. See Multi-camera API

If we want to open concurrent logical cameras, which are one front camera and one back camera, the device needs to support PackageManager.FEATURE_CAMERA_CONCURRENT. To set up concurrent logical camera, call availableConcurrentCameraInfos to get the list of available combinations of concurrent cameras. Each sub-list contains the CameraInfos for a combination of cameras that can be operated concurrently. Each logical camera can have its own UseCases and LifecycleOwner. See {@docRoot}training/camerax/architecture#lifecycles

If the concurrent logical cameras are binding the same preview and video capture use cases, the concurrent cameras video recording will be supported. The concurrent camera preview stream will be shared with video capture and record the concurrent cameras streams as a composited stream. The CompositionSettings can be used to configure the position of each camera stream and different layouts can be built. See CompositionSettings for more details.

If we want to open concurrent physical cameras, which are two front cameras or two back cameras, the device needs to support physical cameras and the capability could be checked via CameraInfo.isLogicalMultiCameraSupported. Each physical cameras can have its own UseCases but needs to have the same LifecycleOwner, otherwise IllegalArgumentException will be thrown.

If we want to open one physical camera, for example ultra wide, we just need to set physical camera id in CameraSelector and bind to lifecycle. All CameraX features will work normally when only a single physical camera is used.

If we want to open multiple physical cameras, we need to have multiple CameraSelectors, each in one SingleCameraConfig and set physical camera id, then bind to lifecycle with the SingleCameraConfigs. Internally each physical camera id will be set on UseCase, for example, Preview and call android.hardware.camera2.params.OutputConfiguration.setPhysicalCameraId.

Currently only two physical cameras for the same logical camera id are allowed and the device needs to support physical cameras by checking CameraInfo.isLogicalMultiCameraSupported. In addition, there is no guarantee or API to query whether the device supports multiple physical camera opening or not. Internally the library checks android.hardware.camera2.CameraDevice.isSessionConfigurationSupported, if the device does not support the multiple physical camera configuration, IllegalArgumentException will be thrown.

Parameters
@NonNull List<ConcurrentCamera.SingleCameraConfig> singleCameraConfigs

Input list of SingleCameraConfigs.

Returns
@NonNull ConcurrentCamera

Output ConcurrentCamera instance.

Throws
kotlin.IllegalArgumentException

If less or more than two camera configs are provided.

kotlin.UnsupportedOperationException

If device is not supporting concurrent camera or cameras are already used by other UseCases.

bindToLifecycle

Added in 1.5.0-beta01
abstract @NonNull Camera bindToLifecycle(
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull CameraSelector cameraSelector,
    @NonNull UseCaseGroup useCaseGroup
)

Binds a UseCaseGroup to a LifecycleOwner.

Similar to bindToLifecycle, with the addition that the bound collection of UseCase share parameters defined by UseCaseGroup such as consistent camera sensor rect across all UseCases.

If one UseCase is in multiple UseCaseGroups, it will be linked to the UseCaseGroup in the latest bindToLifecycle call.

Throws
kotlin.UnsupportedOperationException

If the camera is configured in concurrent mode.

bindToLifecycle

Added in 1.5.0-beta01
abstract @NonNull Camera bindToLifecycle(
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull CameraSelector cameraSelector,
    UseCase useCases
)

Binds the collection of UseCase to a LifecycleOwner.

The state of the lifecycle will determine when the cameras are open, started, stopped and closed. When started, the use cases receive camera data.

Binding to a lifecycleOwner in state currently in Lifecycle.State.STARTED or greater will also initialize and start data capture. If the camera was already running this may cause a new initialization to occur temporarily stopping data from the camera before restarting it.

Multiple use cases can be bound via adding them all to a single bindToLifecycle call, or by using multiple bindToLifecycle calls. Using a single call that includes all the use cases helps to set up a camera session correctly for all uses cases, such as by allowing determination of resolutions depending on all the use cases bound being bound. If the use cases are bound separately, it will find the supported resolution with the priority depending on the binding sequence. If the use cases are bound with a single call, it will find the supported resolution with the priority in sequence of ImageCapture, Preview and then ImageAnalysis. The resolutions that can be supported depends on the camera device hardware level that there are some default guaranteed resolutions listed in android.hardware.camera2.CameraDevice.createCaptureSession.

Currently up to 3 use cases may be bound to a Lifecycle at any time. Exceeding capability of target camera device will throw an IllegalArgumentException.

A UseCase should only be bound to a single lifecycle and camera selector a time. Attempting to bind a use case to a lifecycle when it is already bound to another lifecycle is an error, and the use case binding will not change. Attempting to bind the same use case to multiple camera selectors is also an error and will not change the binding.

If different use cases are bound to different camera selectors that resolve to distinct cameras, but the same lifecycle, only one of the cameras will operate at a time. The non-operating camera will not become active until it is the only camera with use cases bound.

The Camera returned is determined by the given camera selector, plus other internal requirements, possibly from use case configurations. The camera returned from bindToLifecycle may differ from the camera determined solely by a camera selector. If the camera selector can't resolve a valid camera under the requirements, an IllegalArgumentException will be thrown.

Only UseCase bound to latest active Lifecycle can keep alive. UseCase bound to other Lifecycle will be stopped.

Parameters
@NonNull LifecycleOwner lifecycleOwner

The lifecycleOwner which controls the lifecycle transitions of the use cases.

@NonNull CameraSelector cameraSelector

The camera selector which determines the camera to use for set of use cases.

UseCase useCases

The use cases to bind to a lifecycle.

Returns
@NonNull Camera

The Camera instance which is determined by the camera selector and internal requirements.

Throws
kotlin.IllegalStateException

If the use case has already been bound to another lifecycle or method is not called on main thread.

kotlin.IllegalArgumentException

If the provided camera selector is unable to resolve a camera to be used for the given use cases.

kotlin.UnsupportedOperationException

If the camera is configured in concurrent mode.

createInstance

default static final @NonNull LifecycleCameraProvider createInstance(@NonNull Context context, CameraXConfig cameraXConfig)

Creates a lifecycle camera provider instance.

Parameters
@NonNull Context context

The Application context.

CameraXConfig cameraXConfig

The configuration options to configure the lifecycle camera provider. If not set, the default configuration will be used.

Returns
@NonNull LifecycleCameraProvider

The lifecycle camera provider instance.

createInstanceAsync

Added in 1.5.0-beta01
default static final @NonNull ListenableFuture<@NonNull LifecycleCameraProvidercreateInstanceAsync(
    @NonNull Context context,
    CameraXConfig cameraXConfig
)

Creates a lifecycle camera provider instance asynchronously.

Parameters
@NonNull Context context

The Application context.

CameraXConfig cameraXConfig

The configuration options to configure the lifecycle camera provider. If not set, the default configuration will be used.

Returns
@NonNull ListenableFuture<@NonNull LifecycleCameraProvider>

A ListenableFuture that will be completed when the lifecycle camera provider instance is initialized.

isBound

Added in 1.5.0-beta01
abstract boolean isBound(@NonNull UseCase useCase)

Returns true if this UseCase is bound to a lifecycle or included in a bound SessionConfig. Otherwise returns false.

After binding a use case, use cases remain bound until the lifecycle reaches a Lifecycle.State.DESTROYED state or if is unbound by calls to unbind or unbindAll.

unbind

Added in 1.5.0-beta01
abstract void unbind(UseCase useCases)

Unbinds all specified use cases from the lifecycle provider.

This will initiate a close of every open camera which has zero UseCase associated with it at the end of this call.

If a use case in the argument list is not bound, then it is simply ignored.

After unbinding a UseCase, the UseCase can be bound to another Lifecycle however listeners and settings should be reset by the application.

Parameters
UseCase useCases

The collection of use cases to remove.

Throws
kotlin.IllegalStateException

If not called on main thread.

kotlin.UnsupportedOperationException

If called in concurrent mode.

unbindAll

Added in 1.5.0-beta01
abstract void unbindAll()

Unbinds all use cases from the lifecycle provider and removes them from CameraX.

This will initiate a close of every currently open camera.

Throws
kotlin.IllegalStateException

If not called on main thread.