ProcessCameraProvider.Companion

object ProcessCameraProvider.Companion

Summary

Public functions
Unit

Perform one-time configuration of the ProcessCameraProvider singleton with the given CameraXConfig.
ListenableFuture<ProcessCameraProvider>
getInstance(context: Context)

Retrieves the ProcessCameraProvider associated with the current process.

Extension functions
suspend ProcessCameraProvider

Retrieves the ProcessCameraProvider.

Public functions

configureInstance

Added in 1.4.0
@ExperimentalCameraProviderConfiguration
fun configureInstance(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, or by an internally defined executor if none is provided.

This method is not required for every application. If the method is not called and CameraXConfig.Provider is not implemented in Application, default configuration will be used.

Once this method is called, the instance configured by the given CameraXConfig can be retrieved with getInstance. CameraXConfig.Provider implemented in Application will be ignored.

Configuration can only occur once. Once the ProcessCameraProvider has been configured with configureInstance() or getInstance, this method will throw an IllegalStateException. Because configuration can only occur once, usage of this method from library code is not recommended as the application owner should ultimately be in control of singleton configuration.

Parameters
cameraXConfig: CameraXConfig

The configuration options for the singleton process camera provider instance.
Throws
kotlin.IllegalStateException

If the camera provider has already been configured by a previous call to configureInstance() or getInstance.

getInstance

Added in 1.4.0
fun getInstance(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.

The instance's configuration may be customized by subclassing the application's Application class and implementing CameraXConfig.Provider. For example, the sample implements CameraXConfig.Provider.getCameraXConfig and initializes this process camera provider with a Camera2 implementation from androidx.camera.camera2, and with a custom executor.

import androidx.camera.camera2.Camera2Config
import androidx.camera.core.CameraXConfig

@Override
fun getCameraXConfig(): CameraXConfig {
    return CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
        .setCameraExecutor(executor)
        .setSchedulerHandler(scheduleHandler)
        .build()
}

If it isn't possible to subclass the Application class, such as in library code, then the singleton can be configured via configureInstance before the first invocation of getInstance(context), the sample implements a customized camera provider that configures the instance before getting it.

import androidx.camera.camera2.Camera2Config
import androidx.camera.core.CameraProvider
import androidx.camera.core.CameraXConfig
import androidx.camera.lifecycle.ProcessCameraProvider
import androidx.camera.lifecycle.ProcessCameraProvider.Companion.configureInstance

fun getInstance(context: Context): ListenableFuture<ProcessCameraProvider> {
    synchronized(CameraProvider::class.java) {
        if (!configured) {
            configured = true
            configureInstance(
                CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
                    .setCameraExecutor(executor)
                    .setSchedulerHandler(scheduleHandler)
                    .build()
            )
        }
    }
    return ProcessCameraProvider.getInstance(context)
}

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

Parameters
context: Context

The application context.
Returns
ListenableFuture<ProcessCameraProvider>

A future which will contain the ProcessCameraProvider. Cancellation of this future is a no-op. This future may fail with an InitializationException and associated cause that can be retrieved by Throwable.cause. The cause will be a androidx.camera.core.CameraUnavailableException if it fails to access any camera during initialization.
Throws
kotlin.IllegalStateException

if CameraX fails to initialize via a default provider or a CameraXConfig.Provider.
See also
configureInstance

Extension functions

awaitInstance

suspend fun ProcessCameraProvider.Companion.awaitInstance(context: Context): ProcessCameraProvider

Retrieves the ProcessCameraProvider.

This is a suspending function unlike ProcessCameraProvider.getInstance which returns a com.google.common.util.concurrent.ListenableFuture.

Parameters
context: Context

The application context.
Returns
ProcessCameraProvider

A fully initialized ProcessCameraProvider for the current process.
Throws
androidx.camera.core.InitializationException

If failed to retrieve the ProcessCameraProvider, use InitializationException.cause to get the error cause.
See also
getInstance