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