CameraState

@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 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 the CLOSED state .
  • If the error is recoverable, CameraX will attempt to reopen the camera device. If a recovery attempt succeeds, the camera state moves to the OPEN state, however, if all recovery attempts are unsuccessful, the camera waits in a PENDING_OPEN state 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 CLOSING state.

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.
@AutoValue
public abstract class CameraState.StateError

Error that the camera has encountered.
public enum CameraState.Type

States the camera can be in.

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

Public constructors

Public methods
static @NonNull CameraState

Create a new CameraState instance from a Type and a nullStateError.
static @NonNull CameraState

Create a new CameraState instance from a Type and a potential StateError.
abstract @Nullable CameraState.StateError

Potentially returns an error the camera encountered.
abstract @NonNull CameraState.Type

Returns the camera's state.

Constants

ERROR_CAMERA_DISABLED

Added in 1.1.0
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.

See also
setCameraDisabled

ERROR_CAMERA_FATAL_ERROR

Added in 1.1.0
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

Added in 1.1.0
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_DO_NOT_DISTURB_MODE_ENABLED

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
public static final int ERROR_STREAM_CONFIG = 4

An error indicating that configuring the camera has failed.

Public constructors

CameraState

Added in 1.1.0
public CameraState()

Public methods

create

Added in 1.1.0
public static @NonNull CameraState create(@NonNull CameraState.Type type)

Create a new CameraState instance from a Type and a nullStateError.

A CameraState is not expected to be instantiated in normal operation.

create

Added in 1.1.0
public static @NonNull CameraState create(
    @NonNull CameraState.Type type,
    @Nullable CameraState.StateError error
)

Create a new CameraState instance from a Type and a potential StateError.

A CameraState is not expected to be instantiated in normal operation.

getError

Added in 1.1.0
public abstract @Nullable CameraState.StateError getError()

Potentially returns an error the camera encountered.

Returns
@Nullable CameraState.StateError

An error the camera encountered, or null otherwise.

getType

Added in 1.1.0
public abstract @NonNull CameraState.Type getType()

Returns the camera's state.

Returns
@NonNull CameraState.Type

The camera's state