CameraState

@RequiresApi(value = 21)
@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 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.

Error that the camera has encountered.

States 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 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 a new CameraState instance from a Type and a nullStateError.

java-static CameraState

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

abstract CameraState.StateError?

Potentially returns an error the camera encountered.

abstract CameraState.Type

Returns the camera's state.

Constants

ERROR_CAMERA_DISABLED

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

ERROR_CAMERA_FATAL_ERROR

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

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

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

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

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

Added in 1.1.0
const val ERROR_STREAM_CONFIG = 4: Int

An error indicating that configuring the camera has failed.

Public constructors

CameraState

Added in 1.1.0
CameraState()

Public functions

create

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

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

Added in 1.1.0
abstract fun getError(): CameraState.StateError?

Potentially returns an error the camera encountered.

Returns
CameraState.StateError?

An error the camera encountered, or null otherwise.

getType

Added in 1.1.0
abstract fun getType(): CameraState.Type

Returns the camera's state.

Returns
CameraState.Type

The camera's state