2 * Copyright (C) 2012 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef ANDROID_INCLUDE_CAMERA2_H
18 #define ANDROID_INCLUDE_CAMERA2_H
20 #include "camera_common.h"
21 #include "system/camera_metadata.h"
24 * Camera device HAL 2.1 [ CAMERA_DEVICE_API_VERSION_2_0, CAMERA_DEVICE_API_VERSION_2_1 ]
28 * Supports the android.hardware.Camera APIs.
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).
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).
38 * See camera_common.h for more versioning details.
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.
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.
55 struct camera2_device;
57 /**********************************************************************
59 * Input/output stream buffer queue interface definitions
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.
69 typedef struct camera2_stream_ops {
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.
77 int (*dequeue_buffer)(const struct camera2_stream_ops* w,
78 buffer_handle_t** buffer);
81 * Push a filled buffer to the stream to be used by the consumer.
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.
92 int (*enqueue_buffer)(const struct camera2_stream_ops* w,
94 buffer_handle_t* buffer);
96 * Return a buffer to the queue without marking it as filled.
98 int (*cancel_buffer)(const struct camera2_stream_ops* w,
99 buffer_handle_t* buffer);
101 * Set the crop window for subsequently enqueued buffers. The parameters are
102 * measured in pixels relative to the buffer width and height.
104 int (*set_crop)(const struct camera2_stream_ops *w,
105 int left, int top, int right, int bottom);
107 } camera2_stream_ops_t;
110 * Temporary definition during transition.
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
122 CAMERA2_HAL_PIXEL_FORMAT_OPAQUE = HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED,
123 CAMERA2_HAL_PIXEL_FORMAT_ZSL = -1
127 * Transport header for compressed JPEG buffers in output streams.
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.
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.
142 typedef struct camera2_jpeg_blob {
143 uint16_t jpeg_blob_id;
148 CAMERA2_JPEG_BLOB_ID = 0x00FF
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.
156 typedef struct camera2_stream_in_ops {
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.
163 int (*acquire_buffer)(const struct camera2_stream_in_ops *w,
164 buffer_handle_t** buffer);
166 * Return a used buffer to the buffer queue for reuse.
168 int (*release_buffer)(const struct camera2_stream_in_ops *w,
169 buffer_handle_t* buffer);
171 } camera2_stream_in_ops_t;
173 /**********************************************************************
175 * Metadata queue management, used for requests sent to HAL module, and for
176 * frames produced by the HAL.
181 CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS = -1
185 * Request input queue protocol:
187 * The framework holds the queue and its contents. At start, the queue is empty.
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().
192 * 2. After receiving notify_request_queue_not_empty, the device must call
193 * dequeue() once it's ready to handle the next buffer.
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.
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.
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.
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.
216 typedef struct camera2_request_queue_src_ops {
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
224 int (*request_count)(const struct camera2_request_queue_src_ops *q);
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().
233 int (*dequeue_request)(const struct camera2_request_queue_src_ops *q,
234 camera_metadata_t **buffer);
236 * Return a metadata buffer to the framework once it has been used, or if
237 * an error or shutdown occurs.
239 int (*free_request)(const struct camera2_request_queue_src_ops *q,
240 camera_metadata_t *old_buffer);
242 } camera2_request_queue_src_ops_t;
245 * Frame output queue protocol:
247 * The framework holds the queue and its contents. At start, the queue is empty.
249 * 1. When the device is ready to fill an output metadata frame, it must dequeue
250 * a metadata buffer of the required size.
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.
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.
259 typedef struct camera2_frame_queue_dst_ops {
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.
266 int (*dequeue_frame)(const struct camera2_frame_queue_dst_ops *q,
267 size_t entries, size_t data_bytes,
268 camera_metadata_t **buffer);
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.
274 int (*cancel_frame)(const struct camera2_frame_queue_dst_ops *q,
275 camera_metadata_t *buffer);
278 * Place a completed metadata frame on the frame output queue.
280 int (*enqueue_frame)(const struct camera2_frame_queue_dst_ops *q,
281 camera_metadata_t *buffer);
283 } camera2_frame_queue_dst_ops_t;
285 /**********************************************************************
287 * Notification callback and message definition, and trigger definitions
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().
297 typedef void (*camera2_notify_callback)(int32_t msg_type,
304 * Possible message types for camera2_notify_callback
308 * An error has occurred. Argument ext1 contains the error code, and
309 * ext2 and ext3 contain any error-specific information.
311 CAMERA2_MSG_ERROR = 0x0001,
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))
318 CAMERA2_MSG_SHUTTER = 0x0010,
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.
327 CAMERA2_MSG_AUTOFOCUS = 0x0020,
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.
335 CAMERA2_MSG_AUTOEXPOSURE = 0x0021,
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.
343 CAMERA2_MSG_AUTOWB = 0x0022
347 * Error codes for CAMERA_MSG_ERROR
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.
355 CAMERA2_MSG_ERROR_HARDWARE = 0x0001,
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.
361 CAMERA2_MSG_ERROR_DEVICE,
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.
368 CAMERA2_MSG_ERROR_REQUEST,
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.
375 CAMERA2_MSG_ERROR_FRAME,
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.
383 CAMERA2_MSG_ERROR_STREAM,
385 * Number of error types
387 CAMERA2_MSG_NUM_ERRORS
391 * Possible trigger ids for trigger_action()
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.
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:
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
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.
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
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.
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
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.
447 CAMERA2_TRIGGER_AUTOFOCUS = 0x0001,
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
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.
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.
466 CAMERA2_TRIGGER_CANCEL_AUTOFOCUS,
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.
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.
479 CAMERA2_TRIGGER_PRECAPTURE_METERING
483 * Possible template types for construct_default_request()
487 * Standard camera preview operation with 3A on auto.
489 CAMERA2_TEMPLATE_PREVIEW = 1,
491 * Standard camera high-quality still capture with 3A and flash on auto.
493 CAMERA2_TEMPLATE_STILL_CAPTURE,
495 * Standard video recording plus preview with 3A on auto, torch off.
497 CAMERA2_TEMPLATE_VIDEO_RECORD,
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.
503 CAMERA2_TEMPLATE_VIDEO_SNAPSHOT,
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
511 CAMERA2_TEMPLATE_ZERO_SHUTTER_LAG,
513 /* Total number of templates */
514 CAMERA2_TEMPLATE_COUNT
518 /**********************************************************************
520 * Camera device operations
523 typedef struct camera2_device_ops {
525 /**********************************************************************
526 * Request and frame queue setup and management methods
530 * Pass in input request queue interface methods.
532 int (*set_request_queue_src_ops)(const struct camera2_device *,
533 const camera2_request_queue_src_ops_t *request_src_ops);
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.
540 int (*notify_request_queue_not_empty)(const struct camera2_device *);
543 * Pass in output frame queue interface methods
545 int (*set_frame_queue_dst_ops)(const struct camera2_device *,
546 const camera2_frame_queue_dst_ops_t *frame_dst_ops);
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.
554 int (*get_in_progress_count)(const struct camera2_device *);
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.
563 int (*flush_captures_in_progress)(const struct camera2_device *);
566 * Create a filled-in default request for standard camera use cases.
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.
573 * The metadata buffer returned must be allocated with
574 * allocate_camera_metadata. The framework takes ownership of the buffer.
576 int (*construct_default_request)(const struct camera2_device *,
577 int request_template,
578 camera_metadata_t **request);
580 /**********************************************************************
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:
592 * - Requesting a width/height/format combination not listed as
593 * supported by the sensor's static characteristics
595 * - Asking for too many streams of a given format type (2 bayer raw
596 * streams, for example).
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.
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.
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
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.
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.
628 int (*allocate_stream)(
629 const struct camera2_device *,
634 const camera2_stream_ops_t *stream_ops,
637 uint32_t *format_actual, // IGNORED, will be removed
639 uint32_t *max_buffers);
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.
653 int (*register_stream_buffers)(
654 const struct camera2_device *,
657 buffer_handle_t *buffers);
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.
663 int (*release_stream)(
664 const struct camera2_device *,
668 * allocate_reprocess_stream:
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:
675 * - Requesting a width/height/format combination not listed as
676 * supported by the sensor's static characteristics
678 * - Asking for too many reprocessing streams to be configured at once.
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.
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.
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.
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.
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.
704 int (*allocate_reprocess_stream)(const struct camera2_device *,
708 const camera2_stream_in_ops_t *reprocess_stream_ops,
711 uint32_t *consumer_usage,
712 uint32_t *max_buffers);
715 * allocate_reprocess_stream_from_stream:
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
726 * - Using an output stream of unsuitable size/format for the basis of the
727 * reprocessing stream.
729 * - Attempting to allocatee too many reprocessing streams at once.
733 * - output_stream_id: The ID of an existing output stream which has
734 * a size and format suitable for reprocessing.
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.
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.
746 * The HAL client must always release the reprocessing stream before it
747 * releases the output stream it is based on.
750 int (*allocate_reprocess_stream_from_stream)(const struct camera2_device *,
751 uint32_t output_stream_id,
752 const camera2_stream_in_ops_t *reprocess_stream_ops,
754 uint32_t *stream_id);
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
761 int (*release_reprocess_stream)(
762 const struct camera2_device *,
765 /**********************************************************************
766 * Miscellaneous methods
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.
775 int (*trigger_action)(const struct camera2_device *,
781 * Notification callback setup
783 int (*set_notify_callback)(const struct camera2_device *,
784 camera2_notify_callback notify_cb,
788 * Get methods to query for vendor extension metadata tag infomation. May
789 * set ops to NULL if no vendor extension tags are defined.
791 int (*get_metadata_vendor_tag_ops)(const struct camera2_device*,
792 vendor_tag_query_ops_t **ops);
795 * Dump state of the camera hardware
797 int (*dump)(const struct camera2_device *, int fd);
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.
805 * Version information:
807 * CAMERA_DEVICE_API_VERSION_2_0:
809 * Not available. Framework may not access this function pointer.
811 * CAMERA_DEVICE_API_VERSION_2_1:
813 * Valid. Can be called by the framework.
816 int (*get_instance_metadata)(const struct camera2_device *,
817 camera_metadata **instance_metadata);
819 } camera2_device_ops_t;
821 /**********************************************************************
823 * Camera device definition
826 typedef struct camera2_device {
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.
832 camera2_device_ops_t *ops;
838 #endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */