camera_devstatus_t

Updated: April 19, 2023

Status of the camera device

Synopsis:

#include <camera/camera_api.h>
typedef enum {
    CAMERA_STATUS_UNKNOWN = 0,
    CAMERA_STATUS_DISCONNECTED,
    CAMERA_STATUS_CONNECTED,
    CAMERA_STATUS_POWERDOWN,
    CAMERA_STATUS_VIDEOVF,
    CAMERA_STATUS_MM_ERROR,
    CAMERA_STATUS_FILESIZE_ERROR,
    CAMERA_STATUS_NOSPACE_ERROR,
    CAMERA_STATUS_CAPTURE_ABORTED,
    CAMERA_STATUS_FILESIZE_WARNING,
    CAMERA_STATUS_FOCUS_CHANGE,
    CAMERA_STATUS_RESOURCENOTAVAIL,
    CAMERA_STATUS_VIDEO_PAUSE,
    CAMERA_STATUS_VIDEO_RESUME,
    CAMERA_STATUS_POWERUP,
    CAMERA_STATUS_FRAME_DROPPED,
    CAMERA_STATUS_FILESIZE_LIMIT_WARNING,
    CAMERA_STATUS_VIEWFINDER_ACTIVE,
    CAMERA_STATUS_BUFFER_UNDERFLOW,
    CAMERA_STATUS_VIEWFINDER_ERROR
} camera_devstatus_t;

Data:

CAMERA_STATUS_UNKNOWN
The status of the camera is not known.
CAMERA_STATUS_DISCONNECTED
No user is connected to the camera.
CAMERA_STATUS_CONNECTED
A user is connected to the camera but the camera is in the idle state.
CAMERA_STATUS_POWERDOWN
The camera is not powered.

This is typical when the device is going into a standby state. The extra uint16_t value can be interpreted as follows:

CAMERA_STATUS_VIDEOVF
The video viewfinder has started.
CAMERA_STATUS_MM_ERROR
The recording has stopped due to a memory error or multimedia framework error (this is used by the video encoder).
CAMERA_STATUS_FILESIZE_ERROR
A file has exceeded the maximum size.

Recordings will stop with this error when the size is getting too close to the limit.

CAMERA_STATUS_NOSPACE_ERROR
The recording has stopped because there is no more disk space available.
CAMERA_STATUS_CAPTURE_ABORTED
The capture of a still image failed and was aborted.
CAMERA_STATUS_FILESIZE_WARNING
The user-configurable time-remaining threshold has been exceeded while recording video.

The default is 60 seconds, but you can change the time-remaining threshold using the camera_set_video_filesize_warning() function.

CAMERA_STATUS_FOCUS_CHANGE
The focus changed on the camera.

The extra uint16_t value can be interpreted as follows:

  • Bits 15..8: For internal use only; do not use.
  • Bits 7..0: The camera_focusstate_t value indicating the focus state.

You can call the camera_get_focus_state() function to retrieve further details, including the focus region co-ordinates.

CAMERA_STATUS_RESOURCENOTAVAIL
A warning that the camera is about to free resources due to a power-down or arbitration event (i.e., resources are needed elsewhere).

You should release camera resources by returning buffers, stopping recordings, and stopping viewfinders. This event happens when the device is about to enter standby mode or a higher-priority process needs access to resources that are shared with the camera. The extra uint16_t value can be interpreted as follows:

Note:

For more important information related to the triggering of this status event, see Resource Management and the camera_register_resource() function.

CAMERA_STATUS_VIDEO_PAUSE
Video encoding has been paused.

This pause is due to resources needed for video encoding being currently unavailable (i.e., needed elsewhere). While encoding is paused, there will be a gap in the video file. Your application may stop video encoding when this status event is received. When resources become available, a CAMERA_STATUS_VIDEO_RESUME status change will be sent.

CAMERA_STATUS_VIDEO_RESUME
Video encoding has resumed again following a pause or has started for the first time.
CAMERA_STATUS_POWERUP
The camera has been repowered.

This status typically occurs when the device returns from the standby (i.e., CAMERA_STATUS_POWERDOWN) state.

CAMERA_STATUS_FRAME_DROPPED
This indicates that a frame was dropped internally either due to the user taking too long to process a callback frame or due to some internal error.

The uint16_t extra argument contains the camera_eventkey_t associated with the buffer queue that overflowed.

CAMERA_STATUS_FILESIZE_LIMIT_WARNING
The user-configurable time before reaching the user-configured file size limit has been reached while recording a video.

This status event is generated after the user has called camera_set_video_filesize_limit() to set a non-zero file size limit and it was determined that the file size limit will be reached in the configured warning time.

CAMERA_STATUS_VIEWFINDER_ACTIVE
Viewfinder is active and working properly.

This is sent initially after entering CAMERA_STATUS_VIDEOVF to indicate that we have received our first viewfinder buffer. This is also sent after we recover from an error such as CAMERA_STATUS_BUFFER_UNDERFLOW or CAMERA_STATUS_VIEWFINDER_ERROR to indicate that streaming is back to working as expected.

CAMERA_STATUS_BUFFER_UNDERFLOW
The viewfinder is out of buffers and cannot stream any further buffers until a buffer is freed.

When the viewfinder has recovered, a CAMERA_STATUS_VIEWFINDER_ACTIVE indication will be given.

CAMERA_STATUS_VIEWFINDER_ERROR
An unexpected error was encountered while the viewfinder was active that prevents the camera from streaming any further data.

When the viewfinder has recovered, a CAMERA_STATUS_VIEWFINDER_ACTIVE indication will be given.

Library:

libcamapi

Description:

These values are delivered to the status callback functions or via the camera_get_status_details() function whenever the status of the camera changes.

Some examples of conditions which may trigger a status change include:
  • the viewfinder was started
  • recording has stopped
  • autofocus is searching or has locked
  • the camera has powered down
  • a capture was aborted due to a fault

Status changes may also convey additional information as a uint16_t value where indicated.