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