1 /* 2 * Copyright (C) 2012 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_INCLUDE_CAMERA2_H 18 #define ANDROID_INCLUDE_CAMERA2_H 19 20 #include "camera_common.h" 21 22 /** 23 * Camera device HAL 2.0 [ CAMERA_DEVICE_API_VERSION_2_0 ] 24 * 25 * EXPERIMENTAL. 26 * 27 * Supports both the android.hardware.ProCamera and 28 * android.hardware.Camera APIs. 29 * 30 * Camera devices that support this version of the HAL must return 31 * CAMERA_DEVICE_API_VERSION_2_0 in camera_device_t.common.version and in 32 * camera_info_t.device_version (from camera_module_t.get_camera_info). 33 * 34 * Camera modules that may contain version 2.0 devices must implement at least 35 * version 2.0 of the camera module interface (as defined by 36 * camera_module_t.common.module_api_version). 37 * 38 * See camera_common.h for more details. 39 * 40 */ 41 42 __BEGIN_DECLS 43 44 struct camera2_device; 45 46 /** 47 * Output image stream queue management 48 */ 49 50 typedef struct camera2_stream_ops { 51 int (*dequeue_buffer)(struct camera2_stream_ops* w, 52 buffer_handle_t** buffer, int *stride); 53 int (*enqueue_buffer)(struct camera2_stream_ops* w, 54 buffer_handle_t* buffer); 55 int (*cancel_buffer)(struct camera2_stream_ops* w, 56 buffer_handle_t* buffer); 57 int (*set_buffer_count)(struct camera2_stream_ops* w, int count); 58 int (*set_buffers_geometry)(struct camera2_stream_ops* pw, 59 int w, int h, int format); 60 int (*set_crop)(struct camera2_stream_ops *w, 61 int left, int top, int right, int bottom); 62 // Timestamps are measured in nanoseconds, and must be comparable 63 // and monotonically increasing between two frames in the same 64 // preview stream. They do not need to be comparable between 65 // consecutive or parallel preview streams, cameras, or app runs. 66 // The timestamp must be the time at the start of image exposure. 67 int (*set_timestamp)(struct camera2_stream_ops *w, int64_t timestamp); 68 int (*set_usage)(struct camera2_stream_ops* w, int usage); 69 int (*get_min_undequeued_buffer_count)(const struct camera2_stream_ops *w, 70 int *count); 71 int (*lock_buffer)(struct camera2_stream_ops* w, 72 buffer_handle_t* buffer); 73 } camera2_stream_ops_t; 74 75 /** 76 * Metadata queue management, used for requests sent to HAL module, and for 77 * frames produced by the HAL. 78 * 79 * Queue protocol: 80 * 81 * The source holds the queue and its contents. At start, the queue is empty. 82 * 83 * 1. When the first metadata buffer is placed into the queue, the source must 84 * signal the destination by calling notify_queue_not_empty(). 85 * 86 * 2. After receiving notify_queue_not_empty, the destination must call 87 * dequeue() once it's ready to handle the next buffer. 88 * 89 * 3. Once the destination has processed a buffer, it should try to dequeue 90 * another buffer. If there are no more buffers available, dequeue() will 91 * return NULL. In this case, when a buffer becomes available, the source 92 * must call notify_queue_not_empty() again. If the destination receives a 93 * NULL return from dequeue, it does not need to query the queue again until 94 * a notify_queue_not_empty() call is received from the source. 95 * 96 * 4. If the destination calls buffer_count() and receives 0, this does not mean 97 * that the source will provide a notify_queue_not_empty() call. The source 98 * must only provide such a call after the destination has received a NULL 99 * from dequeue, or on initial startup. 100 * 101 * 5. The dequeue() call in response to notify_queue_not_empty() may be on the 102 * same thread as the notify_queue_not_empty() call. The source must not 103 * deadlock in that case. 104 */ 105 106 typedef struct camera2_metadata_queue_src_ops { 107 /** 108 * Get count of buffers in queue 109 */ 110 int (*buffer_count)(camera2_metadata_queue_src_ops *q); 111 112 /** 113 * Get a metadata buffer from the source. Returns OK if a request is 114 * available, placing a pointer to it in next_request. 115 */ 116 int (*dequeue)(camera2_metadata_queue_src_ops *q, 117 camera_metadata_t **buffer); 118 /** 119 * Return a metadata buffer to the source once it has been used 120 */ 121 int (*free)(camera2_metadata_queue_src_ops *q, 122 camera_metadata_t *old_buffer); 123 124 } camera2_metadata_queue_src_ops_t; 125 126 typedef struct camera2_metadata_queue_dst_ops { 127 /** 128 * Notify destination that the queue is no longer empty 129 */ 130 int (*notify_queue_not_empty)(struct camera2_metadata_queue_dst_ops *); 131 132 } camera2_metadata_queue_dst_ops_t; 133 134 /* Defined in camera_metadata.h */ 135 typedef struct vendor_tag_query_ops vendor_tag_query_ops_t; 136 137 /** 138 * Asynchronous notification callback from the HAL, fired for various 139 * reasons. Only for information independent of frame capture, or that require 140 * specific timing. 141 */ 142 typedef void (*camera2_notify_callback)(int32_t msg_type, 143 int32_t ext1, 144 int32_t ext2, 145 void *user); 146 147 /** 148 * Possible message types for camera2_notify_callback 149 */ 150 enum { 151 /** 152 * A serious error has occurred. Argument ext1 contains the error code, and 153 * ext2 and user contain any error-specific information. 154 */ 155 CAMERA2_MSG_ERROR = 0x0001, 156 /** 157 * The exposure of a given request has begun. Argument ext1 contains the 158 * request id. 159 */ 160 CAMERA2_MSG_SHUTTER = 0x0002 161 }; 162 163 /** 164 * Error codes for CAMERA_MSG_ERROR 165 */ 166 enum { 167 /** 168 * A serious failure occured. Camera device may not work without reboot, and 169 * no further frames or buffer streams will be produced by the 170 * device. Device should be treated as closed. 171 */ 172 CAMERA2_MSG_ERROR_HARDWARE_FAULT = 0x0001, 173 /** 174 * A serious failure occured. No further frames or buffer streams will be 175 * produced by the device. Device should be treated as closed. The client 176 * must reopen the device to use it again. 177 */ 178 CAMERA2_MSG_ERROR_DEVICE_FAULT = 0x0002, 179 /** 180 * The camera service has failed. Device should be treated as released. The client 181 * must reopen the device to use it again. 182 */ 183 CAMERA2_MSG_ERROR_SERVER_FAULT = 0x0003 184 }; 185 186 typedef struct camera2_device_ops { 187 /** 188 * Input request queue methods 189 */ 190 int (*set_request_queue_src_ops)(struct camera2_device *, 191 camera2_metadata_queue_src_ops *queue_src_ops); 192 193 int (*get_request_queue_dst_ops)(struct camera2_device *, 194 camera2_metadata_queue_dst_ops **queue_dst_ops); 195 196 /** 197 * Input reprocessing queue methods 198 */ 199 int (*set_reprocess_queue_ops)(struct camera2_device *, 200 camera2_metadata_queue_src_ops *queue_src_ops); 201 202 int (*get_reprocess_queue_dst_ops)(struct camera2_device *, 203 camera2_metadata_queue_dst_ops **queue_dst_ops); 204 205 /** 206 * Output frame queue methods 207 */ 208 int (*set_frame_queue_dst_ops)(struct camera2_device *, 209 camera2_metadata_queue_dst_ops *queue_dst_ops); 210 211 int (*get_frame_queue_src_ops)(struct camera2_device *, 212 camera2_metadata_queue_src_ops **queue_dst_ops); 213 214 /** 215 * Pass in notification methods 216 */ 217 int (*set_notify_callback)(struct camera2_device *, 218 camera2_notify_callback notify_cb); 219 220 /** 221 * Number of camera frames being processed by the device 222 * at the moment (frames that have had their request dequeued, 223 * but have not yet been enqueued onto output pipeline(s) ) 224 */ 225 int (*get_in_progress_count)(struct camera2_device *); 226 227 /** 228 * Flush all in-progress captures. This includes all dequeued requests 229 * (regular or reprocessing) that have not yet placed any outputs into a 230 * stream or the frame queue. Partially completed captures must be completed 231 * normally. No new requests may be dequeued from the request or 232 * reprocessing queues until the flush completes. 233 */ 234 int (*flush_captures_in_progress)(struct camera2_device *); 235 236 /** 237 * Camera stream management 238 */ 239 240 /** 241 * Operations on the input reprocessing stream 242 */ 243 int (*get_reprocess_stream_ops)(struct camera2_device *, 244 camera2_stream_ops_t **stream_ops); 245 246 /** 247 * Get the number of streams that can be simultaneously allocated. 248 * A request may include any allocated pipeline for its output, without 249 * causing a substantial delay in frame production. 250 */ 251 int (*get_stream_slot_count)(struct camera2_device *); 252 253 /** 254 * Allocate a new stream for use. Requires specifying which pipeline slot 255 * to use. Specifies the buffer width, height, and format. 256 * Error conditions: 257 * - Allocating an already-allocated slot without first releasing it 258 * - Requesting a width/height/format combination not listed as supported 259 * - Requesting a pipeline slot >= pipeline slot count. 260 */ 261 int (*allocate_stream)( 262 struct camera2_device *, 263 uint32_t stream_slot, 264 uint32_t width, 265 uint32_t height, 266 uint32_t format, 267 camera2_stream_ops_t *camera2_stream_ops); 268 269 /** 270 * Release a stream. Returns an error if called when 271 * get_in_progress_count is non-zero, or if the pipeline slot is not 272 * allocated. 273 */ 274 int (*release_stream)( 275 struct camera2_device *, 276 uint32_t stream_slot); 277 278 /** 279 * Get methods to query for vendor extension metadata tag infomation. May 280 * set ops to NULL if no vendor extension tags are defined. 281 */ 282 int (*get_metadata_vendor_tag_ops)(struct camera2_device*, 283 vendor_tag_query_ops_t **ops); 284 285 /** 286 * Release the camera hardware. Requests that are in flight will be 287 * canceled. No further buffers will be pushed into any allocated pipelines 288 * once this call returns. 289 */ 290 void (*release)(struct camera2_device *); 291 292 /** 293 * Dump state of the camera hardware 294 */ 295 int (*dump)(struct camera2_device *, int fd); 296 297 } camera2_device_ops_t; 298 299 typedef struct camera2_device { 300 /** 301 * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify 302 * this device as implementing version 2.0 of the camera device HAL. 303 */ 304 hw_device_t common; 305 camera2_device_ops_t *ops; 306 void *priv; 307 } camera2_device_t; 308 309 __END_DECLS 310 311 #endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */ 312
