WIP: Camera HAL module 2.1, device 2.1
- Support a simple callback from camera HAL module to framework, to
indicate a change to module configuration or status.
- Add support for per-instance metadata to camera 2 device HAL.
Change-Id: I25699ff096c4f3578b9e54c7e6e60ce2449adc82
diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
index 1237067..a7cf1c2 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -59,6 +59,14 @@
* 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 @@
*/
#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 @@
*/
#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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
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