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