From 8bf364ef20331ebcc23b1f72121434a98bc5c567 Mon Sep 17 00:00:00 2001 From: Eino-Ville Talvala Date: Thu, 22 Dec 2011 13:50:37 -0800 Subject: [PATCH] Reorganize camera HAL, and add versioning support. Includes a draft of camera device HAL 2. Change-Id: I5f56a8c54a33d0ca039360185822a9c22436cab8 --- include/hardware/camera.h | 61 +++---- include/hardware/camera2.h | 278 +++++++++++++++++++++++++++++++ include/hardware/camera_common.h | 146 ++++++++++++++++ 3 files changed, 444 insertions(+), 41 deletions(-) create mode 100644 include/hardware/camera2.h create mode 100644 include/hardware/camera_common.h diff --git a/include/hardware/camera.h b/include/hardware/camera.h index 4058c301..3530f8d0 100644 --- a/include/hardware/camera.h +++ b/include/hardware/camera.h @@ -14,53 +14,28 @@ * limitations under the License. */ -// FIXME: add well-defined names for cameras - #ifndef ANDROID_INCLUDE_CAMERA_H #define ANDROID_INCLUDE_CAMERA_H -#include -#include -#include -#include -#include -#include -#include - -__BEGIN_DECLS +#include "camera_common.h" /** - * The id of this module + * Camera device HAL, initial version [ HARDWARE_DEVICE_API_VERSION(1,0) ] + * + * Supports the android.hardware.Camera API. + * + * Camera devices that support this version of the HAL must return a value in + * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in + * camera_device_t.common.version. + * + * Camera modules that implement version 2.0 or higher of camera_module_t must + * also return the value of camera_device_t.common.version in + * camera_info_t.device_version. + * + * See camera_common.h for more details. */ -#define CAMERA_HARDWARE_MODULE_ID "camera" -struct camera_info { - /** - * The direction that the camera faces to. It should be CAMERA_FACING_BACK - * or CAMERA_FACING_FRONT. - */ - int facing; - - /** - * The orientation of the camera image. The value is the angle that the - * camera image needs to be rotated clockwise so it shows correctly on the - * 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. - */ - int orientation; -}; - -typedef struct camera_module { - hw_module_t common; - int (*get_number_of_cameras)(void); - int (*get_camera_info)(int camera_id, struct camera_info *info); -} camera_module_t; +__BEGIN_DECLS struct camera_memory; typedef void (*camera_release_memory)(struct camera_memory *mem); @@ -304,6 +279,10 @@ typedef struct camera_device_ops { } camera_device_ops_t; typedef struct camera_device { + /** + * camera_device.common.version must be in the range + * HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF). (1,0) is recommended. + */ hw_device_t common; camera_device_ops_t *ops; void *priv; @@ -311,4 +290,4 @@ typedef struct camera_device { __END_DECLS -#endif /* ANDROID_INCLUDE_CAMERA_H */ +#endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */ diff --git a/include/hardware/camera2.h b/include/hardware/camera2.h new file mode 100644 index 00000000..beb6301f --- /dev/null +++ b/include/hardware/camera2.h @@ -0,0 +1,278 @@ +/* + * Copyright (C) 2012 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef ANDROID_INCLUDE_CAMERA2_H +#define ANDROID_INCLUDE_CAMERA2_H + +#include "camera_common.h" + +/** + * Camera device HAL 2.0 [ HARDWARE_DEVICE_API_VERSION(2,0) ] + * + * EXPERIMENTAL. + * + * Supports both the android.hardware.ProCamera and + * 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_info_t.device_version (from camera_module_t.get_camera_info). + * + * Camera modules that may contain version 2.0 devices must implement at least + * version 2.0 of the camera module interface (as defined by + * camera_module_t.common.module_api_version). + * + * See camera_common.h for more details. + * + */ + +__BEGIN_DECLS + +/** + * Output image stream queue management + */ + +typedef struct camera2_stream_ops { + int (*dequeue_buffer)(struct camera2_stream_ops* w, + buffer_handle_t** buffer, int *stride); + int (*enqueue_buffer)(struct camera2_stream_ops* w, + buffer_handle_t* buffer); + int (*cancel_buffer)(struct camera2_stream_ops* w, + buffer_handle_t* buffer); + int (*set_buffer_count)(struct camera2_stream_ops* w, int count); + int (*set_crop)(struct camera2_stream_ops *w, + int left, int top, int right, int bottom); + // Timestamps are measured in nanoseconds, and must be comparable + // and monotonically increasing between two frames in the same + // preview stream. They do not need to be comparable between + // consecutive or parallel preview streams, cameras, or app runs. + // The timestamp must be the time at the start of image exposure. + int (*set_timestamp)(struct camera2_stream_ops *w, int64_t timestamp); + int (*set_usage)(struct camera2_stream_ops* w, int usage); + int (*set_swap_interval)(struct camera2_stream_ops *w, int interval); + int (*get_min_undequeued_buffer_count)(const struct camera2_stream_ops *w, + int *count); + int (*lock_buffer)(struct camera2_stream_ops* w, + buffer_handle_t* buffer); +} camera2_stream_ops_t; + +/** + * Metadata queue management, used for requests sent to HAL module, and for + * frames produced by the HAL. + */ + +typedef struct camera2_metadata_queue_src_ops { + /** + * Get count of buffers in queue + */ + int (*buffer_count)(camera2_metadata_queue_src_ops *q); + + /** + * Get a metadata buffer from the source. Returns OK if a request is + * available, placing a pointer to it in next_request. + */ + int (*dequeue)(camera2_metadata_queue_src_ops *q, + camera_metadata_t **buffer); + /** + * Return a metadata buffer to the source once it has been used + */ + int (*free)(camera2_metadata_queue_src_ops *q, + camera_metadata_t *old_buffer); + +} camera2_metadata_queue_src_ops_t; + +typedef struct camera2_metadata_queue_dst_ops { + /** + * Notify destination that the queue is no longer empty + */ + int (*notify_queue_not_empty)(struct camera2_metadata_queue_dst_ops *) +} camera2_metadata_queue_dst_ops_t; + +/* Defined in camera_metadata.h */ +typedef struct vendor_tag_query_ops vendor_tag_query_ops_t; + +/** + * Asynchronous notification callback from the HAL, fired for various + * reasons. Only for information independent of frame capture, or that require + * specific timing. + */ +typedef void (*camera2_notify_callback)(int32_t msg_type, + int32_t ext1, + int32_t ext2, + void *user); + +/** + * Possible message types for camera2_notify_callback + */ +enum { + /** + * A serious error has occurred. Argument ext1 contains the error code, and + * ext2 and user contain any error-specific information. + */ + CAMERA_MSG_ERROR = 0x0001, + /** + * The exposure of a given request has begun. Argument ext1 contains the + * request id. + */ + CAMERA_MSG_SHUTTER = 0x0002 +}; + +/** + * Error codes for CAMERA_MSG_ERROR + */ +enum { + /** + * A serious failure occured. Camera device may not work without reboot, and + * no further frames or buffer streams will be produced by the + * device. Device should be treated as closed. + */ + CAMERA_MSG_ERROR_HARDWARE_FAULT = 0x0001, + /** + * A serious failure occured. No further frames or buffer streams will be + * produced by the device. Device should be treated as closed. The client + * must reopen the device to use it again. + */ + CAMERA_MSG_ERROR_DEVICE_FAULT = 0x0002, + /** + * The camera service has failed. Device should be treated as released. The client + * must reopen the device to use it again. + */ + CAMERA_MSG_ERROR_SERVER_FAULT = 0x0003 +}; + + +struct camera2_device; +typedef struct camera2_device_ops { + /** + * Input request queue methods + */ + int (*set_request_queue_ops)(struct camera2_device *, + camera2_metadata_queue_src_ops *request_queue_src_ops); + + camera2_metadata_queue_dst_ops_t *request_queue_dst_ops; + + /** + * Input reprocessing queue methods + */ + int (*set_reprocess_queue_ops)(struct camera2_device *, + camera2_metadata_queue_src_ops *reprocess_queue_src_ops); + + camera2_metadata_queue_dst_ops_t *reprocess_queue_dst_ops; + + /** + * Output frame queue methods + */ + int (*set_frame_queue_ops)(struct camera2_device *, + camera2_metadata_queue_dst_ops *frame_queue_dst_ops); + + camera2_metadata_queue_src_ops_t *frame_queue_src_ops; + + /** + * Pass in notification methods + */ + int (*set_notify_callback)(struct camera2_device *, + camera2_notify_callback notify_cb); + + /** + * Number of camera frames being processed by the device + * at the moment (frames that have had their request dequeued, + * but have not yet been enqueued onto output pipeline(s) ) + */ + int (*get_in_progress_count)(struct camera2_device *); + + /** + * Flush all in-progress captures. This includes all dequeued requests + * (regular or reprocessing) that have not yet placed any outputs into a + * stream or the frame queue. Partially completed captures must be completed + * normally. No new requests may be dequeued from the request or + * reprocessing queues until the flush completes. + */ + int (*flush_captures_in_progress)(struct camera2_device *); + + /** + * Camera stream management + */ + + /** + * Operations on the input reprocessing stream + */ + camera2_stream_ops_t *reprocess_stream_ops; + + /** + * Get the number of streams that can be simultaneously allocated. + * A request may include any allocated pipeline for its output, without + * causing a substantial delay in frame production. + */ + int (*get_stream_slot_count)(struct camera2_device *); + + /** + * Allocate a new stream for use. Requires specifying which pipeline slot + * to use. Specifies the buffer width, height, and format. + * Error conditions: + * - Allocating an already-allocated slot without first releasing it + * - Requesting a width/height/format combination not listed as supported + * - Requesting a pipeline slot >= pipeline slot count. + */ + int (*allocate_stream)( + struct camera2_device *, + uint32_t stream_slot, + uint32_t width, + uint32_t height, + int format, + camera2_stream_ops_t *camera2_stream_ops); + + /** + * Release a stream. Returns an error if called when + * get_in_progress_count is non-zero, or if the pipeline slot is not + * allocated. + */ + int (*release_stream)( + struct camera2_device *, + uint32_t stream_slot); + + /** + * Release the camera hardware. Requests that are in flight will be + * canceled. No further buffers will be pushed into any allocated pipelines + * once this call returns. + */ + void (*release)(struct camera2_device *); + + /** + * Methods to query for vendor extension metadata tag infomation. May be NULL + * if no vendor extension tags are defined. + */ + vendor_tag_query_ops *camera_metadata_vendor_tag_ops; + + /** + * Dump state of the camera hardware + */ + int (*dump)(struct camera2_device *, int fd); + +} camera2_device_ops_t; + +typedef struct camera2_device { + /** + * common.version must equal HARDWARE_DEVICE_API_VERSION(2, 0) to identify + * this device as implementing version 2.0 of the camera device HAL. + */ + hw_device_t common; + camera2_device_ops_t *ops; + void *priv; +} camera2_device_t; + +__END_DECLS + +#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */ diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h new file mode 100644 index 00000000..0a13d5c4 --- /dev/null +++ b/include/hardware/camera_common.h @@ -0,0 +1,146 @@ +/* + * Copyright (C) 2012 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +// FIXME: add well-defined names for cameras + +#ifndef ANDROID_INCLUDE_CAMERA_COMMON_H +#define ANDROID_INCLUDE_CAMERA_COMMON_H + +#include +#include +#include +#include +#include +#include +#include + +__BEGIN_DECLS + +/** + * The id of this module + */ +#define CAMERA_HARDWARE_MODULE_ID "camera" + +/** + * 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 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 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. + */ + + +#define CAMERA_MODULE_API_VERSION HARDWARE_MODULE_API_VERSION(2, 0) +// Stable version for device, version 2.0 is experimental +#define CAMERA_DEVICE_API_VERSION HARDWARE_DEVICE_API_VERSION(1, 0) + +/** + * Defined in /system/media/camera/include/camera_metadata.h + */ +typedef struct camera_metadata camera_metadata_t; + +struct camera_info { + /** + * The direction that the camera faces to. It should be CAMERA_FACING_BACK + * or CAMERA_FACING_FRONT. + * + * Version information: + * Valid in all camera_module versions + */ + int facing; + + /** + * The orientation of the camera image. The value is the angle that the + * camera image needs to be rotated clockwise so it shows correctly on the + * 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. + * + * Version information: + * Valid in all camera_module versions + */ + int orientation; + + /** + * The value of camera_device_t.common.version. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * HARDWARE_MODULE_API_VERSION(0, 0)-(1, FF): + * + * Not valid. Can be assumed to be HARDWARE_DEVICE_API_VERSION(1,0). Do + * not read this field. + * + * HARDWARE_MODULE_API_VERSION(2, 0): + * + * Always valid + * + */ + uint32_t device_version; + + /** + * The camera's fixed characteristics, which include all camera metadata in + * the android.*.info.* sections. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * HARDWARE_MODULE_API_VERSION(0, 0)-(1, FF): + * + * Not valid. Extra characteristics are not available. Do not read this + * field. + * + * HARDWARE_MODULE_API_VERSION(2, 0): + * + * Valid if device_version >= HARDWARE_DEVICE_API_VERSION(2,0). Do not + * read otherwise. + * + */ + camera_metadata_t *static_camera_characteristics; +}; + +typedef struct camera_module { + hw_module_t common; + int (*get_number_of_cameras)(void); + int (*get_camera_info)(int camera_id, struct camera_info *info); +} camera_module_t; + +__END_DECLS + +#endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */