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