diff --git a/include/hardware/camera2.h b/include/hardware/camera2.h index 5cfdbffe..5b182a8a 100644 --- a/include/hardware/camera2.h +++ b/include/hardware/camera2.h @@ -21,17 +21,17 @@ #include "system/camera_metadata.h" /** - * Camera device HAL 2.0 [ CAMERA_DEVICE_API_VERSION_2_0 ] + * Camera device HAL 2.1 [ CAMERA_DEVICE_API_VERSION_2_0, CAMERA_DEVICE_API_VERSION_2_1 ] * * EXPERIMENTAL. * * Supports the android.hardware.Camera APIs. * * Camera devices that support this version of the HAL must return - * CAMERA_DEVICE_API_VERSION_2_0 in camera_device_t.common.version and in + * CAMERA_DEVICE_API_VERSION_2_1 in camera_device_t.common.version and in * camera_info_t.device_version (from camera_module_t.get_camera_info). * - * Camera modules that may contain version 2.0 devices must implement at least + * Camera modules that may contain version 2.x devices must implement at least * version 2.0 of the camera module interface (as defined by * camera_module_t.common.module_api_version). * @@ -39,11 +39,15 @@ * * Version history: * - * 2.0: Initial release (Android 4.2): + * 2.0: CAMERA_DEVICE_API_VERSION_2_0. Initial release (Android 4.2): * - Sufficient for implementing existing android.hardware.Camera API. * - Allows for ZSL queue in camera service layer * - Not tested for any new features such manual capture control, * Bayer RAW capture, reprocessing of RAW data. + * + * 2.1: CAMERA_DEVICE_API_VERSION_2_1. Support per-device static metadata: + * - Add get_instance_metadata() method to retrieve metadata that is fixed + * after device open, but may be variable between open() calls. */ __BEGIN_DECLS @@ -792,6 +796,26 @@ typedef struct camera2_device_ops { */ int (*dump)(const struct camera2_device *, int fd); + /** + * Get device-instance-specific metadata. This metadata must be constant for + * a single instance of the camera device, but may be different between + * open() calls. The returned camera_metadata pointer must be valid until + * the device close() method is called. + * + * Version information: + * + * CAMERA_DEVICE_API_VERSION_2_0: + * + * Not available. Framework may not access this function pointer. + * + * CAMERA_DEVICE_API_VERSION_2_1: + * + * Valid. Can be called by the framework. + * + */ + int (*get_instance_metadata)(const struct camera2_device *, + camera_metadata **instance_metadata); + } camera2_device_ops_t; /********************************************************************** diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h index 12370678..a7cf1c2e 100644 --- a/include/hardware/camera_common.h +++ b/include/hardware/camera_common.h @@ -59,6 +59,14 @@ __BEGIN_DECLS * 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. */ /** @@ -71,8 +79,9 @@ __BEGIN_DECLS */ #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_CURRENT CAMERA_MODULE_API_VERSION_2_0 +#define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_1 /** * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated @@ -80,9 +89,10 @@ __BEGIN_DECLS */ #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) -// Device version 2.0 is outdated; device version 3.0 is experimental +// Device version 2.x is outdated; device version 3.0 is experimental #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_1_0 /** @@ -106,11 +116,11 @@ struct camera_info { * display in its natural orientation. It should be 0, 90, 180, or 270. * * For example, suppose a device has a naturally tall screen. The - * back-facing camera sensor is mounted in landscape. You are looking at - * the screen. If the top side of the camera sensor is aligned with the - * right edge of the screen in natural orientation, the value should be - * 90. If the top side of a front-facing camera sensor is aligned with the - * right of the screen, the value should be 270. + * back-facing camera sensor is mounted in landscape. You are looking at the + * screen. If the top side of the camera sensor is aligned with the right + * edge of the screen in natural orientation, the value should be 90. If the + * top side of a front-facing camera sensor is aligned with the right of the + * screen, the value should be 270. * * Version information: * Valid in all camera_module versions @@ -127,7 +137,7 @@ struct camera_info { * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do * not read this field. * - * CAMERA_MODULE_API_VERSION_2_0: + * CAMERA_MODULE_API_VERSION_2_0 or higher: * * Always valid * @@ -138,7 +148,8 @@ struct camera_info { * The camera's fixed characteristics, which include all camera metadata in * the android.*.info.* sections. This should be a sorted metadata buffer, * and may not be modified or freed by the caller. The pointer should remain - * valid for the lifetime of the camera module. + * valid for the lifetime of the camera module, and values in it may not + * change after it is returned by get_camera_info(). * * Version information (based on camera_module_t.common.module_api_version): * @@ -147,7 +158,7 @@ struct camera_info { * Not valid. Extra characteristics are not available. Do not read this * field. * - * CAMERA_MODULE_API_VERSION_2_0: + * CAMERA_MODULE_API_VERSION_2_0 or higher: * * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read * otherwise. @@ -156,10 +167,110 @@ struct camera_info { const camera_metadata_t *static_camera_characteristics; }; +/** + * 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. + */ +typedef enum camera_device_status { + /** + * The camera device is not currently connected, and opening it will return + * failure. Calls to get_camera_info must still succeed, and provide the + * same information it would if the camera were connected + */ + CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, + + /** + * The camera device is connected, and opening it will succeed. 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_DEVICE_STATUS_PRESENT = 1 + +} camera_device_status_t; + +/** + * Callback functions for the camera HAL module to use to inform the framework + * of changes to the camera subsystem. These are called only by HAL modules + * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL + * module API interface. + */ +typedef struct camera_module_callbacks { + + /** + * camera_device_status_change: + * + * Callback to the framework to indicate that the state of a specific camera + * device has changed. At module load time, the framework will assume all + * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL + * must call this method to inform the framework of any initially + * NOT_PRESENT devices. + * + * camera_module_callbacks: The instance of camera_module_callbacks_t passed + * to the module with set_callbacks. + * + * camera_id: The ID of the camera device that has a new status. + * + * new_status: The new status code, one of the camera_device_status_t enums, + * or a platform-specific status. + * + */ + void (*camera_device_status_change)(const struct camera_module_callbacks*, + int camera_id, + int new_status); + +} camera_module_callbacks_t; + typedef struct camera_module { hw_module_t common; + + /** + * get_number_of_cameras: + * + * Returns the number of camera devices accessible through the camera + * module. The camera devices are numbered 0 through N-1, where N is the + * value returned by this call. The name of the camera device for open() is + * simply the number converted to a string. That is, "0" for camera ID 0, + * "1" for camera ID 1. + * + * The value here must be static, and cannot change after the first call to + * this method + */ int (*get_number_of_cameras)(void); + + /** + * get_camera_info: + * + * Return the static camera information for a given camera device. This + * information may not change for a camera device. + * + */ int (*get_camera_info)(int camera_id, struct camera_info *info); + + /** + * set_callbacks: + * + * Provide callback function pointers to the HAL module to inform framework + * of asynchronous camera module events. The framework will call this + * function once after initial camera HAL module load, after the + * get_number_of_cameras() method is called for the first time, and before + * any other calls to the module. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0: + * + * Not provided by HAL module. Framework may not call this function. + * + * CAMERA_MODULE_API_VERSION_2_1: + * + * Valid to be called by the framework. + * + */ + int (*set_callbacks)(const camera_module_callbacks_t *callbacks); + } camera_module_t; __END_DECLS