CameraState

public abstract class CameraState
extends Object

java.lang.Object
   ↳ androidx.camera.core.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 CameraState.Type.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 CameraState.Type.OPENING state. If it successfully opens the camera device, its state moves to the CameraState.Type.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 CameraState.Type.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 CameraState.Type.OPEN state, however, if all recovery attempts are unsuccessful, the camera waits in a CameraState.Type.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 CameraState.Type.CLOSING state.

While in the CameraState.Type.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 CameraState.Type.OPENING state, and an attempt to open the camera device is made.

While in the CameraState.Type.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 CameraState.Type.CLOSING or CameraState.Type.OPENING state.

If the camera is in an CameraState.Type.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 CameraState.Type.CLOSING state. Once the camera device finishes closing, the camera state moves to the CameraState.Type.CLOSED state.

Whenever the camera encounters an error, it reports it through getError().

Summary

Nested classes

enum CameraState.ErrorType

Types of errors the camera can encounter. 

class CameraState.StateError

Error that the camera has encountered. 

enum CameraState.Type

States the camera can be in. 

Constants

int ERROR_CAMERA_DISABLED

An error indicating that the camera device could not be opened due to a device policy.

int ERROR_CAMERA_FATAL_ERROR

An error indicating that the camera device was closed due to a fatal error.

int ERROR_CAMERA_IN_USE

An error indicating that the camera device is already in use.

int ERROR_DO_NOT_DISTURB_MODE_ENABLED

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

int ERROR_MAX_CAMERAS_IN_USE

An error indicating that the limit number of open cameras has been reached, and more cameras cannot be opened until other instances are closed.

int ERROR_OTHER_RECOVERABLE_ERROR

An error indicating that the camera device has encountered a recoverable error.

int ERROR_STREAM_CONFIG

An error indicating that configuring the camera has failed.

Public constructors

CameraState()

Public methods

static CameraState create(CameraState.Type type)

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

static CameraState create(CameraState.Type type, CameraState.StateError error)

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

abstract CameraState.StateError getError()

Potentially returns an error the camera encountered.

abstract CameraState.Type getType()

Returns the camera's state.

Inherited methods

Constants

ERROR_CAMERA_DISABLED

public static final int ERROR_CAMERA_DISABLED

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.

Constant Value: 5 (0x00000005)

ERROR_CAMERA_FATAL_ERROR

public static final int ERROR_CAMERA_FATAL_ERROR

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 CameraDevice.StateCallback.ERROR_CAMERA_SERVICE error.

Constant Value: 6 (0x00000006)

ERROR_CAMERA_IN_USE

public static final int ERROR_CAMERA_IN_USE

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.

Constant Value: 2 (0x00000002)

ERROR_DO_NOT_DISTURB_MODE_ENABLED

public static final int ERROR_DO_NOT_DISTURB_MODE_ENABLED

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

Constant Value: 7 (0x00000007)

ERROR_MAX_CAMERAS_IN_USE

public static final int ERROR_MAX_CAMERAS_IN_USE

An error indicating that the limit number of open cameras has been reached, and more cameras cannot be opened until other instances are closed.

Constant Value: 1 (0x00000001)

ERROR_OTHER_RECOVERABLE_ERROR

public static final int ERROR_OTHER_RECOVERABLE_ERROR

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 CameraState.Type.PENDING_OPEN state. When CameraX uses a android.hardware.camera2 implementation, this error represents a CameraDevice.StateCallback.ERROR_CAMERA_DEVICE error.

Constant Value: 3 (0x00000003)

ERROR_STREAM_CONFIG

public static final int ERROR_STREAM_CONFIG

An error indicating that configuring the camera has failed.

Constant Value: 4 (0x00000004)

Public constructors

CameraState

public CameraState ()

Public methods

create

public static CameraState create (CameraState.Type type)

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

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

Parameters
type CameraState.Type

Returns
CameraState

create

public static CameraState create (CameraState.Type type, 
                CameraState.StateError error)

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

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

Parameters
type CameraState.Type

error CameraState.StateError

Returns
CameraState

getError

public abstract CameraState.StateError getError ()

Potentially returns an error the camera encountered.

Returns
CameraState.StateError An error the camera encountered, or null otherwise.

getType

public abstract CameraState.Type getType ()

Returns the camera's state.

Returns
CameraState.Type The camera's state