CameraState
@AutoValue
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
Nested types |
|---|
|
Types of errors the camera can encounter. |
@AutoValueError that the camera has encountered. |
enum CameraState.TypeStates the camera can be in. |
Constants |
|
|---|---|
const Int |
An error indicating that the camera device could not be opened due to a device policy. |
const Int |
An error indicating that the camera device was closed due to a fatal error. |
const Int |
An error indicating that the camera device is already in use. |
const Int |
An error indicating that the camera device is no longer available because it has been removed from the system. |
const 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). |
const 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. |
const Int |
An error indicating that the camera device has encountered a recoverable error. |
const Int |
An error indicating that configuring the camera has failed. |
Public constructors |
|---|
Public functions |
|
|---|---|
java-static CameraState |
create(type: CameraState.Type)Create a new |
java-static CameraState |
create(type: CameraState.Type, error: CameraState.StateError?)Create a new |
abstract CameraState.StateError? |
getError()Potentially returns an error the camera encountered. |
abstract CameraState.Type |
getType()Returns the camera's state. |
Constants
ERROR_CAMERA_DISABLED
const val ERROR_CAMERA_DISABLED = 5: Int
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.
| See also | |
|---|---|
setCameraDisabled |
ERROR_CAMERA_FATAL_ERROR
const val ERROR_CAMERA_FATAL_ERROR = 6: Int
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
const val ERROR_CAMERA_IN_USE = 2: Int
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
const val ERROR_CAMERA_REMOVED = 8: Int
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
const val ERROR_DO_NOT_DISTURB_MODE_ENABLED = 7: 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).
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
const val ERROR_MAX_CAMERAS_IN_USE = 1: 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.
ERROR_OTHER_RECOVERABLE_ERROR
const val ERROR_OTHER_RECOVERABLE_ERROR = 3: Int
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
const val ERROR_STREAM_CONFIG = 4: Int
An error indicating that configuring the camera has failed.
Public constructors
Public functions
create
java-static fun create(type: CameraState.Type): CameraState
Create a new CameraState instance from a Type and a nullStateError.
A CameraState is not expected to be instantiated in normal operation.
create
java-static fun create(type: CameraState.Type, error: CameraState.StateError?): CameraState
Create a new CameraState instance from a Type and a potential StateError.
A CameraState is not expected to be instantiated in normal operation.
getError
abstract fun getError(): CameraState.StateError?
Potentially returns an error the camera encountered.
| Returns | |
|---|---|
CameraState.StateError? |
An error the camera encountered, or |
getType
abstract fun getType(): CameraState.Type
Returns the camera's state.
| Returns | |
|---|---|
CameraState.Type |
The camera's state |