ProcessCameraProvider

class ProcessCameraProvider : LifecycleCameraProvider
kotlin.Any
   ↳ androidx.camera.lifecycle.ProcessCameraProvider

A LifecycleCameraProvider which can be used to bind to any LifecycleOwner within an application's process.

Only a single process camera provider can exist within a process, and it can be retrieved with getInstance(Context).

Heavyweight resources, such as open and running camera devices, will be scoped to the lifecycle provided to bindToLifecycle(LifecycleOwner, CameraSelector, UseCase...). Other lightweight resources, such as static camera characteristics, may be retrieved and cached upon first retrieval of this provider with getInstance(Context), and will persist for the lifetime of the process.

This is the standard provider for applications to use.

Summary

Public methods

Camera
bindToLifecycle(@NonNull lifecycleOwner: LifecycleOwner, @NonNull cameraSelector: CameraSelector, @NonNull vararg useCases: UseCase!)

Binds the collection of UseCase to a LifecycleOwner.

static ListenableFuture<ProcessCameraProvider!>
getInstance(@NonNull context: Context)

Retrieves the LifecycleCameraProvider associated with the current process.

Boolean
hasCamera(@NonNull cameraSelector: CameraSelector)

Boolean
isBound(@NonNull useCase: UseCase)

Unit
unbind(@NonNull vararg useCases: UseCase!)

Unit

Public methods

bindToLifecycle

@NonNull fun bindToLifecycle(
    @NonNull lifecycleOwner: LifecycleOwner,
    @NonNull cameraSelector: CameraSelector,
    @NonNull 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(List, * android.hardware.camera2.CameraCaptureSession.StateCallback, Handler).

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.

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

Parameters
lifecycleOwner LifecycleOwner: The lifecycleOwner which controls the lifecycle transitions of the use cases.
cameraSelector CameraSelector: The camera selector which determines the camera to use for set of use cases.
useCases UseCase!: The use cases to bind to a lifecycle.
Return
Camera: The Camera instance which is determined by the camera selector.
Exceptions
IllegalStateException If the use case has already been bound to another lifecycle or method is not called on main thread.
IllegalArgumentException If the provided camera selector is unable to resolve a camera to be used for the given use cases.

getInstance

@NonNull static fun getInstance(@NonNull context: Context): ListenableFuture<ProcessCameraProvider!>

Retrieves the LifecycleCameraProvider associated with the current process.

The instance returned here can be used to bind use cases to any LifecycleOwner with bindToLifecycle(LifecycleOwner, CameraSelector, UseCase...).

The instance must be initialized by subclassing the application's Application class and implementing CameraXConfig.Provider. For example, the following will initialize this process camera provider with a Camera2 implementation from androidx.camera.camera2.

public class MyApplication extends Application implements CameraXConfig.Provider {
          @Override
          public CameraXConfig getCameraXConfig() {
              return Camera2Config.defaultConfig(Application.this);
          }
     
          . . .
      }
      
Return
ListenableFuture<ProcessCameraProvider!>: A future which will contain the ProcessCameraProvider. Cancellation of this future is a no-op.
Exceptions
IllegalStateException if no CameraXConfig has been provided by the application.

hasCamera

fun hasCamera(@NonNull cameraSelector: CameraSelector): Boolean

isBound

fun isBound(@NonNull useCase: UseCase): Boolean

unbind

fun unbind(@NonNull vararg useCases: UseCase!): Unit

unbindAll

fun unbindAll(): Unit