@AutoValue
public abstract class CameraState
Represents the different states the camera can be in.
The following table displays the states the camera can be in, and the possible transitions between them.
| State | Transition cause | New State |
|---|---|---|
| CLOSED | Received signal to open camera, and camera unavailable | PENDING_OPEN |
| Received signal to open camera, and camera available | OPENING | |
| PENDING_OPEN | Received signal that camera is available | OPENING |
| OPENING | Camera opened successfully | OPEN |
| Camera encountered recoverable error while opening | OPENING(Error) | |
| Camera encountered critical error while opening | CLOSING(Error) | |
| Camera opening failed prematurely | CLOSED(Error) | |
| Reached max limit of camera (re)open attempts | PENDING_OPEN | |
| OPEN | Camera encountered recoverable error | OPENING(Error) |
| Camera encountered critical error | CLOSING(Error) | |
| Received signal to close camera | CLOSING | |
| CLOSING | Camera closed | CLOSED |
Initially, a camera is in a CLOSED state. When it receives a signal to open, for example after one or multiple use cases are attached to it, its state moves to the OPENING state. If it successfully opens the camera device, its state moves to the OPEN state, otherwise, it may move to a different state depending on the error it encountered:
- If the camera is physically removed (e.g. a USB camera is unplugged), its state will move directly to
CLOSEDwith anERROR_CAMERA_REMOVEDerror. - If opening the camera device fails prematurely, for example, when "Do Not Disturb" mode is enabled on a device that's affected by a bug in Android 9 (see
ERROR_DO_NOT_DISTURB_MODE_ENABLED), the state moves to theCLOSEDstate . - If the error is recoverable, CameraX will attempt to reopen the camera device. If a recovery attempt succeeds, the camera state moves to the
OPENstate, however, if all recovery attempts are unsuccessful, the camera waits in aPENDING_OPENstate to attempt recovery again once the camera device's availability changes. - If the error is critical, and requires the intervention of the developer or user, the camera's state moves to the
CLOSINGstate.
While in the PENDING_OPEN state, the camera waits for a signal indicating the camera device's availability. The signal can either be an external one from the camera service, or an internal one from within CameraX. When received, the camera's state moves to the OPENING state, and an attempt to open the camera device is made.
While in the OPEN state, the camera device may be disconnected due to an error. In this case, depending on whether the error is critical or recoverable, CameraX may or may not attempt to recover from it, thus the state will move to either a CLOSING or OPENING state.
If the camera is in an OPEN state and receives a signal to close the camera device, for example when all its previously attached use cases are detached, its state moves to the CLOSING state. Once the camera device finishes closing, the camera state moves to the CLOSED state.
Whenever the camera encounters an error, it reports it through getError.
Summary
Constants |
|
|---|---|
static final int |
An error indicating that the camera device could not be opened due to a device policy. |
static final int |
An error indicating that the camera device was closed due to a fatal error. |
static final int |
An error indicating that the camera device is already in use. |
static final int |
An error indicating that the camera device is no longer available because it has been removed from the system. |
static final int |
An error indicating that the camera could not be opened because "Do Not Disturb" mode is enabled on devices affected by a bug in Android 9 (API level 28). |
static final int |
An error indicating that the limit number of open cameras has been reached, and more cameras cannot be opened until other instances are closed. |
static final int |
An error indicating that the camera device has encountered a recoverable error. |
static final int |
An error indicating that configuring the camera has failed. |
Constants
ERROR_CAMERA_DISABLED
public static final int ERROR_CAMERA_DISABLED = 5
An error indicating that the camera device could not be opened due to a device policy.
The error may be encountered if a client from a background process attempts to open the camera.
ERROR_CAMERA_FATAL_ERROR
public static final int ERROR_CAMERA_FATAL_ERROR = 6
An error indicating that the camera device was closed due to a fatal error.
The error may require the Android device to be shut down and restarted to restore camera function. It may also indicate the existence of a persistent camera hardware problem. When CameraX uses a android.hardware.camera2 implementation, this error represents a ERROR_CAMERA_SERVICE error.
ERROR_CAMERA_IN_USE
public static final int ERROR_CAMERA_IN_USE = 2
An error indicating that the camera device is already in use.
This could be due to the camera device being used by a higher-priority camera client.
ERROR_CAMERA_REMOVED
public static final int ERROR_CAMERA_REMOVED = 8
An error indicating that the camera device is no longer available because it has been removed from the system.
This error will be reported when a camera is disconnected from the host device (e.g., a USB camera is unplugged). This is a terminal state for the camera session. Once this error is received, the associated Camera and CameraInfo objects are no longer valid. Attempting to call methods on them may result in exceptions.
Action: The application should unbind all use cases from the invalid camera and switch to another available camera. To find a new camera, use getAvailableCameraInfos or hasCamera.
This error is considered critical, and CameraX will not attempt to recover.
ERROR_DO_NOT_DISTURB_MODE_ENABLED
public static final int ERROR_DO_NOT_DISTURB_MODE_ENABLED = 7
An error indicating that the camera could not be opened because "Do Not Disturb" mode is enabled on devices affected by a bug in Android 9 (API level 28).
When "Do Not Disturb" mode is enabled, opening the camera device fails on certain Android devices running on an early Android 9 release with a INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY camera hardware level.
CameraX will not attempt to reopen the camera device, instead, disable the "Do Not Disturb" mode, then explicitly open the camera again.
ERROR_MAX_CAMERAS_IN_USE
public static final int ERROR_MAX_CAMERAS_IN_USE = 1
An error indicating that the limit number of open cameras has been reached, and more cameras cannot be opened until other instances are closed.
ERROR_OTHER_RECOVERABLE_ERROR
public static final int ERROR_OTHER_RECOVERABLE_ERROR = 3
An error indicating that the camera device has encountered a recoverable error.
CameraX will attempt to recover from the error, it if succeeds in doing so, the camera will open, otherwise the camera will move to a PENDING_OPEN state. When CameraX uses a android.hardware.camera2 implementation, this error represents a ERROR_CAMERA_DEVICE error.
ERROR_STREAM_CONFIG
public static final int ERROR_STREAM_CONFIG = 4
An error indicating that configuring the camera has failed.