camera_common.h File Reference
#include <stdint.h>
#include <stdbool.h>
#include <sys/cdefs.h>
#include <sys/types.h>
#include <cutils/native_handle.h>
#include <system/camera.h>
#include <system/camera_vendor_tags.h>
#include <hardware/hardware.h>
#include <hardware/gralloc.h>

Go to the source code of this file.

Data Structures

struct  camera_info
 
struct  camera_module_callbacks
 
struct  camera_module
 

Macros

#define CAMERA_HARDWARE_MODULE_ID   "camera"
 
#define CAMERA_MODULE_API_VERSION_1_0   HARDWARE_MODULE_API_VERSION(1, 0)
 
#define CAMERA_MODULE_API_VERSION_2_0   HARDWARE_MODULE_API_VERSION(2, 0)
 
#define CAMERA_MODULE_API_VERSION_2_1   HARDWARE_MODULE_API_VERSION(2, 1)
 
#define CAMERA_MODULE_API_VERSION_2_2   HARDWARE_MODULE_API_VERSION(2, 2)
 
#define CAMERA_MODULE_API_VERSION_2_3   HARDWARE_MODULE_API_VERSION(2, 3)
 
#define CAMERA_MODULE_API_VERSION_2_4   HARDWARE_MODULE_API_VERSION(2, 4)
 
#define CAMERA_MODULE_API_VERSION_CURRENT   CAMERA_MODULE_API_VERSION_2_4
 
#define CAMERA_DEVICE_API_VERSION_1_0   HARDWARE_DEVICE_API_VERSION(1, 0)
 
#define CAMERA_DEVICE_API_VERSION_2_0   HARDWARE_DEVICE_API_VERSION(2, 0)
 
#define CAMERA_DEVICE_API_VERSION_2_1   HARDWARE_DEVICE_API_VERSION(2, 1)
 
#define CAMERA_DEVICE_API_VERSION_3_0   HARDWARE_DEVICE_API_VERSION(3, 0)
 
#define CAMERA_DEVICE_API_VERSION_3_1   HARDWARE_DEVICE_API_VERSION(3, 1)
 
#define CAMERA_DEVICE_API_VERSION_3_2   HARDWARE_DEVICE_API_VERSION(3, 2)
 
#define CAMERA_DEVICE_API_VERSION_3_3   HARDWARE_DEVICE_API_VERSION(3, 3)
 
#define CAMERA_DEVICE_API_VERSION_3_4   HARDWARE_DEVICE_API_VERSION(3, 4)
 
#define CAMERA_DEVICE_API_VERSION_CURRENT   CAMERA_DEVICE_API_VERSION_3_4
 

Typedefs

typedef struct camera_metadata camera_metadata_t
 
typedef struct camera_info camera_info_t
 
typedef enum camera_device_status camera_device_status_t
 
typedef enum torch_mode_status torch_mode_status_t
 
typedef struct
camera_module_callbacks 
camera_module_callbacks_t
 
typedef struct camera_module camera_module_t
 

Enumerations

enum  camera_device_status { CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, CAMERA_DEVICE_STATUS_PRESENT = 1, CAMERA_DEVICE_STATUS_ENUMERATING = 2 }
 
enum  torch_mode_status { TORCH_MODE_STATUS_NOT_AVAILABLE = 0, TORCH_MODE_STATUS_AVAILABLE_OFF = 1, TORCH_MODE_STATUS_AVAILABLE_ON = 2 }
 

Macro Definition Documentation

#define CAMERA_DEVICE_API_VERSION_1_0   HARDWARE_DEVICE_API_VERSION(1, 0)

All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated as CAMERA_DEVICE_API_VERSION_1_0

Definition at line 143 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_2_0   HARDWARE_DEVICE_API_VERSION(2, 0)

Definition at line 144 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_2_1   HARDWARE_DEVICE_API_VERSION(2, 1)

Definition at line 145 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_3_0   HARDWARE_DEVICE_API_VERSION(3, 0)

Definition at line 146 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_3_1   HARDWARE_DEVICE_API_VERSION(3, 1)

Definition at line 147 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_3_2   HARDWARE_DEVICE_API_VERSION(3, 2)

Definition at line 148 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_3_3   HARDWARE_DEVICE_API_VERSION(3, 3)

Definition at line 149 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_3_4   HARDWARE_DEVICE_API_VERSION(3, 4)

Definition at line 150 of file camera_common.h.

#define CAMERA_DEVICE_API_VERSION_CURRENT   CAMERA_DEVICE_API_VERSION_3_4

Definition at line 154 of file camera_common.h.

#define CAMERA_HARDWARE_MODULE_ID   "camera"

The id of this module

Definition at line 37 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_1_0   HARDWARE_MODULE_API_VERSION(1, 0)

Module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version. The two most significant hex digits represent the major version, and the two least significant represent the minor version.

Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0]

Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version and static_camera_characteristics fields of camera_info are not valid. Only the android.hardware.Camera API can be supported by this module and its devices.

Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0]

Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version field of camera_info is always valid; the static_camera_characteristics field of camera_info is valid if the device_version field is 2.0 or higher.

Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1]

This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks() method must report at least this version number.

Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2]

This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops that were previously only accessible with a device open.

Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3]

This camera module version adds open legacy camera HAL device support. Framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call (common.methods->open) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version.

Version: 2.4 [CAMERA_MODULE_API_VERSION_2_4]

This camera module version adds below API changes:

  1. Torch mode support. The framework can use it to turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device will turn off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as open() is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off.
  2. External camera (e.g. USB hot-plug camera) support. The API updates specify that the camera static info is only available when camera is connected and ready to use for external hot-plug cameras. Calls to get static info will be invalid calls when camera status is not CAMERA_DEVICE_STATUS_PRESENT. The frameworks will only count on device status change callbacks to manage the available external camera list.
  3. Camera arbitration hints. This module version adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the resource_cost and conflicting_devices fields should always be set in the camera_info structure returned by the get_camera_info call.
  4. Module initialization method. This will be called by the camera service right after the HAL module is loaded, to allow for one-time initialization of the HAL. It is called before any other module methods are invoked. Predefined macros for currently-defined version numbers All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated as CAMERA_MODULE_API_VERSION_1_0

Definition at line 130 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_2_0   HARDWARE_MODULE_API_VERSION(2, 0)

Definition at line 131 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_2_1   HARDWARE_MODULE_API_VERSION(2, 1)

Definition at line 132 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_2_2   HARDWARE_MODULE_API_VERSION(2, 2)

Definition at line 133 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_2_3   HARDWARE_MODULE_API_VERSION(2, 3)

Definition at line 134 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_2_4   HARDWARE_MODULE_API_VERSION(2, 4)

Definition at line 135 of file camera_common.h.

#define CAMERA_MODULE_API_VERSION_CURRENT   CAMERA_MODULE_API_VERSION_2_4

Definition at line 137 of file camera_common.h.

Typedef Documentation

camera_device_status_t:

The current status of the camera device, as provided by the HAL through the camera_module_callbacks.camera_device_status_change() call.

At module load time, the framework will assume all camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke camera_module_callbacks::camera_device_status_change to inform the framework of any initially NOT_PRESENT devices.

Allowed transitions: PRESENT -> NOT_PRESENT NOT_PRESENT -> ENUMERATING NOT_PRESENT -> PRESENT ENUMERATING -> PRESENT ENUMERATING -> NOT_PRESENT

typedef struct camera_info camera_info_t
typedef struct camera_metadata camera_metadata_t

Defined in /system/media/camera/include/system/camera_metadata.h

Definition at line 159 of file camera_common.h.

Callback functions for the camera HAL module to use to inform the framework of changes to the camera subsystem.

Version information (based on camera_module_t.common.module_api_version):

Each callback is called only by HAL modules implementing the indicated version or higher of the HAL module API interface.

CAMERA_MODULE_API_VERSION_2_1: camera_device_status_change()

CAMERA_MODULE_API_VERSION_2_4: torch_mode_status_change()

torch_mode_status_t:

The current status of the torch mode, as provided by the HAL through the camera_module_callbacks.torch_mode_status_change() call.

The torch mode status of a camera device is applicable only when the camera device is present. The framework will not call set_torch_mode() to turn on torch mode of a camera device if the camera device is not present. At module load time, the framework will assume torch modes are in the TORCH_MODE_STATUS_AVAILABLE_OFF state if the camera device is present and android.flash.info.available is reported as true via get_camera_info() call.

The behaviors of the camera HAL module that the framework expects in the following situations when a camera device's status changes:

  1. A previously-disconnected camera device becomes connected. After camera_module_callbacks::camera_device_status_change() is invoked to inform the framework that the camera device is present, the framework will assume the camera device's torch mode is in TORCH_MODE_STATUS_AVAILABLE_OFF state. The camera HAL module does not need to invoke camera_module_callbacks::torch_mode_status_change() unless the flash unit is unavailable to use by set_torch_mode().
  2. A previously-connected camera becomes disconnected. After camera_module_callbacks::camera_device_status_change() is invoked to inform the framework that the camera device is not present, the framework will not call set_torch_mode() for the disconnected camera device until its flash unit becomes available again. The camera HAL module does not need to invoke camera_module_callbacks::torch_mode_status_change() separately to inform that the flash unit has become unavailable.
  3. open() is called to open a camera device. The camera HAL module must invoke camera_module_callbacks::torch_mode_status_change() for all flash units that have entered TORCH_MODE_STATUS_NOT_AVAILABLE state and can not be turned on by calling set_torch_mode() anymore due to this open() call. open() must not trigger TORCH_MODE_STATUS_AVAILABLE_OFF before TORCH_MODE_STATUS_NOT_AVAILABLE for all flash units that have become unavailable.
  4. close() is called to close a camera device. The camera HAL module must invoke camera_module_callbacks::torch_mode_status_change() for all flash units that have entered TORCH_MODE_STATUS_AVAILABLE_OFF state and can be turned on by calling set_torch_mode() again because of enough resources freed up by this close() call.

Note that the framework calling set_torch_mode() successfully must trigger TORCH_MODE_STATUS_AVAILABLE_OFF or TORCH_MODE_STATUS_AVAILABLE_ON callback for the given camera device. Additionally it must trigger TORCH_MODE_STATUS_AVAILABLE_OFF callbacks for other previously-on torch modes if HAL cannot keep multiple torch modes on simultaneously.

Enumeration Type Documentation

camera_device_status_t:

The current status of the camera device, as provided by the HAL through the camera_module_callbacks.camera_device_status_change() call.

At module load time, the framework will assume all camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke camera_module_callbacks::camera_device_status_change to inform the framework of any initially NOT_PRESENT devices.

Allowed transitions: PRESENT -> NOT_PRESENT NOT_PRESENT -> ENUMERATING NOT_PRESENT -> PRESENT ENUMERATING -> PRESENT ENUMERATING -> NOT_PRESENT

Enumerator
CAMERA_DEVICE_STATUS_NOT_PRESENT 

The camera device is not currently connected, and opening it will return failure.

Version information (based on camera_module_t.common.module_api_version):

CAMERA_MODULE_API_VERSION_2_3 or lower:

Calls to get_camera_info must still succeed, and provide the same information it would if the camera were connected.

CAMERA_MODULE_API_VERSION_2_4:

The camera device at this status must return -EINVAL for get_camera_info call, as the device is not connected.

CAMERA_DEVICE_STATUS_PRESENT 

The camera device is connected, and opening it will succeed.

CAMERA_MODULE_API_VERSION_2_3 or lower:

The information returned by get_camera_info cannot change due to this status change. By default, the framework will assume all devices are in this state.

CAMERA_MODULE_API_VERSION_2_4:

The information returned by get_camera_info will become valid after a device's status changes to this. By default, the framework will assume all devices are in this state.

CAMERA_DEVICE_STATUS_ENUMERATING 

The camera device is connected, but it is undergoing an enumeration and so opening the device will return -EBUSY.

CAMERA_MODULE_API_VERSION_2_3 or lower:

Calls to get_camera_info must still succeed, as if the camera was in the PRESENT status.

CAMERA_MODULE_API_VERSION_2_4:

The camera device at this status must return -EINVAL for get_camera_info for call, as the device is not ready.

Definition at line 441 of file camera_common.h.

torch_mode_status_t:

The current status of the torch mode, as provided by the HAL through the camera_module_callbacks.torch_mode_status_change() call.

The torch mode status of a camera device is applicable only when the camera device is present. The framework will not call set_torch_mode() to turn on torch mode of a camera device if the camera device is not present. At module load time, the framework will assume torch modes are in the TORCH_MODE_STATUS_AVAILABLE_OFF state if the camera device is present and android.flash.info.available is reported as true via get_camera_info() call.

The behaviors of the camera HAL module that the framework expects in the following situations when a camera device's status changes:

  1. A previously-disconnected camera device becomes connected. After camera_module_callbacks::camera_device_status_change() is invoked to inform the framework that the camera device is present, the framework will assume the camera device's torch mode is in TORCH_MODE_STATUS_AVAILABLE_OFF state. The camera HAL module does not need to invoke camera_module_callbacks::torch_mode_status_change() unless the flash unit is unavailable to use by set_torch_mode().
  2. A previously-connected camera becomes disconnected. After camera_module_callbacks::camera_device_status_change() is invoked to inform the framework that the camera device is not present, the framework will not call set_torch_mode() for the disconnected camera device until its flash unit becomes available again. The camera HAL module does not need to invoke camera_module_callbacks::torch_mode_status_change() separately to inform that the flash unit has become unavailable.
  3. open() is called to open a camera device. The camera HAL module must invoke camera_module_callbacks::torch_mode_status_change() for all flash units that have entered TORCH_MODE_STATUS_NOT_AVAILABLE state and can not be turned on by calling set_torch_mode() anymore due to this open() call. open() must not trigger TORCH_MODE_STATUS_AVAILABLE_OFF before TORCH_MODE_STATUS_NOT_AVAILABLE for all flash units that have become unavailable.
  4. close() is called to close a camera device. The camera HAL module must invoke camera_module_callbacks::torch_mode_status_change() for all flash units that have entered TORCH_MODE_STATUS_AVAILABLE_OFF state and can be turned on by calling set_torch_mode() again because of enough resources freed up by this close() call.

Note that the framework calling set_torch_mode() successfully must trigger TORCH_MODE_STATUS_AVAILABLE_OFF or TORCH_MODE_STATUS_AVAILABLE_ON callback for the given camera device. Additionally it must trigger TORCH_MODE_STATUS_AVAILABLE_OFF callbacks for other previously-on torch modes if HAL cannot keep multiple torch modes on simultaneously.

Enumerator
TORCH_MODE_STATUS_NOT_AVAILABLE 

The flash unit is no longer available and the torch mode can not be turned on by calling set_torch_mode(). If the torch mode is on, it will be turned off by HAL before HAL calls torch_mode_status_change().

TORCH_MODE_STATUS_AVAILABLE_OFF 

A torch mode has become off and available to be turned on via set_torch_mode(). This may happen in the following cases:

  1. After the resources to turn on the torch mode have become available.
  2. After set_torch_mode() is called to turn off the torch mode.
  3. After the framework turned on the torch mode of some other camera device and HAL had to turn off the torch modes of any camera devices that were previously on.
TORCH_MODE_STATUS_AVAILABLE_ON 

A torch mode has become on and available to be turned off via set_torch_mode(). This can happen only after set_torch_mode() is called to turn on the torch mode.

Definition at line 548 of file camera_common.h.