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