ProcessCameraProvider

bindToLifecycle

@MainThread @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.

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.

bindToLifecycle

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

Binds a UseCaseGroup to a LifecycleOwner.

Similar to bindToLifecycle(LifecycleOwner, CameraSelector, UseCase[]), 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(LifecycleOwner, CameraSelector, UseCaseGroup) call.

configureInstance

static fun configureInstance(@NonNull cameraXConfig: CameraXConfig): Unit

Perform one-time configuration of the ProcessCameraProvider singleton with the given CameraXConfig.

This method allows configuration of the camera provider via CameraXConfig. All initialization tasks, such as communicating with the camera service, will be executed on the java.util.concurrent.Executor set by CameraXConfig.Builder#setCameraExecutor(Executor), or by an internally defined executor if none is provided.

Once this method is called, the instance can be retrieved with getInstance(Context) without the need for implementing CameraXConfig.Provider in Application.

Configuration can only occur once. Once the ProcessCameraProvider has been configured with configureInstance() or getInstance(Context), this method will throw an IllegalStateException.

getInstance

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

Retrieves the ProcessCameraProvider 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's configuration may be customized 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, and with a custom executor.

public class MyApplication extends Application implements CameraXConfig.Provider {
          @Override
          public CameraXConfig getCameraXConfig() {
              return CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
                         .setCameraExecutor(myExecutor)
                         .setSchedulerHandler(mySchedulerHandler)
                         .build();
          }
     
          . . .
      }
      

If it isn't possible to subclass the Application class, such as in library code, then the singleton can be configured via configureInstance(CameraXConfig) before the first invocation of getInstance(context), as in the following example.

<code>class MyCustomizedCameraProvider {
     
          private static boolean configured = false;
     
          static ListenableFuture&lt;ProcessCameraProvider&gt; getInstance(Context context) {
              synchronized(MyCustomizedCameraProvider.class) {
                  if (!configured) {
                      configured = true;
                      ProcessCameraProvider.configureInstance(
                          CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
                                .setCameraExecutor(myExecutor)
                                .setSchedulerHandler(mySchedulerHandler)
                                .build());
                  }
              }
              return ProcessCameraProvider.getInstance(context);
          }
      }
      </code>

If no CameraXConfig.Provider is implemented by Application, or if the singleton has not been configured via configureInstance(CameraXConfig) a default configuration will be used.

hasCamera

fun hasCamera(@NonNull cameraSelector: CameraSelector): Boolean

isBound

fun isBound(@NonNull useCase: UseCase): Boolean

Returns true if the UseCase is bound to a lifecycle. Otherwise returns false.

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

unbind

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

Unbinds all specified use cases from the lifecycle.

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 and bound to another Lifecycle however listeners and settings should be reset by the application.

unbindAll

@MainThread fun unbindAll(): Unit

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

This will initiate a close of every currently open camera.