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