camera2.h
Go to the documentation of this file.
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 
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,
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 };
150 
151 enum {
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 
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 {
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  */
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  */
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  */
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  */
244  camera_metadata_t *old_buffer);
245 
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  */
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  */
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  */
279  camera_metadata_t *buffer);
280 
281  /**
282  * Place a completed metadata frame on the frame output queue.
283  */
285  camera_metadata_t *buffer);
286 
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
388  /**
389  * Number of error types
390  */
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  */
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  */
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  */
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  */
494  /**
495  * Standard camera high-quality still capture with 3A and flash on auto.
496  */
498  /**
499  * Standard video recording plus preview with 3A on auto, torch off.
500  */
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  */
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  */
516 
517  /* Total number of templates */
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  */
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  */
545 
546  /**
547  * Pass in output frame queue interface methods
548  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 
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  */
837  void *priv;
839 
840 __END_DECLS
841 
842 #endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */
int(* enqueue_buffer)(const struct camera2_stream_ops *w, int64_t timestamp, buffer_handle_t *buffer)
Definition: camera2.h:96
struct camera_metadata camera_metadata_t
int(* enqueue_frame)(const struct camera2_frame_queue_dst_ops *q, camera_metadata_t *buffer)
Definition: camera2.h:284
int(* allocate_stream)(const struct camera2_device *, uint32_t width, uint32_t height, int format, const camera2_stream_ops_t *stream_ops, uint32_t *stream_id, uint32_t *format_actual, uint32_t *usage, uint32_t *max_buffers)
Definition: camera2.h:632
int(* release_stream)(const struct camera2_device *, uint32_t stream_id)
Definition: camera2.h:667
int(* release_buffer)(const struct camera2_stream_in_ops *w, buffer_handle_t *buffer)
Definition: camera2.h:172
camera2_device_ops_t * ops
Definition: camera2.h:836
int(* construct_default_request)(const struct camera2_device *, int request_template, camera_metadata_t **request)
Definition: camera2.h:580
int(* cancel_frame)(const struct camera2_frame_queue_dst_ops *q, camera_metadata_t *buffer)
Definition: camera2.h:278
int(* notify_request_queue_not_empty)(const struct camera2_device *)
Definition: camera2.h:544
int(* trigger_action)(const struct camera2_device *, uint32_t trigger_id, int32_t ext1, int32_t ext2)
Definition: camera2.h:779
uint32_t jpeg_size
Definition: camera2.h:148
struct camera2_device camera2_device_t
int(* set_request_queue_src_ops)(const struct camera2_device *, const camera2_request_queue_src_ops_t *request_src_ops)
Definition: camera2.h:536
int(* allocate_reprocess_stream)(const struct camera2_device *, uint32_t width, uint32_t height, uint32_t format, const camera2_stream_in_ops_t *reprocess_stream_ops, uint32_t *stream_id, uint32_t *consumer_usage, uint32_t *max_buffers)
Definition: camera2.h:708
int(* release_reprocess_stream)(const struct camera2_device *, uint32_t stream_id)
Definition: camera2.h:765
struct camera2_frame_queue_dst_ops camera2_frame_queue_dst_ops_t
int(* get_metadata_vendor_tag_ops)(const struct camera2_device *, vendor_tag_query_ops_t **ops)
Definition: camera2.h:795
int(* cancel_buffer)(const struct camera2_stream_ops *w, buffer_handle_t *buffer)
Definition: camera2.h:102
int(* get_instance_metadata)(const struct camera2_device *, camera_metadata **instance_metadata)
Definition: camera2.h:820
int(* free_request)(const struct camera2_request_queue_src_ops *q, camera_metadata_t *old_buffer)
Definition: camera2.h:243
hw_device_t common
Definition: camera2.h:835
void * priv
Definition: camera2.h:837
int(* flush_captures_in_progress)(const struct camera2_device *)
Definition: camera2.h:567
int(* register_stream_buffers)(const struct camera2_device *, uint32_t stream_id, int num_buffers, buffer_handle_t *buffers)
Definition: camera2.h:657
struct camera2_stream_in_ops camera2_stream_in_ops_t
int(* allocate_reprocess_stream_from_stream)(const struct camera2_device *, uint32_t output_stream_id, const camera2_stream_in_ops_t *reprocess_stream_ops, uint32_t *stream_id)
Definition: camera2.h:754
int(* dequeue_buffer)(const struct camera2_stream_ops *w, buffer_handle_t **buffer)
Definition: camera2.h:81
int(* set_crop)(const struct camera2_stream_ops *w, int left, int top, int right, int bottom)
Definition: camera2.h:108
struct camera2_stream_ops camera2_stream_ops_t
int(* dequeue_frame)(const struct camera2_frame_queue_dst_ops *q, size_t entries, size_t data_bytes, camera_metadata_t **buffer)
Definition: camera2.h:270
int(* set_frame_queue_dst_ops)(const struct camera2_device *, const camera2_frame_queue_dst_ops_t *frame_dst_ops)
Definition: camera2.h:549
struct camera2_device_ops camera2_device_ops_t
int(* dequeue_request)(const struct camera2_request_queue_src_ops *q, camera_metadata_t **buffer)
Definition: camera2.h:237
int(* dump)(const struct camera2_device *, int fd)
Definition: camera2.h:801
struct camera2_request_queue_src_ops camera2_request_queue_src_ops_t
int(* acquire_buffer)(const struct camera2_stream_in_ops *w, buffer_handle_t **buffer)
Definition: camera2.h:167
int(* request_count)(const struct camera2_request_queue_src_ops *q)
Definition: camera2.h:228
uint16_t jpeg_blob_id
Definition: camera2.h:147
int(* get_in_progress_count)(const struct camera2_device *)
Definition: camera2.h:558
int(* set_notify_callback)(const struct camera2_device *, camera2_notify_callback notify_cb, void *user)
Definition: camera2.h:787
void(* camera2_notify_callback)(int32_t msg_type, int32_t ext1, int32_t ext2, int32_t ext3, void *user)
Definition: camera2.h:301