hardware/camera2.h

   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 */