CameraX

public final class CameraX
extends Object

java.lang.Object
   ↳ androidx.camera.core.CameraX

Main interface for accessing CameraX library.

This is a singleton class responsible for managing the set of camera instances and attached use cases (such as Preview, ImageAnalysis, or ImageCapture. Use cases are bound to a LifecycleOwner by calling bindToLifecycle(LifecycleOwner, UseCase) Once bound, the lifecycle of the LifecycleOwner determines when the camera is started and stopped, and when camera data is available to the use case.

It is often sufficient to just bind the use cases once when the activity is created, and let the lifecycle handle the rest, so application code generally does not need to call unbind(UseCase) nor call bindToLifecycle(LifecycleOwner, UseCase...) more than once.

A lifecycle transition from Lifecycle.State.CREATED to Lifecycle.State.STARTED state (via Lifecycle.Event.ON_START) initializes the camera asynchronously on a CameraX managed thread. After initialization, the camera is opened and a camera capture session is created. If a Preview or ImageAnalysis is bound, those use cases will begin to receive camera data after initialization completes. ImageCapture can receive data via specific calls (such as ImageCapture.takePicture(File, ImageCapture.Metadata, Executor, ImageCapture.OnImageSavedListener)) after initialization completes. Calling bindToLifecycle(LifecycleOwner, UseCase...) with no Use Cases does nothing.

Binding to a LifecycleOwner when the state is Lifecycle.State.STARTED or greater will also initialize and start data capture as though an Lifecycle.Event.ON_START transition had occurred. If the camera was already running this may cause a new initialization to occur, temporarily stopping data from the camera before restarting it.

After a lifecycle transition from Lifecycle.State.STARTED to Lifecycle.State.CREATED state (via Lifecycle.Event.ON_STOP), use cases will no longer receive camera data. The camera capture session is destroyed and the camera device is closed. Use cases can remain bound and will become active again on the next Lifecycle.Event.ON_START transition.

When the lifecycle transitions from Lifecycle.State.CREATED to the Lifecycle.State.DESTROYED state (via Lifecycle.Event.ON_DESTROY) any bound use cases are unbound and use case resources are freed. Calls to bindToLifecycle(LifecycleOwner, UseCase...) when the lifecycle is in the Lifecycle.State.DESTROYED state will fail. A call to bindToLifecycle(LifecycleOwner, UseCase...) will need to be made with another lifecycle to rebind the UseCase that has been unbound.

If the camera is not already closed, unbinding all use cases will cause the camera to close asynchronously. 

public void setup() {
   // Initialize UseCase
   useCase = ...;

   // UseCase binding event
   CameraX.bindToLifecycle(lifecycleOwner, useCase);

   // Make calls on useCase
 }

 public void operateOnUseCase() {
   if (CameraX.isBound(useCase)) {
     // Make calls on useCase
   }
 }

 public void prematureTearDown() {
   // Not required since the lifecycle automatically stops the use case.  Can be used to
   // disassociate use cases from the lifecycle to move a use case to a different lifecycle.
   CameraX.unbindAll();
 }

All operations on a use case, including binding and unbinding, should be done on the main thread. This is because lifecycle events are triggered on main thread and so accessing the use case on the main thread guarantees that lifecycle state changes will not occur during execution of a method call or binding/unbinding.

Summary

Nested classes

enum CameraX.ErrorCode

The types of error states that can occur. 

interface CameraX.ErrorListener

Listener called whenever an error condition occurs within CameraX. 

enum CameraX.LensFacing

The direction the camera faces relative to device screen. 

Public methods

static void bindToLifecycle(LifecycleOwner lifecycleOwner, UseCase... useCases)

Binds the collection of UseCase to a LifecycleOwner.

static CameraControl getCameraControl(CameraX.LensFacing lensFacing)

Returns the camera control for the camera with the given lens facing.

static CameraInfo getCameraInfo(CameraX.LensFacing lensFacing)

Returns the camera info for the camera with the given lens facing.

static boolean hasCameraWithLensFacing(CameraX.LensFacing lensFacing)

Checks if the device supports specified lens facing.

static boolean isBound(UseCase useCase)

Returns true if the UseCase is bound to a lifecycle.

static void setErrorListener(CameraX.ErrorListener errorListener, Handler handler)

Sets an CameraX.ErrorListener which will get called any time a CameraX specific error is encountered.

static void unbind(UseCase... useCases)

Unbinds all specified use cases from the lifecycle.

static void unbindAll()

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

Inherited methods

Public methods

bindToLifecycle

public static void bindToLifecycle (LifecycleOwner lifecycleOwner, 
                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, 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 at a time. Attempting to bind a UseCase to a Lifecycle when it is already bound to another Lifecycle is an error, and the UseCase binding will not change.

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.
useCases UseCase: The use cases to bind to a lifecycle.
Throws
IllegalStateException If the use case has already been bound to another lifecycle or method is not called on main thread.

getCameraControl

public static CameraControl getCameraControl (CameraX.LensFacing lensFacing)

Returns the camera control for the camera with the given lens facing.

Parameters
lensFacing CameraX.LensFacing: the lens facing of the camera
Returns
CameraControl the CameraControl.
Throws
CameraInfoUnavailableException if unable to access cameras, perhaps due to insufficient permissions.

getCameraInfo

public static CameraInfo getCameraInfo (CameraX.LensFacing lensFacing)

Returns the camera info for the camera with the given lens facing.

Parameters
lensFacing CameraX.LensFacing: the lens facing of the camera
Returns
CameraInfo the camera info if it can be retrieved for the given lens facing.
Throws
CameraInfoUnavailableException if unable to access cameras, perhaps due to insufficient permissions.

hasCameraWithLensFacing

public static boolean hasCameraWithLensFacing (CameraX.LensFacing lensFacing)

Checks if the device supports specified lens facing.

Parameters
lensFacing CameraX.LensFacing: the lens facing
Returns
boolean true if the device has at least one camera with the specified lens facing, otherwise false.
Throws
CameraInfoUnavailableException if unable to access cameras, perhaps due to insufficient permissions

isBound

public static 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, 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

setErrorListener

public static void setErrorListener (CameraX.ErrorListener errorListener, 
                Handler handler)

Sets an CameraX.ErrorListener which will get called any time a CameraX specific error is encountered.

Parameters
errorListener CameraX.ErrorListener: the listener which will get all the error messages. If this is set to null then the default error listener will be set.
handler Handler: the handler for the thread to run the error handling on. If this is set to null then it will default to run on the main thread.

unbind

public static 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 static 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.