LifecycleCameraProvider

suspend fun createInstance(context: Context, cameraXConfig: CameraXConfig? = null): LifecycleCameraProvider

Creates a lifecycle camera provider instance.

fun createInstanceAsync(context: Context, cameraXConfig: CameraXConfig? = null): ListenableFuture<LifecycleCameraProvider>

Creates a lifecycle camera provider instance asynchronously.

fun bindToLifecycle(
    singleCameraConfigs: List<ConcurrentCamera.SingleCameraConfig?>
): ConcurrentCamera

Binds list of SingleCameraConfigs to LifecycleOwner.

This function only supports combinations that are available via availableConcurrentCameraInfos. If the input list of SingleCameraConfigs does not match any of the supported combinations returned by availableConcurrentCameraInfos, IllegalArgumentException will be thrown. If cameras are already used by other UseCases, UnsupportedOperationException will be thrown.

To set up concurrent 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 camera can have its own UseCases and LifecycleOwner. See {@docRoot}training/camerax/architecture#lifecycles

There are two modes:

1. Non-Composition mode: These SingleCameraConfigs have different preview and video capture use cases and there is no androidx.camera.core.CompositionSettings. In this mode, these previews and video captures can stream separately. CameraX doesn't perform any composition. You can also bind an extra image capture along with the preview and the video capture use cases.

2. Composition mode: If the concurrent cameras are binding the same instances of preview and video capture use cases, the concurrent cameras video recording is supported. The concurrent camera preview stream will be shared with video capture and record the concurrent cameras streams as a composited stream. The androidx.camera.core.CompositionSettings can be used to configure the position of each camera stream and different layouts can be built. See androidx.camera.core.CompositionSettings for more details. The composition settings can also be updated dynamically by invoking androidx.camera.core.ConcurrentCamera.setCompositionSettings. The composition mode only supports preview and video capture. ImageCapture is currently not supported. androidx.camera.core.CameraEffect can be applied on the composited stream. However, the mirrorMode of VideoCapture will be ignored. This means the recorded video will have the same mirrorMode as the preview.

fun bindToLifecycle(
    lifecycleOwner: LifecycleOwner,
    cameraSelector: CameraSelector,
    sessionConfig: SessionConfig
): Camera

Binds a SessionConfig to a LifecycleOwner.

A SessionConfig encapsulates the configuration required for a camera session. This includes:

• A collection of UseCase instances defining the desired camera functionality.

• Session parameters to be applied to the camera.

• Common properties such as the field-of-view defined by androidx.camera.core.ViewPort.

• androidx.camera.core.CameraEffects to be applied for image processing.

The state of the lifecycle will determine when the cameras are open, started, stopped and closed. When started, the use cases contained in the given SessionConfig receive camera data and the parameters of SessionConfig are used for configuring the camera including common field of view, effects and the session parameters.

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.

Updates the SessionConfig for a given LifecycleOwner by invoking bindToLifecycle again with the new SessionConfig. There is no need to call unbind or unbindAll; the previous SessionConfig and its associated UseCases will be implicitly unbound. This behavior also applies when rebinding to the same LifecycleOwner with a different CameraSelector, such as when switching the camera's lens facing.

Important Restrictions:

• You cannot bind a SessionConfig to a LifecycleOwner that already has individual UseCases or a UseCaseGroup bound to it.

• A SessionConfig bound to a LifecycleOwner cannot contain UseCases that are already bound to a different LifecycleOwner.

Violating these restrictions will result in an IllegalStateException.

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.

import androidx.camera.core.CameraSelector
import androidx.camera.core.ImageCapture
import androidx.camera.core.Preview
import androidx.camera.core.SessionConfig

val preview =
    Preview.Builder().build().also { it.surfaceProvider = previewView.surfaceProvider }
val imageCapture = ImageCapture.Builder().build()
val sessionConfig =
    SessionConfig(
        useCases = listOf(preview, imageCapture),
        viewPort = previewView.getViewPort(preview.getTargetRotation()),
        effects = listOf(effect1),
    )
// Starts the camera with the given effect and viewPort when the lifecycleOwner is started.
cameraProvider.bindToLifecycle(
    lifecycleOwner,
    CameraSelector.DEFAULT_BACK_CAMERA,
    sessionConfig,
)

// To apply a different effect, unbind the previous SessionConfig and bind the new SessionConfig
// with the new effect.
val sessionConfigNewEffect =
    SessionConfig(
        useCases = listOf(preview, imageCapture),
        viewPort = previewView.getViewPort(preview.getTargetRotation()),
        effects = listOf(effect2),
    )
// Make sures to unbind the previous sessionConfig before binding the new one
cameraProvider.unbind(sessionConfig)
cameraProvider.bindToLifecycle(
    lifecycleOwner,
    CameraSelector.DEFAULT_BACK_CAMERA,
    sessionConfigNewEffect,
)

fun bindToLifecycle(
    lifecycleOwner: LifecycleOwner,
    cameraSelector: CameraSelector,
    useCaseGroup: UseCaseGroup
): Camera

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.

fun bindToLifecycle(
    lifecycleOwner: LifecycleOwner,
    cameraSelector: CameraSelector,
    vararg useCases: UseCase?
): Camera

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.

Binding different use cases to the same lifecycle with different camera selectors that resolve to distinct cameras is an error, resulting in an exception.

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.

fun isBound(sessionConfig: SessionConfig): Boolean

Returns true if the exact same instance of SessionConfig is bound to a lifecycle, false otherwise.

After binding a SessionConfig, this SessionConfig remains bound until the lifecycle reaches a Lifecycle.State.DESTROYED state or if is unbound by calls to unbind or unbindAll.

fun isBound(useCase: UseCase): Boolean

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

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.

fun unbind(sessionConfig: SessionConfig): Unit

Unbinds the specified SessionConfig instance from the lifecycle provider.

This method will only unbind the session if the provided sessionConfig is the exact same instance that was previously used for binding.

This SessionConfig contains the UseCases to be detached from the camera. This will initiate a close of every open camera which has zero UseCase associated with it at the end of this call.

After unbinding the SessionConfig, another SessionConfig can be bound again and its UseCases can be bound to another Lifecycle.

fun unbind(vararg useCases: UseCase?): Unit

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.

fun unbindAll(): Unit

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

This will initiate a close of every currently open camera.