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 #include "system/camera_metadata.h" 22 23 /** 24 * Camera device HAL 2.1 [ CAMERA_DEVICE_API_VERSION_2_0, CAMERA_DEVICE_API_VERSION_2_1 ] 25 * 26 * EXPERIMENTAL. 27 * 28 * Supports the android.hardware.Camera APIs. 29 * 30 * Camera devices that support this version of the HAL must return 31 * CAMERA_DEVICE_API_VERSION_2_1 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.x 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 versioning details. 39 * 40 * Version history: 41 * 42 * 2.0: CAMERA_DEVICE_API_VERSION_2_0. Initial release (Android 4.2): 43 * - Sufficient for implementing existing android.hardware.Camera API. 44 * - Allows for ZSL queue in camera service layer 45 * - Not tested for any new features such manual capture control, 46 * Bayer RAW capture, reprocessing of RAW data. 47 * 48 * 2.1: CAMERA_DEVICE_API_VERSION_2_1. Support per-device static metadata: 49 * - Add get_instance_metadata() method to retrieve metadata that is fixed 50 * after device open, but may be variable between open() calls. 51 */ 52 53 __BEGIN_DECLS 54 55 struct camera2_device; 56 57 /********************************************************************** 58 * 59 * Input/output stream buffer queue interface definitions 60 * 61 */ 62 63 /** 64 * Output image stream queue interface. A set of these methods is provided to 65 * the HAL device in allocate_stream(), and are used to interact with the 66 * gralloc buffer queue for that stream. They may not be called until after 67 * allocate_stream returns. 68 */ 69 typedef struct camera2_stream_ops { 70 /** 71 * Get a buffer to fill from the queue. The size and format of the buffer 72 * are fixed for a given stream (defined in allocate_stream), and the stride 73 * should be queried from the platform gralloc module. The gralloc buffer 74 * will have been allocated based on the usage flags provided by 75 * allocate_stream, and will be locked for use. 76 */ 77 int (*dequeue_buffer)(const struct camera2_stream_ops* w, 78 buffer_handle_t** buffer); 79 80 /** 81 * Push a filled buffer to the stream to be used by the consumer. 82 * 83 * The timestamp represents the time at start of exposure of the first row 84 * of the image; it must be from a monotonic clock, and is measured in 85 * nanoseconds. The timestamps do not need to be comparable between 86 * different cameras, or consecutive instances of the same camera. However, 87 * they must be comparable between streams from the same camera. If one 88 * capture produces buffers for multiple streams, each stream must have the 89 * same timestamp for that buffer, and that timestamp must match the 90 * timestamp in the output frame metadata. 91 */ 92 int (*enqueue_buffer)(const struct camera2_stream_ops* w, 93 int64_t timestamp, 94 buffer_handle_t* buffer); 95 /** 96 * Return a buffer to the queue without marking it as filled. 97 */ 98 int (*cancel_buffer)(const struct camera2_stream_ops* w, 99 buffer_handle_t* buffer); 100 /** 101 * Set the crop window for subsequently enqueued buffers. The parameters are 102 * measured in pixels relative to the buffer width and height. 103 */ 104 int (*set_crop)(const struct camera2_stream_ops *w, 105 int left, int top, int right, int bottom); 106 107 } camera2_stream_ops_t; 108 109 /** 110 * Temporary definition during transition. 111 * 112 * These formats will be removed and replaced with 113 * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. To maximize forward compatibility, 114 * HAL implementations are strongly recommended to treat FORMAT_OPAQUE and 115 * FORMAT_ZSL as equivalent to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, and 116 * return HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED in the format_actual output 117 * parameter of allocate_stream, allowing the gralloc module to select the 118 * specific format based on the usage flags from the camera and the stream 119 * consumer. 120 */ 121 enum { 122 CAMERA2_HAL_PIXEL_FORMAT_OPAQUE = HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 123 CAMERA2_HAL_PIXEL_FORMAT_ZSL = -1 124 }; 125 126 /** 127 * Transport header for compressed JPEG buffers in output streams. 128 * 129 * To capture JPEG images, a stream is created using the pixel format 130 * HAL_PIXEL_FORMAT_BLOB, and the static metadata field android.jpeg.maxSize is 131 * used as the buffer size. Since compressed JPEG images are of variable size, 132 * the HAL needs to include the final size of the compressed image using this 133 * structure inside the output stream buffer. The JPEG blob ID field must be set 134 * to CAMERA2_JPEG_BLOB_ID. 135 * 136 * Transport header should be at the end of the JPEG output stream buffer. That 137 * means the jpeg_blob_id must start at byte[android.jpeg.maxSize - 138 * sizeof(camera2_jpeg_blob)]. Any HAL using this transport header must 139 * account for it in android.jpeg.maxSize. The JPEG data itself starts at 140 * byte[0] and should be jpeg_size bytes long. 141 */ 142 typedef struct camera2_jpeg_blob { 143 uint16_t jpeg_blob_id; 144 uint32_t jpeg_size; 145 }; 146 147 enum { 148 CAMERA2_JPEG_BLOB_ID = 0x00FF 149 }; 150 151 /** 152 * Input reprocess stream queue management. A set of these methods is provided 153 * to the HAL device in allocate_reprocess_stream(); they are used to interact 154 * with the reprocess stream's input gralloc buffer queue. 155 */ 156 typedef struct camera2_stream_in_ops { 157 /** 158 * Get the next buffer of image data to reprocess. The width, height, and 159 * format of the buffer is fixed in allocate_reprocess_stream(), and the 160 * stride and other details should be queried from the platform gralloc 161 * module as needed. The buffer will already be locked for use. 162 */ 163 int (*acquire_buffer)(const struct camera2_stream_in_ops *w, 164 buffer_handle_t** buffer); 165 /** 166 * Return a used buffer to the buffer queue for reuse. 167 */ 168 int (*release_buffer)(const struct camera2_stream_in_ops *w, 169 buffer_handle_t* buffer); 170 171 } camera2_stream_in_ops_t; 172 173 /********************************************************************** 174 * 175 * Metadata queue management, used for requests sent to HAL module, and for 176 * frames produced by the HAL. 177 * 178 */ 179 180 enum { 181 CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS = -1 182 }; 183 184 /** 185 * Request input queue protocol: 186 * 187 * The framework holds the queue and its contents. At start, the queue is empty. 188 * 189 * 1. When the first metadata buffer is placed into the queue, the framework 190 * signals the device by calling notify_request_queue_not_empty(). 191 * 192 * 2. After receiving notify_request_queue_not_empty, the device must call 193 * dequeue() once it's ready to handle the next buffer. 194 * 195 * 3. Once the device has processed a buffer, and is ready for the next buffer, 196 * it must call dequeue() again instead of waiting for a notification. If 197 * there are no more buffers available, dequeue() will return NULL. After 198 * this point, when a buffer becomes available, the framework must call 199 * notify_request_queue_not_empty() again. If the device receives a NULL 200 * return from dequeue, it does not need to query the queue again until a 201 * notify_request_queue_not_empty() call is received from the source. 202 * 203 * 4. If the device calls buffer_count() and receives 0, this does not mean that 204 * the framework will provide a notify_request_queue_not_empty() call. The 205 * framework will only provide such a notification after the device has 206 * received a NULL from dequeue, or on initial startup. 207 * 208 * 5. The dequeue() call in response to notify_request_queue_not_empty() may be 209 * on the same thread as the notify_request_queue_not_empty() call, and may 210 * be performed from within the notify call. 211 * 212 * 6. All dequeued request buffers must be returned to the framework by calling 213 * free_request, including when errors occur, a device flush is requested, or 214 * when the device is shutting down. 215 */ 216 typedef struct camera2_request_queue_src_ops { 217 /** 218 * Get the count of request buffers pending in the queue. May return 219 * CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS if a repeating request (stream 220 * request) is currently configured. Calling this method has no effect on 221 * whether the notify_request_queue_not_empty() method will be called by the 222 * framework. 223 */ 224 int (*request_count)(const struct camera2_request_queue_src_ops *q); 225 226 /** 227 * Get a metadata buffer from the framework. Returns OK if there is no 228 * error. If the queue is empty, returns NULL in buffer. In that case, the 229 * device must wait for a notify_request_queue_not_empty() message before 230 * attempting to dequeue again. Buffers obtained in this way must be 231 * returned to the framework with free_request(). 232 */ 233 int (*dequeue_request)(const struct camera2_request_queue_src_ops *q, 234 camera_metadata_t **buffer); 235 /** 236 * Return a metadata buffer to the framework once it has been used, or if 237 * an error or shutdown occurs. 238 */ 239 int (*free_request)(const struct camera2_request_queue_src_ops *q, 240 camera_metadata_t *old_buffer); 241 242 } camera2_request_queue_src_ops_t; 243 244 /** 245 * Frame output queue protocol: 246 * 247 * The framework holds the queue and its contents. At start, the queue is empty. 248 * 249 * 1. When the device is ready to fill an output metadata frame, it must dequeue 250 * a metadata buffer of the required size. 251 * 252 * 2. It should then fill the metadata buffer, and place it on the frame queue 253 * using enqueue_frame. The framework takes ownership of the frame. 254 * 255 * 3. In case of an error, a request to flush the pipeline, or shutdown, the 256 * device must return any affected dequeued frames to the framework by 257 * calling cancel_frame. 258 */ 259 typedef struct camera2_frame_queue_dst_ops { 260 /** 261 * Get an empty metadata buffer to fill from the framework. The new metadata 262 * buffer will have room for entries number of metadata entries, plus 263 * data_bytes worth of extra storage. Frames dequeued here must be returned 264 * to the framework with either cancel_frame or enqueue_frame. 265 */ 266 int (*dequeue_frame)(const struct camera2_frame_queue_dst_ops *q, 267 size_t entries, size_t data_bytes, 268 camera_metadata_t **buffer); 269 270 /** 271 * Return a dequeued metadata buffer to the framework for reuse; do not mark it as 272 * filled. Use when encountering errors, or flushing the internal request queue. 273 */ 274 int (*cancel_frame)(const struct camera2_frame_queue_dst_ops *q, 275 camera_metadata_t *buffer); 276 277 /** 278 * Place a completed metadata frame on the frame output queue. 279 */ 280 int (*enqueue_frame)(const struct camera2_frame_queue_dst_ops *q, 281 camera_metadata_t *buffer); 282 283 } camera2_frame_queue_dst_ops_t; 284 285 /********************************************************************** 286 * 287 * Notification callback and message definition, and trigger definitions 288 * 289 */ 290 291 /** 292 * Asynchronous notification callback from the HAL, fired for various 293 * reasons. Only for information independent of frame capture, or that require 294 * specific timing. The user pointer must be the same one that was passed to the 295 * device in set_notify_callback(). 296 */ 297 typedef void (*camera2_notify_callback)(int32_t msg_type, 298 int32_t ext1, 299 int32_t ext2, 300 int32_t ext3, 301 void *user); 302 303 /** 304 * Possible message types for camera2_notify_callback 305 */ 306 enum { 307 /** 308 * An error has occurred. Argument ext1 contains the error code, and 309 * ext2 and ext3 contain any error-specific information. 310 */ 311 CAMERA2_MSG_ERROR = 0x0001, 312 /** 313 * The exposure of a given request has begun. Argument ext1 contains the 314 * frame number, and ext2 and ext3 contain the low-order and high-order 315 * bytes of the timestamp for when exposure began. 316 * (timestamp = (ext3 << 32 | ext2)) 317 */ 318 CAMERA2_MSG_SHUTTER = 0x0010, 319 /** 320 * The autofocus routine has changed state. Argument ext1 contains the new 321 * state; the values are the same as those for the metadata field 322 * android.control.afState. Ext2 contains the latest trigger ID passed to 323 * trigger_action(CAMERA2_TRIGGER_AUTOFOCUS) or 324 * trigger_action(CAMERA2_TRIGGER_CANCEL_AUTOFOCUS), or 0 if trigger has not 325 * been called with either of those actions. 326 */ 327 CAMERA2_MSG_AUTOFOCUS = 0x0020, 328 /** 329 * The autoexposure routine has changed state. Argument ext1 contains the 330 * new state; the values are the same as those for the metadata field 331 * android.control.aeState. Ext2 contains the latest trigger ID value passed to 332 * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method 333 * has not been called. 334 */ 335 CAMERA2_MSG_AUTOEXPOSURE = 0x0021, 336 /** 337 * The auto-whitebalance routine has changed state. Argument ext1 contains 338 * the new state; the values are the same as those for the metadata field 339 * android.control.awbState. Ext2 contains the latest trigger ID passed to 340 * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method 341 * has not been called. 342 */ 343 CAMERA2_MSG_AUTOWB = 0x0022 344 }; 345 346 /** 347 * Error codes for CAMERA_MSG_ERROR 348 */ 349 enum { 350 /** 351 * A serious failure occured. Camera device may not work without reboot, and 352 * no further frames or buffer streams will be produced by the 353 * device. Device should be treated as closed. 354 */ 355 CAMERA2_MSG_ERROR_HARDWARE = 0x0001, 356 /** 357 * A serious failure occured. No further frames or buffer streams will be 358 * produced by the device. Device should be treated as closed. The client 359 * must reopen the device to use it again. 360 */ 361 CAMERA2_MSG_ERROR_DEVICE, 362 /** 363 * An error has occurred in processing a request. No output (metadata or 364 * buffers) will be produced for this request. ext2 contains the frame 365 * number of the request. Subsequent requests are unaffected, and the device 366 * remains operational. 367 */ 368 CAMERA2_MSG_ERROR_REQUEST, 369 /** 370 * An error has occurred in producing an output frame metadata buffer for a 371 * request, but image buffers for it will still be available. Subsequent 372 * requests are unaffected, and the device remains operational. ext2 373 * contains the frame number of the request. 374 */ 375 CAMERA2_MSG_ERROR_FRAME, 376 /** 377 * An error has occurred in placing an output buffer into a stream for a 378 * request. The frame metadata and other buffers may still be 379 * available. Subsequent requests are unaffected, and the device remains 380 * operational. ext2 contains the frame number of the request, and ext3 381 * contains the stream id. 382 */ 383 CAMERA2_MSG_ERROR_STREAM, 384 /** 385 * Number of error types 386 */ 387 CAMERA2_MSG_NUM_ERRORS 388 }; 389 390 /** 391 * Possible trigger ids for trigger_action() 392 */ 393 enum { 394 /** 395 * Trigger an autofocus cycle. The effect of the trigger depends on the 396 * autofocus mode in effect when the trigger is received, which is the mode 397 * listed in the latest capture request to be dequeued by the HAL. If the 398 * mode is OFF, EDOF, or FIXED, the trigger has no effect. In AUTO, MACRO, 399 * or CONTINUOUS_* modes, see below for the expected behavior. The state of 400 * the autofocus cycle can be tracked in android.control.afMode and the 401 * corresponding notifications. 402 * 403 ** 404 * In AUTO or MACRO mode, the AF state transitions (and notifications) 405 * when calling with trigger ID = N with the previous ID being K are: 406 * 407 * Initial state Transitions 408 * INACTIVE (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 409 * AF_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 410 * AF_NOT_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 411 * ACTIVE_SCAN (K) -> AF_FOCUSED(N) or AF_NOT_FOCUSED(N) 412 * PASSIVE_SCAN (K) Not used in AUTO/MACRO mode 413 * PASSIVE_FOCUSED (K) Not used in AUTO/MACRO mode 414 * 415 ** 416 * In CONTINUOUS_PICTURE mode, triggering AF must lock the AF to the current 417 * lens position and transition the AF state to either AF_FOCUSED or 418 * NOT_FOCUSED. If a passive scan is underway, that scan must complete and 419 * then lock the lens position and change AF state. TRIGGER_CANCEL_AUTOFOCUS 420 * will allow the AF to restart its operation. 421 * 422 * Initial state Transitions 423 * INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 424 * PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 425 * PASSIVE_SCAN (K) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 426 * AF_FOCUSED (K) no effect except to change next notification ID to N 427 * AF_NOT_FOCUSED (K) no effect except to change next notification ID to N 428 * 429 ** 430 * In CONTINUOUS_VIDEO mode, triggering AF must lock the AF to the current 431 * lens position and transition the AF state to either AF_FOCUSED or 432 * NOT_FOCUSED. If a passive scan is underway, it must immediately halt, in 433 * contrast with CONTINUOUS_PICTURE mode. TRIGGER_CANCEL_AUTOFOCUS will 434 * allow the AF to restart its operation. 435 * 436 * Initial state Transitions 437 * INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 438 * PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 439 * PASSIVE_SCAN (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) 440 * AF_FOCUSED (K) no effect except to change next notification ID to N 441 * AF_NOT_FOCUSED (K) no effect except to change next notification ID to N 442 * 443 * Ext1 is an ID that must be returned in subsequent auto-focus state change 444 * notifications through camera2_notify_callback() and stored in 445 * android.control.afTriggerId. 446 */ 447 CAMERA2_TRIGGER_AUTOFOCUS = 0x0001, 448 /** 449 * Send a cancel message to the autofocus algorithm. The effect of the 450 * cancellation depends on the autofocus mode in effect when the trigger is 451 * received, which is the mode listed in the latest capture request to be 452 * dequeued by the HAL. If the AF mode is OFF or EDOF, the cancel has no 453 * effect. For other modes, the lens should return to its default position, 454 * any current autofocus scan must be canceled, and the AF state should be 455 * set to INACTIVE. 456 * 457 * The state of the autofocus cycle can be tracked in android.control.afMode 458 * and the corresponding notification. Continuous autofocus modes may resume 459 * focusing operations thereafter exactly as if the camera had just been set 460 * to a continuous AF mode. 461 * 462 * Ext1 is an ID that must be returned in subsequent auto-focus state change 463 * notifications through camera2_notify_callback() and stored in 464 * android.control.afTriggerId. 465 */ 466 CAMERA2_TRIGGER_CANCEL_AUTOFOCUS, 467 /** 468 * Trigger a pre-capture metering cycle, which may include firing the flash 469 * to determine proper capture parameters. Typically, this trigger would be 470 * fired for a half-depress of a camera shutter key, or before a snapshot 471 * capture in general. The state of the metering cycle can be tracked in 472 * android.control.aeMode and the corresponding notification. If the 473 * auto-exposure mode is OFF, the trigger does nothing. 474 * 475 * Ext1 is an ID that must be returned in subsequent 476 * auto-exposure/auto-white balance state change notifications through 477 * camera2_notify_callback() and stored in android.control.aePrecaptureId. 478 */ 479 CAMERA2_TRIGGER_PRECAPTURE_METERING 480 }; 481 482 /** 483 * Possible template types for construct_default_request() 484 */ 485 enum { 486 /** 487 * Standard camera preview operation with 3A on auto. 488 */ 489 CAMERA2_TEMPLATE_PREVIEW = 1, 490 /** 491 * Standard camera high-quality still capture with 3A and flash on auto. 492 */ 493 CAMERA2_TEMPLATE_STILL_CAPTURE, 494 /** 495 * Standard video recording plus preview with 3A on auto, torch off. 496 */ 497 CAMERA2_TEMPLATE_VIDEO_RECORD, 498 /** 499 * High-quality still capture while recording video. Application will 500 * include preview, video record, and full-resolution YUV or JPEG streams in 501 * request. Must not cause stuttering on video stream. 3A on auto. 502 */ 503 CAMERA2_TEMPLATE_VIDEO_SNAPSHOT, 504 /** 505 * Zero-shutter-lag mode. Application will request preview and 506 * full-resolution data for each frame, and reprocess it to JPEG when a 507 * still image is requested by user. Settings should provide highest-quality 508 * full-resolution images without compromising preview frame rate. 3A on 509 * auto. 510 */ 511 CAMERA2_TEMPLATE_ZERO_SHUTTER_LAG, 512 513 /* Total number of templates */ 514 CAMERA2_TEMPLATE_COUNT 515 }; 516 517 518 /********************************************************************** 519 * 520 * Camera device operations 521 * 522 */ 523 typedef struct camera2_device_ops { 524 525 /********************************************************************** 526 * Request and frame queue setup and management methods 527 */ 528 529 /** 530 * Pass in input request queue interface methods. 531 */ 532 int (*set_request_queue_src_ops)(const struct camera2_device *, 533 const camera2_request_queue_src_ops_t *request_src_ops); 534 535 /** 536 * Notify device that the request queue is no longer empty. Must only be 537 * called when the first buffer is added a new queue, or after the source 538 * has returned NULL in response to a dequeue call. 539 */ 540 int (*notify_request_queue_not_empty)(const struct camera2_device *); 541 542 /** 543 * Pass in output frame queue interface methods 544 */ 545 int (*set_frame_queue_dst_ops)(const struct camera2_device *, 546 const camera2_frame_queue_dst_ops_t *frame_dst_ops); 547 548 /** 549 * Number of camera requests being processed by the device at the moment 550 * (captures/reprocesses that have had their request dequeued, but have not 551 * yet been enqueued onto output pipeline(s) ). No streams may be released 552 * by the framework until the in-progress count is 0. 553 */ 554 int (*get_in_progress_count)(const struct camera2_device *); 555 556 /** 557 * Flush all in-progress captures. This includes all dequeued requests 558 * (regular or reprocessing) that have not yet placed any outputs into a 559 * stream or the frame queue. Partially completed captures must be completed 560 * normally. No new requests may be dequeued from the request queue until 561 * the flush completes. 562 */ 563 int (*flush_captures_in_progress)(const struct camera2_device *); 564 565 /** 566 * Create a filled-in default request for standard camera use cases. 567 * 568 * The device must return a complete request that is configured to meet the 569 * requested use case, which must be one of the CAMERA2_TEMPLATE_* 570 * enums. All request control fields must be included, except for 571 * android.request.outputStreams. 572 * 573 * The metadata buffer returned must be allocated with 574 * allocate_camera_metadata. The framework takes ownership of the buffer. 575 */ 576 int (*construct_default_request)(const struct camera2_device *, 577 int request_template, 578 camera_metadata_t **request); 579 580 /********************************************************************** 581 * Stream management 582 */ 583 584 /** 585 * allocate_stream: 586 * 587 * Allocate a new output stream for use, defined by the output buffer width, 588 * height, target, and possibly the pixel format. Returns the new stream's 589 * ID, gralloc usage flags, minimum queue buffer count, and possibly the 590 * pixel format, on success. Error conditions: 591 * 592 * - Requesting a width/height/format combination not listed as 593 * supported by the sensor's static characteristics 594 * 595 * - Asking for too many streams of a given format type (2 bayer raw 596 * streams, for example). 597 * 598 * Input parameters: 599 * 600 * - width, height, format: Specification for the buffers to be sent through 601 * this stream. Format is a value from the HAL_PIXEL_FORMAT_* list. If 602 * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform 603 * gralloc module will select a format based on the usage flags provided 604 * by the camera HAL and the consumer of the stream. The camera HAL should 605 * inspect the buffers handed to it in the register_stream_buffers call to 606 * obtain the implementation-specific format if necessary. 607 * 608 * - stream_ops: A structure of function pointers for obtaining and queuing 609 * up buffers for this stream. The underlying stream will be configured 610 * based on the usage and max_buffers outputs. The methods in this 611 * structure may not be called until after allocate_stream returns. 612 * 613 * Output parameters: 614 * 615 * - stream_id: An unsigned integer identifying this stream. This value is 616 * used in incoming requests to identify the stream, and in releasing the 617 * stream. 618 * 619 * - usage: The gralloc usage mask needed by the HAL device for producing 620 * the requested type of data. This is used in allocating new gralloc 621 * buffers for the stream buffer queue. 622 * 623 * - max_buffers: The maximum number of buffers the HAL device may need to 624 * have dequeued at the same time. The device may not dequeue more buffers 625 * than this value at the same time. 626 * 627 */ 628 int (*allocate_stream)( 629 const struct camera2_device *, 630 // inputs 631 uint32_t width, 632 uint32_t height, 633 int format, 634 const camera2_stream_ops_t *stream_ops, 635 // outputs 636 uint32_t *stream_id, 637 uint32_t *format_actual, // IGNORED, will be removed 638 uint32_t *usage, 639 uint32_t *max_buffers); 640 641 /** 642 * Register buffers for a given stream. This is called after a successful 643 * allocate_stream call, and before the first request referencing the stream 644 * is enqueued. This method is intended to allow the HAL device to map or 645 * otherwise prepare the buffers for later use. num_buffers is guaranteed to 646 * be at least max_buffers (from allocate_stream), but may be larger. The 647 * buffers will already be locked for use. At the end of the call, all the 648 * buffers must be ready to be returned to the queue. If the stream format 649 * was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL should 650 * inspect the passed-in buffers here to determine any platform-private 651 * pixel format information. 652 */ 653 int (*register_stream_buffers)( 654 const struct camera2_device *, 655 uint32_t stream_id, 656 int num_buffers, 657 buffer_handle_t *buffers); 658 659 /** 660 * Release a stream. Returns an error if called when get_in_progress_count 661 * is non-zero, or if the stream id is invalid. 662 */ 663 int (*release_stream)( 664 const struct camera2_device *, 665 uint32_t stream_id); 666 667 /** 668 * allocate_reprocess_stream: 669 * 670 * Allocate a new input stream for use, defined by the output buffer width, 671 * height, and the pixel format. Returns the new stream's ID, gralloc usage 672 * flags, and required simultaneously acquirable buffer count, on 673 * success. Error conditions: 674 * 675 * - Requesting a width/height/format combination not listed as 676 * supported by the sensor's static characteristics 677 * 678 * - Asking for too many reprocessing streams to be configured at once. 679 * 680 * Input parameters: 681 * 682 * - width, height, format: Specification for the buffers to be sent through 683 * this stream. Format must be a value from the HAL_PIXEL_FORMAT_* list. 684 * 685 * - reprocess_stream_ops: A structure of function pointers for acquiring 686 * and releasing buffers for this stream. The underlying stream will be 687 * configured based on the usage and max_buffers outputs. 688 * 689 * Output parameters: 690 * 691 * - stream_id: An unsigned integer identifying this stream. This value is 692 * used in incoming requests to identify the stream, and in releasing the 693 * stream. These ids are numbered separately from the input stream ids. 694 * 695 * - consumer_usage: The gralloc usage mask needed by the HAL device for 696 * consuming the requested type of data. This is used in allocating new 697 * gralloc buffers for the stream buffer queue. 698 * 699 * - max_buffers: The maximum number of buffers the HAL device may need to 700 * have acquired at the same time. The device may not have more buffers 701 * acquired at the same time than this value. 702 * 703 */ 704 int (*allocate_reprocess_stream)(const struct camera2_device *, 705 uint32_t width, 706 uint32_t height, 707 uint32_t format, 708 const camera2_stream_in_ops_t *reprocess_stream_ops, 709 // outputs 710 uint32_t *stream_id, 711 uint32_t *consumer_usage, 712 uint32_t *max_buffers); 713 714 /** 715 * allocate_reprocess_stream_from_stream: 716 * 717 * Allocate a new input stream for use, which will use the buffers allocated 718 * for an existing output stream. That is, after the HAL enqueues a buffer 719 * onto the output stream, it may see that same buffer handed to it from 720 * this input reprocessing stream. After the HAL releases the buffer back to 721 * the reprocessing stream, it will be returned to the output queue for 722 * reuse. 723 * 724 * Error conditions: 725 * 726 * - Using an output stream of unsuitable size/format for the basis of the 727 * reprocessing stream. 728 * 729 * - Attempting to allocatee too many reprocessing streams at once. 730 * 731 * Input parameters: 732 * 733 * - output_stream_id: The ID of an existing output stream which has 734 * a size and format suitable for reprocessing. 735 * 736 * - reprocess_stream_ops: A structure of function pointers for acquiring 737 * and releasing buffers for this stream. The underlying stream will use 738 * the same graphics buffer handles as the output stream uses. 739 * 740 * Output parameters: 741 * 742 * - stream_id: An unsigned integer identifying this stream. This value is 743 * used in incoming requests to identify the stream, and in releasing the 744 * stream. These ids are numbered separately from the input stream ids. 745 * 746 * The HAL client must always release the reprocessing stream before it 747 * releases the output stream it is based on. 748 * 749 */ 750 int (*allocate_reprocess_stream_from_stream)(const struct camera2_device *, 751 uint32_t output_stream_id, 752 const camera2_stream_in_ops_t *reprocess_stream_ops, 753 // outputs 754 uint32_t *stream_id); 755 756 /** 757 * Release a reprocessing stream. Returns an error if called when 758 * get_in_progress_count is non-zero, or if the stream id is not 759 * valid. 760 */ 761 int (*release_reprocess_stream)( 762 const struct camera2_device *, 763 uint32_t stream_id); 764 765 /********************************************************************** 766 * Miscellaneous methods 767 */ 768 769 /** 770 * Trigger asynchronous activity. This is used for triggering special 771 * behaviors of the camera 3A routines when they are in use. See the 772 * documentation for CAMERA2_TRIGGER_* above for details of the trigger ids 773 * and their arguments. 774 */ 775 int (*trigger_action)(const struct camera2_device *, 776 uint32_t trigger_id, 777 int32_t ext1, 778 int32_t ext2); 779 780 /** 781 * Notification callback setup 782 */ 783 int (*set_notify_callback)(const struct camera2_device *, 784 camera2_notify_callback notify_cb, 785 void *user); 786 787 /** 788 * Get methods to query for vendor extension metadata tag infomation. May 789 * set ops to NULL if no vendor extension tags are defined. 790 */ 791 int (*get_metadata_vendor_tag_ops)(const struct camera2_device*, 792 vendor_tag_query_ops_t **ops); 793 794 /** 795 * Dump state of the camera hardware 796 */ 797 int (*dump)(const struct camera2_device *, int fd); 798 799 /** 800 * Get device-instance-specific metadata. This metadata must be constant for 801 * a single instance of the camera device, but may be different between 802 * open() calls. The returned camera_metadata pointer must be valid until 803 * the device close() method is called. 804 * 805 * Version information: 806 * 807 * CAMERA_DEVICE_API_VERSION_2_0: 808 * 809 * Not available. Framework may not access this function pointer. 810 * 811 * CAMERA_DEVICE_API_VERSION_2_1: 812 * 813 * Valid. Can be called by the framework. 814 * 815 */ 816 int (*get_instance_metadata)(const struct camera2_device *, 817 camera_metadata **instance_metadata); 818 819 } camera2_device_ops_t; 820 821 /********************************************************************** 822 * 823 * Camera device definition 824 * 825 */ 826 typedef struct camera2_device { 827 /** 828 * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify 829 * this device as implementing version 2.0 of the camera device HAL. 830 */ 831 hw_device_t common; 832 camera2_device_ops_t *ops; 833 void *priv; 834 } camera2_device_t; 835 836 __END_DECLS 837 838 #endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */ 839