ProcessCameraProvider
public
final
class
ProcessCameraProvider
extends Object
java.lang.Object | |
↳ | androidx.camera.lifecycle.ProcessCameraProvider |
A singleton which can be used to bind the lifecycle of cameras 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(LifecycleOwner lifecycleOwner, CameraSelector cameraSelector, UseCase... useCases)
Binds the collection of |
Camera
|
bindToLifecycle(LifecycleOwner lifecycleOwner, CameraSelector cameraSelector, UseCaseGroup useCaseGroup)
Binds a |
static
void
|
configureInstance(CameraXConfig cameraXConfig)
Perform one-time configuration of the |
List<CameraInfo>
|
getAvailableCameraInfos()
|
static
ListenableFuture<ProcessCameraProvider>
|
getInstance(Context context)
Retrieves the |
boolean
|
hasCamera(CameraSelector cameraSelector)
|
boolean
|
isBound(UseCase useCase)
Returns true if the |
void
|
unbind(UseCase... useCases)
Unbinds all specified use cases from the lifecycle. |
void
|
unbindAll()
Unbinds all use cases from the lifecycle and removes them from CameraX. |
Inherited methods | |
---|---|
Public methods
bindToLifecycle
public Camera bindToLifecycle (LifecycleOwner lifecycleOwner, 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
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.
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. |
Returns | |
---|---|
Camera |
The Camera instance which is determined by the camera selector and
internal requirements. |
Throws | |
---|---|
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. |
bindToLifecycle
public Camera bindToLifecycle (LifecycleOwner lifecycleOwner, CameraSelector cameraSelector, UseCaseGroup useCaseGroup)
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
UseCase
s.
If one UseCase
is in multiple UseCaseGroup
s, it will be linked to
the UseCaseGroup
in the latest
bindToLifecycle(LifecycleOwner, CameraSelector, UseCaseGroup)
call.
Parameters | |
---|---|
lifecycleOwner |
LifecycleOwner |
cameraSelector |
CameraSelector |
useCaseGroup |
UseCaseGroup |
Returns | |
---|---|
Camera |
configureInstance
public static void configureInstance (CameraXConfig cameraXConfig)
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 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
. 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 : configuration options for the singleton process camera provider
instance. |
Throws | |
---|---|
IllegalStateException |
if the camera provider has already been configured by a
previous call to configureInstance() or
getInstance(Context) .
|
getInstance
public static ListenableFuture<ProcessCameraProvider> getInstance (Context context)
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.
class MyCustomizedCameraProvider {
private static boolean configured = false;
static ListenableFuture<ProcessCameraProvider> 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);
}
}
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.
Parameters | |
---|---|
context |
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.getCause() . The cause will be
a CameraUnavailableException if it fails to access any camera
during initialization. |
Throws | |
---|---|
IllegalStateException |
if CameraX fails to initialize via a default provider or a CameraXConfig.Provider. |
See also:
hasCamera
public boolean hasCamera (CameraSelector cameraSelector)
Parameters | |
---|---|
cameraSelector |
CameraSelector |
Returns | |
---|---|
boolean |
Throws | |
---|---|
CameraInfoUnavailableException |
isBound
public boolean isBound (UseCase useCase)
Returns true if the UseCase
is bound to a lifecycle. Otherwise returns false.
After binding a use case with bindToLifecycle(LifecycleOwner, CameraSelector, UseCase...)
, use cases remain bound until the
lifecycle reaches a Lifecycle.State.DESTROYED
state or if is unbound by calls to
unbind(UseCase)
or unbindAll()
.
Parameters | |
---|---|
useCase |
UseCase |
Returns | |
---|---|
boolean |
unbind
public void unbind (UseCase... useCases)
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.
Parameters | |
---|---|
useCases |
UseCase : The collection of use cases to remove. |
Throws | |
---|---|
IllegalStateException |
If not called on main thread. |
unbindAll
public void unbindAll ()
Unbinds all use cases from the lifecycle and removes them from CameraX.
This will initiate a close of every currently open camera.
Throws | |
---|---|
IllegalStateException |
If not called on main thread. |