camera3.h revision 5a5fbf489e118493bca15c2a6bafbe65887f5b2f
1/* 2 * Copyright (C) 2013 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_CAMERA3_H 18#define ANDROID_INCLUDE_CAMERA3_H 19 20#include <system/camera_metadata.h> 21#include "camera_common.h" 22 23/** 24 * Camera device HAL 3.2 [ CAMERA_DEVICE_API_VERSION_3_2 ] 25 * 26 * EXPERIMENTAL. 27 * 28 * Supports the android.hardware.Camera API. 29 * 30 * Camera devices that support this version of the HAL must return 31 * CAMERA_DEVICE_API_VERSION_3_2 in camera_device_t.common.version and in 32 * camera_info_t.device_version (from camera_module_t.get_camera_info). 33 * 34 * CAMERA_DEVICE_API_VERSION_3_2: 35 * Camera modules that may contain version 3.2 devices must implement at 36 * least version 2.2 of the camera module interface (as defined by 37 * camera_module_t.common.module_api_version). 38 * 39 * <= CAMERA_DEVICE_API_VERSION_3_1: 40 * Camera modules that may contain version 3.1 (or 3.0) devices must 41 * implement at least version 2.0 of the camera module interface 42 * (as defined by camera_module_t.common.module_api_version). 43 * 44 * See camera_common.h for more versioning details. 45 * 46 * Documentation index: 47 * S1. Version history 48 * S2. Startup and operation sequencing 49 * S3. Operational modes 50 * S4. 3A modes and state machines 51 * S5. Cropping 52 * S6. Error management 53 * S7. Key Performance Indicator (KPI) glossary 54 */ 55 56/** 57 * S1. Version history: 58 * 59 * 1.0: Initial Android camera HAL (Android 4.0) [camera.h]: 60 * 61 * - Converted from C++ CameraHardwareInterface abstraction layer. 62 * 63 * - Supports android.hardware.Camera API. 64 * 65 * 2.0: Initial release of expanded-capability HAL (Android 4.2) [camera2.h]: 66 * 67 * - Sufficient for implementing existing android.hardware.Camera API. 68 * 69 * - Allows for ZSL queue in camera service layer 70 * 71 * - Not tested for any new features such manual capture control, Bayer RAW 72 * capture, reprocessing of RAW data. 73 * 74 * 3.0: First revision of expanded-capability HAL: 75 * 76 * - Major version change since the ABI is completely different. No change to 77 * the required hardware capabilities or operational model from 2.0. 78 * 79 * - Reworked input request and stream queue interfaces: Framework calls into 80 * HAL with next request and stream buffers already dequeued. Sync framework 81 * support is included, necessary for efficient implementations. 82 * 83 * - Moved triggers into requests, most notifications into results. 84 * 85 * - Consolidated all callbacks into framework into one structure, and all 86 * setup methods into a single initialize() call. 87 * 88 * - Made stream configuration into a single call to simplify stream 89 * management. Bidirectional streams replace STREAM_FROM_STREAM construct. 90 * 91 * - Limited mode semantics for older/limited hardware devices. 92 * 93 * 3.1: Minor revision of expanded-capability HAL: 94 * 95 * - configure_streams passes consumer usage flags to the HAL. 96 * 97 * - flush call to drop all in-flight requests/buffers as fast as possible. 98 * 99 * 3.2: Minor revision of expanded-capability HAL: 100 * 101 * - Deprecates get_metadata_vendor_tag_ops. Please use get_vendor_tag_ops 102 * in camera_common.h instead. 103 * 104 * - register_stream_buffers deprecated. All gralloc buffers provided 105 * by framework to HAL in process_capture_request may be new at any time. 106 * 107 * - add partial result support. process_capture_result may be called 108 * multiple times with a subset of the available result before the full 109 * result is available. 110 */ 111 112/** 113 * S2. Startup and general expected operation sequence: 114 * 115 * 1. Framework calls camera_module_t->common.open(), which returns a 116 * hardware_device_t structure. 117 * 118 * 2. Framework inspects the hardware_device_t->version field, and instantiates 119 * the appropriate handler for that version of the camera hardware device. In 120 * case the version is CAMERA_DEVICE_API_VERSION_3_0, the device is cast to 121 * a camera3_device_t. 122 * 123 * 3. Framework calls camera3_device_t->ops->initialize() with the framework 124 * callback function pointers. This will only be called this one time after 125 * open(), before any other functions in the ops structure are called. 126 * 127 * 4. The framework calls camera3_device_t->ops->configure_streams() with a list 128 * of input/output streams to the HAL device. 129 * 130 * 5. <= CAMERA_DEVICE_API_VERSION_3_1: 131 * 132 * The framework allocates gralloc buffers and calls 133 * camera3_device_t->ops->register_stream_buffers() for at least one of the 134 * output streams listed in configure_streams. The same stream is registered 135 * only once. 136 * 137 * >= CAMERA_DEVICE_API_VERSION_3_2: 138 * 139 * camera3_device_t->ops->register_stream_buffers() is not called and must 140 * be NULL. 141 * 142 * 6. The framework requests default settings for some number of use cases with 143 * calls to camera3_device_t->ops->construct_default_request_settings(). This 144 * may occur any time after step 3. 145 * 146 * 7. The framework constructs and sends the first capture request to the HAL, 147 * with settings based on one of the sets of default settings, and with at 148 * least one output stream, which has been registered earlier by the 149 * framework. This is sent to the HAL with 150 * camera3_device_t->ops->process_capture_request(). The HAL must block the 151 * return of this call until it is ready for the next request to be sent. 152 * 153 * >= CAMERA_DEVICE_API_VERSION_3_2: 154 * 155 * The buffer_handle_t provided in the camera3_stream_buffer_t array 156 * in the camera3_capture_request_t may be new and never-before-seen 157 * by the HAL on any given new request. 158 * 159 * 8. The framework continues to submit requests, and call 160 * construct_default_request_settings to get default settings buffers for 161 * other use cases. 162 * 163 * <= CAMERA_DEVICE_API_VERSION_3_1: 164 * 165 * The framework may call register_stream_buffers() at this time for 166 * not-yet-registered streams. 167 * 168 * 9. When the capture of a request begins (sensor starts exposing for the 169 * capture), the HAL calls camera3_callback_ops_t->notify() with the SHUTTER 170 * event, including the frame number and the timestamp for start of exposure. 171 * 172 * <= CAMERA_DEVICE_API_VERSION_3_1: 173 * 174 * This notify call must be made before the first call to 175 * process_capture_result() for that frame number. 176 * 177 * >= CAMERA_DEVICE_API_VERSION_3_2: 178 * 179 * The camera3_callback_ops_t->notify() call with the SHUTTER event should 180 * be made as early as possible since the framework will be unable to 181 * deliver gralloc buffers to the application layer (for that frame) until 182 * it has a valid timestamp for the start of exposure. 183 * 184 * Both partial metadata results and the gralloc buffers may be sent to the 185 * framework at any time before or after the SHUTTER event. 186 * 187 * 10. After some pipeline delay, the HAL begins to return completed captures to 188 * the framework with camera3_callback_ops_t->process_capture_result(). These 189 * are returned in the same order as the requests were submitted. Multiple 190 * requests can be in flight at once, depending on the pipeline depth of the 191 * camera HAL device. 192 * 193 * >= CAMERA_DEVICE_API_VERSION_3_2: 194 * 195 * Once a buffer is returned by process_capture_result as part of the 196 * camera3_stream_buffer_t array, and the fence specified by release_fence 197 * has been signaled (this is a no-op for -1 fences), the ownership of that 198 * buffer is considered to be transferred back to the framework. After that, 199 * the HAL must no longer retain that particular buffer, and the 200 * framework may clean up the memory for it immediately. 201 * 202 * process_capture_result may be called multiple times for a single frame, 203 * each time with a new disjoint piece of metadata and/or set of gralloc 204 * buffers. The framework will accumulate these partial metadata results 205 * into one result. 206 * 207 * In particular, it is legal for a process_capture_result to be called 208 * simultaneously for both a frame N and a frame N+1 as long as the 209 * above rule holds for gralloc buffers. 210 * 211 * 11. After some time, the framework may stop submitting new requests, wait for 212 * the existing captures to complete (all buffers filled, all results 213 * returned), and then call configure_streams() again. This resets the camera 214 * hardware and pipeline for a new set of input/output streams. Some streams 215 * may be reused from the previous configuration; if these streams' buffers 216 * had already been registered with the HAL, they will not be registered 217 * again. The framework then continues from step 7, if at least one 218 * registered output stream remains (otherwise, step 5 is required first). 219 * 220 * 12. Alternatively, the framework may call camera3_device_t->common->close() 221 * to end the camera session. This may be called at any time when no other 222 * calls from the framework are active, although the call may block until all 223 * in-flight captures have completed (all results returned, all buffers 224 * filled). After the close call returns, no more calls to the 225 * camera3_callback_ops_t functions are allowed from the HAL. Once the 226 * close() call is underway, the framework may not call any other HAL device 227 * functions. 228 * 229 * 13. In case of an error or other asynchronous event, the HAL must call 230 * camera3_callback_ops_t->notify() with the appropriate error/event 231 * message. After returning from a fatal device-wide error notification, the 232 * HAL should act as if close() had been called on it. However, the HAL must 233 * either cancel or complete all outstanding captures before calling 234 * notify(), so that once notify() is called with a fatal error, the 235 * framework will not receive further callbacks from the device. Methods 236 * besides close() should return -ENODEV or NULL after the notify() method 237 * returns from a fatal error message. 238 */ 239 240/** 241 * S3. Operational modes: 242 * 243 * The camera 3 HAL device can implement one of two possible operational modes; 244 * limited and full. Full support is expected from new higher-end 245 * devices. Limited mode has hardware requirements roughly in line with those 246 * for a camera HAL device v1 implementation, and is expected from older or 247 * inexpensive devices. Full is a strict superset of limited, and they share the 248 * same essential operational flow, as documented above. 249 * 250 * The HAL must indicate its level of support with the 251 * android.info.supportedHardwareLevel static metadata entry, with 0 indicating 252 * limited mode, and 1 indicating full mode support. 253 * 254 * Roughly speaking, limited-mode devices do not allow for application control 255 * of capture settings (3A control only), high-rate capture of high-resolution 256 * images, raw sensor readout, or support for YUV output streams above maximum 257 * recording resolution (JPEG only for large images). 258 * 259 * ** Details of limited mode behavior: 260 * 261 * - Limited-mode devices do not need to implement accurate synchronization 262 * between capture request settings and the actual image data 263 * captured. Instead, changes to settings may take effect some time in the 264 * future, and possibly not for the same output frame for each settings 265 * entry. Rapid changes in settings may result in some settings never being 266 * used for a capture. However, captures that include high-resolution output 267 * buffers ( > 1080p ) have to use the settings as specified (but see below 268 * for processing rate). 269 * 270 * - Limited-mode devices do not need to support most of the 271 * settings/result/static info metadata. Full-mode devices must support all 272 * metadata fields listed in TODO. Specifically, only the following settings 273 * are expected to be consumed or produced by a limited-mode HAL device: 274 * 275 * android.control.aeAntibandingMode (controls) 276 * android.control.aeExposureCompensation (controls) 277 * android.control.aeLock (controls) 278 * android.control.aeMode (controls) 279 * [OFF means ON_FLASH_TORCH - TODO] 280 * android.control.aeRegions (controls) 281 * android.control.aeTargetFpsRange (controls) 282 * android.control.afMode (controls) 283 * [OFF means infinity focus] 284 * android.control.afRegions (controls) 285 * android.control.awbLock (controls) 286 * android.control.awbMode (controls) 287 * [OFF not supported] 288 * android.control.awbRegions (controls) 289 * android.control.captureIntent (controls) 290 * android.control.effectMode (controls) 291 * android.control.mode (controls) 292 * [OFF not supported] 293 * android.control.sceneMode (controls) 294 * android.control.videoStabilizationMode (controls) 295 * android.control.aeAvailableAntibandingModes (static) 296 * android.control.aeAvailableModes (static) 297 * android.control.aeAvailableTargetFpsRanges (static) 298 * android.control.aeCompensationRange (static) 299 * android.control.aeCompensationStep (static) 300 * android.control.afAvailableModes (static) 301 * android.control.availableEffects (static) 302 * android.control.availableSceneModes (static) 303 * android.control.availableVideoStabilizationModes (static) 304 * android.control.awbAvailableModes (static) 305 * android.control.maxRegions (static) 306 * android.control.sceneModeOverrides (static) 307 * android.control.aeRegions (dynamic) 308 * android.control.aeState (dynamic) 309 * android.control.afMode (dynamic) 310 * android.control.afRegions (dynamic) 311 * android.control.afState (dynamic) 312 * android.control.awbMode (dynamic) 313 * android.control.awbRegions (dynamic) 314 * android.control.awbState (dynamic) 315 * android.control.mode (dynamic) 316 * 317 * android.flash.info.available (static) 318 * 319 * android.info.supportedHardwareLevel (static) 320 * 321 * android.jpeg.gpsCoordinates (controls) 322 * android.jpeg.gpsProcessingMethod (controls) 323 * android.jpeg.gpsTimestamp (controls) 324 * android.jpeg.orientation (controls) 325 * android.jpeg.quality (controls) 326 * android.jpeg.thumbnailQuality (controls) 327 * android.jpeg.thumbnailSize (controls) 328 * android.jpeg.availableThumbnailSizes (static) 329 * android.jpeg.maxSize (static) 330 * android.jpeg.gpsCoordinates (dynamic) 331 * android.jpeg.gpsProcessingMethod (dynamic) 332 * android.jpeg.gpsTimestamp (dynamic) 333 * android.jpeg.orientation (dynamic) 334 * android.jpeg.quality (dynamic) 335 * android.jpeg.size (dynamic) 336 * android.jpeg.thumbnailQuality (dynamic) 337 * android.jpeg.thumbnailSize (dynamic) 338 * 339 * android.lens.info.minimumFocusDistance (static) 340 * 341 * android.request.id (controls) 342 * android.request.id (dynamic) 343 * 344 * android.scaler.cropRegion (controls) 345 * [ignores (x,y), assumes center-zoom] 346 * android.scaler.availableFormats (static) 347 * [RAW not supported] 348 * android.scaler.availableJpegMinDurations (static) 349 * android.scaler.availableJpegSizes (static) 350 * android.scaler.availableMaxDigitalZoom (static) 351 * android.scaler.availableProcessedMinDurations (static) 352 * android.scaler.availableProcessedSizes (static) 353 * [full resolution not supported] 354 * android.scaler.maxDigitalZoom (static) 355 * android.scaler.cropRegion (dynamic) 356 * 357 * android.sensor.orientation (static) 358 * android.sensor.timestamp (dynamic) 359 * 360 * android.statistics.faceDetectMode (controls) 361 * android.statistics.info.availableFaceDetectModes (static) 362 * android.statistics.faceDetectMode (dynamic) 363 * android.statistics.faceIds (dynamic) 364 * android.statistics.faceLandmarks (dynamic) 365 * android.statistics.faceRectangles (dynamic) 366 * android.statistics.faceScores (dynamic) 367 * 368 * - Captures in limited mode that include high-resolution (> 1080p) output 369 * buffers may block in process_capture_request() until all the output buffers 370 * have been filled. A full-mode HAL device must process sequences of 371 * high-resolution requests at the rate indicated in the static metadata for 372 * that pixel format. The HAL must still call process_capture_result() to 373 * provide the output; the framework must simply be prepared for 374 * process_capture_request() to block until after process_capture_result() for 375 * that request completes for high-resolution captures for limited-mode 376 * devices. 377 * 378 */ 379 380/** 381 * S4. 3A modes and state machines: 382 * 383 * While the actual 3A algorithms are up to the HAL implementation, a high-level 384 * state machine description is defined by the HAL interface, to allow the HAL 385 * device and the framework to communicate about the current state of 3A, and to 386 * trigger 3A events. 387 * 388 * When the device is opened, all the individual 3A states must be 389 * STATE_INACTIVE. Stream configuration does not reset 3A. For example, locked 390 * focus must be maintained across the configure() call. 391 * 392 * Triggering a 3A action involves simply setting the relevant trigger entry in 393 * the settings for the next request to indicate start of trigger. For example, 394 * the trigger for starting an autofocus scan is setting the entry 395 * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTROL_AF_TRIGGER_START for one 396 * request, and cancelling an autofocus scan is triggered by setting 397 * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTRL_AF_TRIGGER_CANCEL. Otherwise, 398 * the entry will not exist, or be set to ANDROID_CONTROL_AF_TRIGGER_IDLE. Each 399 * request with a trigger entry set to a non-IDLE value will be treated as an 400 * independent triggering event. 401 * 402 * At the top level, 3A is controlled by the ANDROID_CONTROL_MODE setting, which 403 * selects between no 3A (ANDROID_CONTROL_MODE_OFF), normal AUTO mode 404 * (ANDROID_CONTROL_MODE_AUTO), and using the scene mode setting 405 * (ANDROID_CONTROL_USE_SCENE_MODE). 406 * 407 * - In OFF mode, each of the individual AE/AF/AWB modes are effectively OFF, 408 * and none of the capture controls may be overridden by the 3A routines. 409 * 410 * - In AUTO mode, Auto-focus, auto-exposure, and auto-whitebalance all run 411 * their own independent algorithms, and have their own mode, state, and 412 * trigger metadata entries, as listed in the next section. 413 * 414 * - In USE_SCENE_MODE, the value of the ANDROID_CONTROL_SCENE_MODE entry must 415 * be used to determine the behavior of 3A routines. In SCENE_MODEs other than 416 * FACE_PRIORITY, the HAL must override the values of 417 * ANDROId_CONTROL_AE/AWB/AF_MODE to be the mode it prefers for the selected 418 * SCENE_MODE. For example, the HAL may prefer SCENE_MODE_NIGHT to use 419 * CONTINUOUS_FOCUS AF mode. Any user selection of AE/AWB/AF_MODE when scene 420 * must be ignored for these scene modes. 421 * 422 * - For SCENE_MODE_FACE_PRIORITY, the AE/AWB/AF_MODE controls work as in 423 * ANDROID_CONTROL_MODE_AUTO, but the 3A routines must bias toward metering 424 * and focusing on any detected faces in the scene. 425 * 426 * S4.1. Auto-focus settings and result entries: 427 * 428 * Main metadata entries: 429 * 430 * ANDROID_CONTROL_AF_MODE: Control for selecting the current autofocus 431 * mode. Set by the framework in the request settings. 432 * 433 * AF_MODE_OFF: AF is disabled; the framework/app directly controls lens 434 * position. 435 * 436 * AF_MODE_AUTO: Single-sweep autofocus. No lens movement unless AF is 437 * triggered. 438 * 439 * AF_MODE_MACRO: Single-sweep up-close autofocus. No lens movement unless 440 * AF is triggered. 441 * 442 * AF_MODE_CONTINUOUS_VIDEO: Smooth continuous focusing, for recording 443 * video. Triggering immediately locks focus in current 444 * position. Canceling resumes cotinuous focusing. 445 * 446 * AF_MODE_CONTINUOUS_PICTURE: Fast continuous focusing, for 447 * zero-shutter-lag still capture. Triggering locks focus once currently 448 * active sweep concludes. Canceling resumes continuous focusing. 449 * 450 * AF_MODE_EDOF: Advanced extended depth of field focusing. There is no 451 * autofocus scan, so triggering one or canceling one has no effect. 452 * Images are focused automatically by the HAL. 453 * 454 * ANDROID_CONTROL_AF_STATE: Dynamic metadata describing the current AF 455 * algorithm state, reported by the HAL in the result metadata. 456 * 457 * AF_STATE_INACTIVE: No focusing has been done, or algorithm was 458 * reset. Lens is not moving. Always the state for MODE_OFF or MODE_EDOF. 459 * When the device is opened, it must start in this state. 460 * 461 * AF_STATE_PASSIVE_SCAN: A continuous focus algorithm is currently scanning 462 * for good focus. The lens is moving. 463 * 464 * AF_STATE_PASSIVE_FOCUSED: A continuous focus algorithm believes it is 465 * well focused. The lens is not moving. The HAL may spontaneously leave 466 * this state. 467 * 468 * AF_STATE_PASSIVE_UNFOCUSED: A continuous focus algorithm believes it is 469 * not well focused. The lens is not moving. The HAL may spontaneously 470 * leave this state. 471 * 472 * AF_STATE_ACTIVE_SCAN: A scan triggered by the user is underway. 473 * 474 * AF_STATE_FOCUSED_LOCKED: The AF algorithm believes it is focused. The 475 * lens is not moving. 476 * 477 * AF_STATE_NOT_FOCUSED_LOCKED: The AF algorithm has been unable to 478 * focus. The lens is not moving. 479 * 480 * ANDROID_CONTROL_AF_TRIGGER: Control for starting an autofocus scan, the 481 * meaning of which is mode- and state- dependent. Set by the framework in 482 * the request settings. 483 * 484 * AF_TRIGGER_IDLE: No current trigger. 485 * 486 * AF_TRIGGER_START: Trigger start of AF scan. Effect is mode and state 487 * dependent. 488 * 489 * AF_TRIGGER_CANCEL: Cancel current AF scan if any, and reset algorithm to 490 * default. 491 * 492 * Additional metadata entries: 493 * 494 * ANDROID_CONTROL_AF_REGIONS: Control for selecting the regions of the FOV 495 * that should be used to determine good focus. This applies to all AF 496 * modes that scan for focus. Set by the framework in the request 497 * settings. 498 * 499 * S4.2. Auto-exposure settings and result entries: 500 * 501 * Main metadata entries: 502 * 503 * ANDROID_CONTROL_AE_MODE: Control for selecting the current auto-exposure 504 * mode. Set by the framework in the request settings. 505 * 506 * AE_MODE_OFF: Autoexposure is disabled; the user controls exposure, gain, 507 * frame duration, and flash. 508 * 509 * AE_MODE_ON: Standard autoexposure, with flash control disabled. User may 510 * set flash to fire or to torch mode. 511 * 512 * AE_MODE_ON_AUTO_FLASH: Standard autoexposure, with flash on at HAL's 513 * discretion for precapture and still capture. User control of flash 514 * disabled. 515 * 516 * AE_MODE_ON_ALWAYS_FLASH: Standard autoexposure, with flash always fired 517 * for capture, and at HAL's discretion for precapture.. User control of 518 * flash disabled. 519 * 520 * AE_MODE_ON_AUTO_FLASH_REDEYE: Standard autoexposure, with flash on at 521 * HAL's discretion for precapture and still capture. Use a flash burst 522 * at end of precapture sequence to reduce redeye in the final 523 * picture. User control of flash disabled. 524 * 525 * ANDROID_CONTROL_AE_STATE: Dynamic metadata describing the current AE 526 * algorithm state, reported by the HAL in the result metadata. 527 * 528 * AE_STATE_INACTIVE: Initial AE state after mode switch. When the device is 529 * opened, it must start in this state. 530 * 531 * AE_STATE_SEARCHING: AE is not converged to a good value, and is adjusting 532 * exposure parameters. 533 * 534 * AE_STATE_CONVERGED: AE has found good exposure values for the current 535 * scene, and the exposure parameters are not changing. HAL may 536 * spontaneously leave this state to search for better solution. 537 * 538 * AE_STATE_LOCKED: AE has been locked with the AE_LOCK control. Exposure 539 * values are not changing. 540 * 541 * AE_STATE_FLASH_REQUIRED: The HAL has converged exposure, but believes 542 * flash is required for a sufficiently bright picture. Used for 543 * determining if a zero-shutter-lag frame can be used. 544 * 545 * AE_STATE_PRECAPTURE: The HAL is in the middle of a precapture 546 * sequence. Depending on AE mode, this mode may involve firing the 547 * flash for metering, or a burst of flash pulses for redeye reduction. 548 * 549 * ANDROID_CONTROL_AE_PRECAPTURE_TRIGGER: Control for starting a metering 550 * sequence before capturing a high-quality image. Set by the framework in 551 * the request settings. 552 * 553 * PRECAPTURE_TRIGGER_IDLE: No current trigger. 554 * 555 * PRECAPTURE_TRIGGER_START: Start a precapture sequence. The HAL should 556 * use the subsequent requests to measure good exposure/white balance 557 * for an upcoming high-resolution capture. 558 * 559 * Additional metadata entries: 560 * 561 * ANDROID_CONTROL_AE_LOCK: Control for locking AE controls to their current 562 * values 563 * 564 * ANDROID_CONTROL_AE_EXPOSURE_COMPENSATION: Control for adjusting AE 565 * algorithm target brightness point. 566 * 567 * ANDROID_CONTROL_AE_TARGET_FPS_RANGE: Control for selecting the target frame 568 * rate range for the AE algorithm. The AE routine cannot change the frame 569 * rate to be outside these bounds. 570 * 571 * ANDROID_CONTROL_AE_REGIONS: Control for selecting the regions of the FOV 572 * that should be used to determine good exposure levels. This applies to 573 * all AE modes besides OFF. 574 * 575 * S4.3. Auto-whitebalance settings and result entries: 576 * 577 * Main metadata entries: 578 * 579 * ANDROID_CONTROL_AWB_MODE: Control for selecting the current white-balance 580 * mode. 581 * 582 * AWB_MODE_OFF: Auto-whitebalance is disabled. User controls color matrix. 583 * 584 * AWB_MODE_AUTO: Automatic white balance is enabled; 3A controls color 585 * transform, possibly using more complex transforms than a simple 586 * matrix. 587 * 588 * AWB_MODE_INCANDESCENT: Fixed white balance settings good for indoor 589 * incandescent (tungsten) lighting, roughly 2700K. 590 * 591 * AWB_MODE_FLUORESCENT: Fixed white balance settings good for fluorescent 592 * lighting, roughly 5000K. 593 * 594 * AWB_MODE_WARM_FLUORESCENT: Fixed white balance settings good for 595 * fluorescent lighting, roughly 3000K. 596 * 597 * AWB_MODE_DAYLIGHT: Fixed white balance settings good for daylight, 598 * roughly 5500K. 599 * 600 * AWB_MODE_CLOUDY_DAYLIGHT: Fixed white balance settings good for clouded 601 * daylight, roughly 6500K. 602 * 603 * AWB_MODE_TWILIGHT: Fixed white balance settings good for 604 * near-sunset/sunrise, roughly 15000K. 605 * 606 * AWB_MODE_SHADE: Fixed white balance settings good for areas indirectly 607 * lit by the sun, roughly 7500K. 608 * 609 * ANDROID_CONTROL_AWB_STATE: Dynamic metadata describing the current AWB 610 * algorithm state, reported by the HAL in the result metadata. 611 * 612 * AWB_STATE_INACTIVE: Initial AWB state after mode switch. When the device 613 * is opened, it must start in this state. 614 * 615 * AWB_STATE_SEARCHING: AWB is not converged to a good value, and is 616 * changing color adjustment parameters. 617 * 618 * AWB_STATE_CONVERGED: AWB has found good color adjustment values for the 619 * current scene, and the parameters are not changing. HAL may 620 * spontaneously leave this state to search for better solution. 621 * 622 * AWB_STATE_LOCKED: AWB has been locked with the AWB_LOCK control. Color 623 * adjustment values are not changing. 624 * 625 * Additional metadata entries: 626 * 627 * ANDROID_CONTROL_AWB_LOCK: Control for locking AWB color adjustments to 628 * their current values. 629 * 630 * ANDROID_CONTROL_AWB_REGIONS: Control for selecting the regions of the FOV 631 * that should be used to determine good color balance. This applies only 632 * to auto-WB mode. 633 * 634 * S4.4. General state machine transition notes 635 * 636 * Switching between AF, AE, or AWB modes always resets the algorithm's state 637 * to INACTIVE. Similarly, switching between CONTROL_MODE or 638 * CONTROL_SCENE_MODE if CONTROL_MODE == USE_SCENE_MODE resets all the 639 * algorithm states to INACTIVE. 640 * 641 * The tables below are per-mode. 642 * 643 * S4.5. AF state machines 644 * 645 * when enabling AF or changing AF mode 646 *| state | trans. cause | new state | notes | 647 *+--------------------+---------------+--------------------+------------------+ 648 *| Any | AF mode change| INACTIVE | | 649 *+--------------------+---------------+--------------------+------------------+ 650 * 651 * mode = AF_MODE_OFF or AF_MODE_EDOF 652 *| state | trans. cause | new state | notes | 653 *+--------------------+---------------+--------------------+------------------+ 654 *| INACTIVE | | INACTIVE | Never changes | 655 *+--------------------+---------------+--------------------+------------------+ 656 * 657 * mode = AF_MODE_AUTO or AF_MODE_MACRO 658 *| state | trans. cause | new state | notes | 659 *+--------------------+---------------+--------------------+------------------+ 660 *| INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep | 661 *| | | | Lens now moving | 662 *+--------------------+---------------+--------------------+------------------+ 663 *| ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | If AF successful | 664 *| | | | Lens now locked | 665 *+--------------------+---------------+--------------------+------------------+ 666 *| ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | If AF successful | 667 *| | | | Lens now locked | 668 *+--------------------+---------------+--------------------+------------------+ 669 *| ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF | 670 *| | | | Lens now locked | 671 *+--------------------+---------------+--------------------+------------------+ 672 *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | 673 *+--------------------+---------------+--------------------+------------------+ 674 *| FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | 675 *| | | | Lens now moving | 676 *+--------------------+---------------+--------------------+------------------+ 677 *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | 678 *+--------------------+---------------+--------------------+------------------+ 679 *| NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | 680 *| | | | Lens now moving | 681 *+--------------------+---------------+--------------------+------------------+ 682 *| All states | mode change | INACTIVE | | 683 *+--------------------+---------------+--------------------+------------------+ 684 * 685 * mode = AF_MODE_CONTINUOUS_VIDEO 686 *| state | trans. cause | new state | notes | 687 *+--------------------+---------------+--------------------+------------------+ 688 *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | 689 *| | new scan | | Lens now moving | 690 *+--------------------+---------------+--------------------+------------------+ 691 *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | 692 *| | | | Lens now locked | 693 *+--------------------+---------------+--------------------+------------------+ 694 *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | 695 *| | current scan | | Lens now locked | 696 *+--------------------+---------------+--------------------+------------------+ 697 *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | 698 *| | current scan | | Lens now locked | 699 *+--------------------+---------------+--------------------+------------------+ 700 *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | 701 *| | | | if focus is good | 702 *| | | | Lens now locked | 703 *+--------------------+---------------+--------------------+------------------+ 704 *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | 705 *| | | | if focus is bad | 706 *| | | | Lens now locked | 707 *+--------------------+---------------+--------------------+------------------+ 708 *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | 709 *| | | | position | 710 *| | | | Lens now locked | 711 *+--------------------+---------------+--------------------+------------------+ 712 *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 713 *| | new scan | | Lens now moving | 714 *+--------------------+---------------+--------------------+------------------+ 715 *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 716 *| | new scan | | Lens now moving | 717 *+--------------------+---------------+--------------------+------------------+ 718 *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | 719 *| | | | Lens now locked | 720 *+--------------------+---------------+--------------------+------------------+ 721 *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | 722 *| | | | Lens now locked | 723 *+--------------------+---------------+--------------------+------------------+ 724 *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | 725 *+--------------------+---------------+--------------------+------------------+ 726 *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 727 *+--------------------+---------------+--------------------+------------------+ 728 *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | 729 *+--------------------+---------------+--------------------+------------------+ 730 *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 731 *+--------------------+---------------+--------------------+------------------+ 732 * 733 * mode = AF_MODE_CONTINUOUS_PICTURE 734 *| state | trans. cause | new state | notes | 735 *+--------------------+---------------+--------------------+------------------+ 736 *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | 737 *| | new scan | | Lens now moving | 738 *+--------------------+---------------+--------------------+------------------+ 739 *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | 740 *| | | | Lens now locked | 741 *+--------------------+---------------+--------------------+------------------+ 742 *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | 743 *| | current scan | | Lens now locked | 744 *+--------------------+---------------+--------------------+------------------+ 745 *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | 746 *| | current scan | | Lens now locked | 747 *+--------------------+---------------+--------------------+------------------+ 748 *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual trans. | 749 *| | | | once focus good | 750 *| | | | Lens now locked | 751 *+--------------------+---------------+--------------------+------------------+ 752 *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual trans. | 753 *| | | | if cannot focus | 754 *| | | | Lens now locked | 755 *+--------------------+---------------+--------------------+------------------+ 756 *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | 757 *| | | | position | 758 *| | | | Lens now locked | 759 *+--------------------+---------------+--------------------+------------------+ 760 *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 761 *| | new scan | | Lens now moving | 762 *+--------------------+---------------+--------------------+------------------+ 763 *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 764 *| | new scan | | Lens now moving | 765 *+--------------------+---------------+--------------------+------------------+ 766 *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | 767 *| | | | Lens now locked | 768 *+--------------------+---------------+--------------------+------------------+ 769 *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | 770 *| | | | Lens now locked | 771 *+--------------------+---------------+--------------------+------------------+ 772 *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | 773 *+--------------------+---------------+--------------------+------------------+ 774 *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 775 *+--------------------+---------------+--------------------+------------------+ 776 *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | 777 *+--------------------+---------------+--------------------+------------------+ 778 *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 779 *+--------------------+---------------+--------------------+------------------+ 780 * 781 * S4.6. AE and AWB state machines 782 * 783 * The AE and AWB state machines are mostly identical. AE has additional 784 * FLASH_REQUIRED and PRECAPTURE states. So rows below that refer to those two 785 * states should be ignored for the AWB state machine. 786 * 787 * when enabling AE/AWB or changing AE/AWB mode 788 *| state | trans. cause | new state | notes | 789 *+--------------------+---------------+--------------------+------------------+ 790 *| Any | mode change | INACTIVE | | 791 *+--------------------+---------------+--------------------+------------------+ 792 * 793 * mode = AE_MODE_OFF / AWB mode not AUTO 794 *| state | trans. cause | new state | notes | 795 *+--------------------+---------------+--------------------+------------------+ 796 *| INACTIVE | | INACTIVE | AE/AWB disabled | 797 *+--------------------+---------------+--------------------+------------------+ 798 * 799 * mode = AE_MODE_ON_* / AWB_MODE_AUTO 800 *| state | trans. cause | new state | notes | 801 *+--------------------+---------------+--------------------+------------------+ 802 *| INACTIVE | HAL initiates | SEARCHING | | 803 *| | AE/AWB scan | | | 804 *+--------------------+---------------+--------------------+------------------+ 805 *| INACTIVE | AE/AWB_LOCK | LOCKED | values locked | 806 *| | on | | | 807 *+--------------------+---------------+--------------------+------------------+ 808 *| SEARCHING | HAL finishes | CONVERGED | good values, not | 809 *| | AE/AWB scan | | changing | 810 *+--------------------+---------------+--------------------+------------------+ 811 *| SEARCHING | HAL finishes | FLASH_REQUIRED | converged but too| 812 *| | AE scan | | dark w/o flash | 813 *+--------------------+---------------+--------------------+------------------+ 814 *| SEARCHING | AE/AWB_LOCK | LOCKED | values locked | 815 *| | on | | | 816 *+--------------------+---------------+--------------------+------------------+ 817 *| CONVERGED | HAL initiates | SEARCHING | values locked | 818 *| | AE/AWB scan | | | 819 *+--------------------+---------------+--------------------+------------------+ 820 *| CONVERGED | AE/AWB_LOCK | LOCKED | values locked | 821 *| | on | | | 822 *+--------------------+---------------+--------------------+------------------+ 823 *| FLASH_REQUIRED | HAL initiates | SEARCHING | values locked | 824 *| | AE/AWB scan | | | 825 *+--------------------+---------------+--------------------+------------------+ 826 *| FLASH_REQUIRED | AE/AWB_LOCK | LOCKED | values locked | 827 *| | on | | | 828 *+--------------------+---------------+--------------------+------------------+ 829 *| LOCKED | AE/AWB_LOCK | SEARCHING | values not good | 830 *| | off | | after unlock | 831 *+--------------------+---------------+--------------------+------------------+ 832 *| LOCKED | AE/AWB_LOCK | CONVERGED | values good | 833 *| | off | | after unlock | 834 *+--------------------+---------------+--------------------+------------------+ 835 *| LOCKED | AE_LOCK | FLASH_REQUIRED | exposure good, | 836 *| | off | | but too dark | 837 *+--------------------+---------------+--------------------+------------------+ 838 *| All AE states | PRECAPTURE_ | PRECAPTURE | Start precapture | 839 *| | START | | sequence | 840 *+--------------------+---------------+--------------------+------------------+ 841 *| PRECAPTURE | Sequence done.| CONVERGED | Ready for high- | 842 *| | AE_LOCK off | | quality capture | 843 *+--------------------+---------------+--------------------+------------------+ 844 *| PRECAPTURE | Sequence done.| LOCKED | Ready for high- | 845 *| | AE_LOCK on | | quality capture | 846 *+--------------------+---------------+--------------------+------------------+ 847 * 848 */ 849 850/** 851 * S5. Cropping: 852 * 853 * Cropping of the full pixel array (for digital zoom and other use cases where 854 * a smaller FOV is desirable) is communicated through the 855 * ANDROID_SCALER_CROP_REGION setting. This is a per-request setting, and can 856 * change on a per-request basis, which is critical for implementing smooth 857 * digital zoom. 858 * 859 * The region is defined as a rectangle (x, y, width, height), with (x, y) 860 * describing the top-left corner of the rectangle. The rectangle is defined on 861 * the coordinate system of the sensor active pixel array, with (0,0) being the 862 * top-left pixel of the active pixel array. Therefore, the width and height 863 * cannot be larger than the dimensions reported in the 864 * ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY static info field. The minimum allowed 865 * width and height are reported by the HAL through the 866 * ANDROID_SCALER_MAX_DIGITAL_ZOOM static info field, which describes the 867 * maximum supported zoom factor. Therefore, the minimum crop region width and 868 * height are: 869 * 870 * {width, height} = 871 * { floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[0] / 872 * ANDROID_SCALER_MAX_DIGITAL_ZOOM), 873 * floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[1] / 874 * ANDROID_SCALER_MAX_DIGITAL_ZOOM) } 875 * 876 * If the crop region needs to fulfill specific requirements (for example, it 877 * needs to start on even coordinates, and its width/height needs to be even), 878 * the HAL must do the necessary rounding and write out the final crop region 879 * used in the output result metadata. Similarly, if the HAL implements video 880 * stabilization, it must adjust the result crop region to describe the region 881 * actually included in the output after video stabilization is applied. In 882 * general, a camera-using application must be able to determine the field of 883 * view it is receiving based on the crop region, the dimensions of the image 884 * sensor, and the lens focal length. 885 * 886 * Since the crop region applies to all streams, which may have different aspect 887 * ratios than the crop region, the exact sensor region used for each stream may 888 * be smaller than the crop region. Specifically, each stream should maintain 889 * square pixels and its aspect ratio by minimally further cropping the defined 890 * crop region. If the stream's aspect ratio is wider than the crop region, the 891 * stream should be further cropped vertically, and if the stream's aspect ratio 892 * is narrower than the crop region, the stream should be further cropped 893 * horizontally. 894 * 895 * In all cases, the stream crop must be centered within the full crop region, 896 * and each stream is only either cropped horizontally or vertical relative to 897 * the full crop region, never both. 898 * 899 * For example, if two streams are defined, a 640x480 stream (4:3 aspect), and a 900 * 1280x720 stream (16:9 aspect), below demonstrates the expected output regions 901 * for each stream for a few sample crop regions, on a hypothetical 3 MP (2000 x 902 * 1500 pixel array) sensor. 903 * 904 * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) 905 * 906 * 640x480 stream crop: (500, 375, 1000, 750) (equal to crop region) 907 * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) 908 * 909 * 0 1000 2000 910 * +---------+---------+---------+----------+ 911 * | Active pixel array | 912 * | | 913 * | | 914 * + +-------------------+ + 375 915 * | | | | 916 * | O===================O | 917 * | I 1280x720 stream I | 918 * + I I + 750 919 * | I I | 920 * | O===================O | 921 * | | | | 922 * + +-------------------+ + 1125 923 * | Crop region, 640x480 stream | 924 * | | 925 * | | 926 * +---------+---------+---------+----------+ 1500 927 * 928 * Crop region: (500, 375, 1333, 750) (16:9 aspect ratio) 929 * 930 * 640x480 stream crop: (666, 375, 1000, 750) (marked with =) 931 * 1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region) 932 * 933 * 0 1000 2000 934 * +---------+---------+---------+----------+ 935 * | Active pixel array | 936 * | | 937 * | | 938 * + +---O==================O---+ + 375 939 * | | I 640x480 stream I | | 940 * | | I I | | 941 * | | I I | | 942 * + | I I | + 750 943 * | | I I | | 944 * | | I I | | 945 * | | I I | | 946 * + +---O==================O---+ + 1125 947 * | Crop region, 1280x720 stream | 948 * | | 949 * | | 950 * +---------+---------+---------+----------+ 1500 951 * 952 * Crop region: (500, 375, 750, 750) (1:1 aspect ratio) 953 * 954 * 640x480 stream crop: (500, 469, 750, 562) (marked with =) 955 * 1280x720 stream crop: (500, 543, 750, 414) (marged with #) 956 * 957 * 0 1000 2000 958 * +---------+---------+---------+----------+ 959 * | Active pixel array | 960 * | | 961 * | | 962 * + +--------------+ + 375 963 * | O==============O | 964 * | ################ | 965 * | # # | 966 * + # # + 750 967 * | # # | 968 * | ################ 1280x720 | 969 * | O==============O 640x480 | 970 * + +--------------+ + 1125 971 * | Crop region | 972 * | | 973 * | | 974 * +---------+---------+---------+----------+ 1500 975 * 976 * And a final example, a 1024x1024 square aspect ratio stream instead of the 977 * 480p stream: 978 * 979 * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) 980 * 981 * 1024x1024 stream crop: (625, 375, 750, 750) (marked with #) 982 * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) 983 * 984 * 0 1000 2000 985 * +---------+---------+---------+----------+ 986 * | Active pixel array | 987 * | | 988 * | 1024x1024 stream | 989 * + +--###############--+ + 375 990 * | | # # | | 991 * | O===================O | 992 * | I 1280x720 stream I | 993 * + I I + 750 994 * | I I | 995 * | O===================O | 996 * | | # # | | 997 * + +--###############--+ + 1125 998 * | Crop region | 999 * | | 1000 * | | 1001 * +---------+---------+---------+----------+ 1500 1002 * 1003 */ 1004 1005/** 1006 * S6. Error management: 1007 * 1008 * Camera HAL device ops functions that have a return value will all return 1009 * -ENODEV / NULL in case of a serious error. This means the device cannot 1010 * continue operation, and must be closed by the framework. Once this error is 1011 * returned by some method, or if notify() is called with ERROR_DEVICE, only 1012 * the close() method can be called successfully. All other methods will return 1013 * -ENODEV / NULL. 1014 * 1015 * If a device op is called in the wrong sequence, for example if the framework 1016 * calls configure_streams() is called before initialize(), the device must 1017 * return -ENOSYS from the call, and do nothing. 1018 * 1019 * Transient errors in image capture must be reported through notify() as follows: 1020 * 1021 * - The failure of an entire capture to occur must be reported by the HAL by 1022 * calling notify() with ERROR_REQUEST. Individual errors for the result 1023 * metadata or the output buffers must not be reported in this case. 1024 * 1025 * - If the metadata for a capture cannot be produced, but some image buffers 1026 * were filled, the HAL must call notify() with ERROR_RESULT. 1027 * 1028 * - If an output image buffer could not be filled, but either the metadata was 1029 * produced or some other buffers were filled, the HAL must call notify() with 1030 * ERROR_BUFFER for each failed buffer. 1031 * 1032 * In each of these transient failure cases, the HAL must still call 1033 * process_capture_result, with valid output buffer_handle_t. If the result 1034 * metadata could not be produced, it should be NULL. If some buffers could not 1035 * be filled, they must be returned with process_capture_result in the error state, 1036 * their release fences must be set to the acquire fences passed by the framework, 1037 * or -1 if they have been waited on by the HAL already. 1038 * 1039 * Invalid input arguments result in -EINVAL from the appropriate methods. In 1040 * that case, the framework must act as if that call had never been made. 1041 * 1042 */ 1043 1044/** 1045 * S7. Key Performance Indicator (KPI) glossary: 1046 * 1047 * This includes some critical definitions that are used by KPI metrics. 1048 * 1049 * Pipeline Latency: 1050 * For a given capture request, the duration from the framework calling 1051 * process_capture_request to the HAL sending capture result and all buffers 1052 * back by process_capture_result call. To make the Pipeline Latency measure 1053 * independent of frame rate, it is measured by frame count. 1054 * 1055 * For example, when frame rate is 30 (fps), the frame duration (time interval 1056 * between adjacent frame capture time) is 33 (ms). 1057 * If it takes 5 frames for framework to get the result and buffers back for 1058 * a given request, then the Pipeline Latency is 5 (frames), instead of 1059 * 5 x 33 = 165 (ms). 1060 * 1061 * The Pipeline Latency is determined by android.request.pipelineDepth and 1062 * android.request.pipelineMaxDepth, see their definitions for more details. 1063 * 1064 */ 1065 1066__BEGIN_DECLS 1067 1068struct camera3_device; 1069 1070/********************************************************************** 1071 * 1072 * Camera3 stream and stream buffer definitions. 1073 * 1074 * These structs and enums define the handles and contents of the input and 1075 * output streams connecting the HAL to various framework and application buffer 1076 * consumers. Each stream is backed by a gralloc buffer queue. 1077 * 1078 */ 1079 1080/** 1081 * camera3_stream_type_t: 1082 * 1083 * The type of the camera stream, which defines whether the camera HAL device is 1084 * the producer or the consumer for that stream, and how the buffers of the 1085 * stream relate to the other streams. 1086 */ 1087typedef enum camera3_stream_type { 1088 /** 1089 * This stream is an output stream; the camera HAL device will be 1090 * responsible for filling buffers from this stream with newly captured or 1091 * reprocessed image data. 1092 */ 1093 CAMERA3_STREAM_OUTPUT = 0, 1094 1095 /** 1096 * This stream is an input stream; the camera HAL device will be responsible 1097 * for reading buffers from this stream and sending them through the camera 1098 * processing pipeline, as if the buffer was a newly captured image from the 1099 * imager. 1100 */ 1101 CAMERA3_STREAM_INPUT = 1, 1102 1103 /** 1104 * This stream can be used for input and output. Typically, the stream is 1105 * used as an output stream, but occasionally one already-filled buffer may 1106 * be sent back to the HAL device for reprocessing. 1107 * 1108 * This kind of stream is meant generally for zero-shutter-lag features, 1109 * where copying the captured image from the output buffer to the 1110 * reprocessing input buffer would be expensive. The stream will be used by 1111 * the framework as follows: 1112 * 1113 * 1. The framework includes a buffer from this stream as output buffer in a 1114 * request as normal. 1115 * 1116 * 2. Once the HAL device returns a filled output buffer to the framework, 1117 * the framework may do one of two things with the filled buffer: 1118 * 1119 * 2. a. The framework uses the filled data, and returns the now-used buffer 1120 * to the stream queue for reuse. This behavior exactly matches the 1121 * OUTPUT type of stream. 1122 * 1123 * 2. b. The framework wants to reprocess the filled data, and uses the 1124 * buffer as an input buffer for a request. Once the HAL device has 1125 * used the reprocessing buffer, it then returns it to the 1126 * framework. The framework then returns the now-used buffer to the 1127 * stream queue for reuse. 1128 * 1129 * 3. The HAL device will be given the buffer again as an output buffer for 1130 * a request at some future point. 1131 * 1132 * Note that the HAL will always be reprocessing data it produced. 1133 * 1134 */ 1135 CAMERA3_STREAM_BIDIRECTIONAL = 2, 1136 1137 /** 1138 * Total number of framework-defined stream types 1139 */ 1140 CAMERA3_NUM_STREAM_TYPES 1141 1142} camera3_stream_type_t; 1143 1144/** 1145 * camera3_stream_t: 1146 * 1147 * A handle to a single camera input or output stream. A stream is defined by 1148 * the framework by its buffer resolution and format, and additionally by the 1149 * HAL with the gralloc usage flags and the maximum in-flight buffer count. 1150 * 1151 * The stream structures are owned by the framework, but pointers to a 1152 * camera3_stream passed into the HAL by configure_streams() are valid until the 1153 * end of the first subsequent configure_streams() call that _does not_ include 1154 * that camera3_stream as an argument, or until the end of the close() call. 1155 * 1156 * All camera3_stream framework-controlled members are immutable once the 1157 * camera3_stream is passed into configure_streams(). The HAL may only change 1158 * the HAL-controlled parameters during a configure_streams() call, except for 1159 * the contents of the private pointer. 1160 * 1161 * If a configure_streams() call returns a non-fatal error, all active streams 1162 * remain valid as if configure_streams() had not been called. 1163 * 1164 * The endpoint of the stream is not visible to the camera HAL device. 1165 * In DEVICE_API_VERSION_3_1, this was changed to share consumer usage flags 1166 * on streams where the camera is a producer (OUTPUT and BIDIRECTIONAL stream 1167 * types) see the usage field below. 1168 */ 1169typedef struct camera3_stream { 1170 1171 /***** 1172 * Set by framework before configure_streams() 1173 */ 1174 1175 /** 1176 * The type of the stream, one of the camera3_stream_type_t values. 1177 */ 1178 int stream_type; 1179 1180 /** 1181 * The width in pixels of the buffers in this stream 1182 */ 1183 uint32_t width; 1184 1185 /** 1186 * The height in pixels of the buffers in this stream 1187 */ 1188 uint32_t height; 1189 1190 /** 1191 * The pixel format for the buffers in this stream. Format is a value from 1192 * the HAL_PIXEL_FORMAT_* list in system/core/include/system/graphics.h, or 1193 * from device-specific headers. 1194 * 1195 * If HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform 1196 * gralloc module will select a format based on the usage flags provided by 1197 * the camera device and the other endpoint of the stream. 1198 * 1199 * <= CAMERA_DEVICE_API_VERSION_3_1: 1200 * 1201 * The camera HAL device must inspect the buffers handed to it in the 1202 * subsequent register_stream_buffers() call to obtain the 1203 * implementation-specific format details, if necessary. 1204 * 1205 * >= CAMERA_DEVICE_API_VERSION_3_2: 1206 * 1207 * register_stream_buffers() won't be called by the framework, so the HAL 1208 * should configure the ISP and sensor pipeline based purely on the sizes, 1209 * usage flags, and formats for the configured streams. 1210 */ 1211 int format; 1212 1213 /***** 1214 * Set by HAL during configure_streams(). 1215 */ 1216 1217 /** 1218 * The gralloc usage flags for this stream, as needed by the HAL. The usage 1219 * flags are defined in gralloc.h (GRALLOC_USAGE_*), or in device-specific 1220 * headers. 1221 * 1222 * For output streams, these are the HAL's producer usage flags. For input 1223 * streams, these are the HAL's consumer usage flags. The usage flags from 1224 * the producer and the consumer will be combined together and then passed 1225 * to the platform gralloc HAL module for allocating the gralloc buffers for 1226 * each stream. 1227 * 1228 * Version information: 1229 * 1230 * == CAMERA_DEVICE_API_VERSION_3_0: 1231 * 1232 * No initial value guaranteed when passed via configure_streams(). 1233 * HAL may not use this field as input, and must write over this field 1234 * with its usage flags. 1235 * 1236 * >= CAMERA_DEVICE_API_VERSION_3_1: 1237 * 1238 * For stream_type OUTPUT and BIDIRECTIONAL, when passed via 1239 * configure_streams(), the initial value of this is the consumer's 1240 * usage flags. The HAL may use these consumer flags to decide stream 1241 * configuration. 1242 * For stream_type INPUT, when passed via configure_streams(), the initial 1243 * value of this is 0. 1244 * For all streams passed via configure_streams(), the HAL must write 1245 * over this field with its usage flags. 1246 */ 1247 uint32_t usage; 1248 1249 /** 1250 * The maximum number of buffers the HAL device may need to have dequeued at 1251 * the same time. The HAL device may not have more buffers in-flight from 1252 * this stream than this value. 1253 */ 1254 uint32_t max_buffers; 1255 1256 /** 1257 * A handle to HAL-private information for the stream. Will not be inspected 1258 * by the framework code. 1259 */ 1260 void *priv; 1261 1262} camera3_stream_t; 1263 1264/** 1265 * camera3_stream_configuration_t: 1266 * 1267 * A structure of stream definitions, used by configure_streams(). This 1268 * structure defines all the output streams and the reprocessing input 1269 * stream for the current camera use case. 1270 */ 1271typedef struct camera3_stream_configuration { 1272 /** 1273 * The total number of streams requested by the framework. This includes 1274 * both input and output streams. The number of streams will be at least 1, 1275 * and there will be at least one output-capable stream. 1276 */ 1277 uint32_t num_streams; 1278 1279 /** 1280 * An array of camera stream pointers, defining the input/output 1281 * configuration for the camera HAL device. 1282 * 1283 * At most one input-capable stream may be defined (INPUT or BIDIRECTIONAL) 1284 * in a single configuration. 1285 * 1286 * At least one output-capable stream must be defined (OUTPUT or 1287 * BIDIRECTIONAL). 1288 */ 1289 camera3_stream_t **streams; 1290 1291} camera3_stream_configuration_t; 1292 1293/** 1294 * camera3_buffer_status_t: 1295 * 1296 * The current status of a single stream buffer. 1297 */ 1298typedef enum camera3_buffer_status { 1299 /** 1300 * The buffer is in a normal state, and can be used after waiting on its 1301 * sync fence. 1302 */ 1303 CAMERA3_BUFFER_STATUS_OK = 0, 1304 1305 /** 1306 * The buffer does not contain valid data, and the data in it should not be 1307 * used. The sync fence must still be waited on before reusing the buffer. 1308 */ 1309 CAMERA3_BUFFER_STATUS_ERROR = 1 1310 1311} camera3_buffer_status_t; 1312 1313/** 1314 * camera3_stream_buffer_t: 1315 * 1316 * A single buffer from a camera3 stream. It includes a handle to its parent 1317 * stream, the handle to the gralloc buffer itself, and sync fences 1318 * 1319 * The buffer does not specify whether it is to be used for input or output; 1320 * that is determined by its parent stream type and how the buffer is passed to 1321 * the HAL device. 1322 */ 1323typedef struct camera3_stream_buffer { 1324 /** 1325 * The handle of the stream this buffer is associated with 1326 */ 1327 camera3_stream_t *stream; 1328 1329 /** 1330 * The native handle to the buffer 1331 */ 1332 buffer_handle_t *buffer; 1333 1334 /** 1335 * Current state of the buffer, one of the camera3_buffer_status_t 1336 * values. The framework will not pass buffers to the HAL that are in an 1337 * error state. In case a buffer could not be filled by the HAL, it must 1338 * have its status set to CAMERA3_BUFFER_STATUS_ERROR when returned to the 1339 * framework with process_capture_result(). 1340 */ 1341 int status; 1342 1343 /** 1344 * The acquire sync fence for this buffer. The HAL must wait on this fence 1345 * fd before attempting to read from or write to this buffer. 1346 * 1347 * The framework may be set to -1 to indicate that no waiting is necessary 1348 * for this buffer. 1349 * 1350 * When the HAL returns an output buffer to the framework with 1351 * process_capture_result(), the acquire_fence must be set to -1. If the HAL 1352 * never waits on the acquire_fence due to an error in filling a buffer, 1353 * when calling process_capture_result() the HAL must set the release_fence 1354 * of the buffer to be the acquire_fence passed to it by the framework. This 1355 * will allow the framework to wait on the fence before reusing the buffer. 1356 * 1357 * For input buffers, the HAL must not change the acquire_fence field during 1358 * the process_capture_request() call. 1359 */ 1360 int acquire_fence; 1361 1362 /** 1363 * The release sync fence for this buffer. The HAL must set this fence when 1364 * returning buffers to the framework, or write -1 to indicate that no 1365 * waiting is required for this buffer. 1366 * 1367 * For the input buffer, the release fence must be set by the 1368 * process_capture_request() call. For the output buffers, the fences must 1369 * be set in the output_buffers array passed to process_capture_result(). 1370 * 1371 * >= CAMERA_DEVICE_API_VERSION_3_2: 1372 * 1373 * After signaling the release_fence for this buffer, the HAL 1374 * should not make any further attempts to access this buffer as the 1375 * ownership has been fully transferred back to the framework. 1376 * 1377 * If a fence of -1 was specified then the ownership of this buffer 1378 * is transferred back immediately upon the call of process_capture_result. 1379 */ 1380 int release_fence; 1381 1382} camera3_stream_buffer_t; 1383 1384/** 1385 * camera3_stream_buffer_set_t: 1386 * 1387 * The complete set of gralloc buffers for a stream. This structure is given to 1388 * register_stream_buffers() to allow the camera HAL device to register/map/etc 1389 * newly allocated stream buffers. 1390 * 1391 * >= CAMERA_DEVICE_API_VERSION_3_2: 1392 * 1393 * Deprecated (and not used). In particular, 1394 * register_stream_buffers is also deprecated and will never be invoked. 1395 * 1396 */ 1397typedef struct camera3_stream_buffer_set { 1398 /** 1399 * The stream handle for the stream these buffers belong to 1400 */ 1401 camera3_stream_t *stream; 1402 1403 /** 1404 * The number of buffers in this stream. It is guaranteed to be at least 1405 * stream->max_buffers. 1406 */ 1407 uint32_t num_buffers; 1408 1409 /** 1410 * The array of gralloc buffer handles for this stream. If the stream format 1411 * is set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL device 1412 * should inspect the passed-in buffers to determine any platform-private 1413 * pixel format information. 1414 */ 1415 buffer_handle_t **buffers; 1416 1417} camera3_stream_buffer_set_t; 1418 1419/** 1420 * camera3_jpeg_blob: 1421 * 1422 * Transport header for compressed JPEG buffers in output streams. 1423 * 1424 * To capture JPEG images, a stream is created using the pixel format 1425 * HAL_PIXEL_FORMAT_BLOB, and the static metadata field android.jpeg.maxSize is 1426 * used as the buffer size. Since compressed JPEG images are of variable size, 1427 * the HAL needs to include the final size of the compressed image using this 1428 * structure inside the output stream buffer. The JPEG blob ID field must be set 1429 * to CAMERA3_JPEG_BLOB_ID. 1430 * 1431 * Transport header should be at the end of the JPEG output stream buffer. That 1432 * means the jpeg_blob_id must start at byte[android.jpeg.maxSize - 1433 * sizeof(camera3_jpeg_blob)]. Any HAL using this transport header must 1434 * account for it in android.jpeg.maxSize. The JPEG data itself starts at 1435 * the beginning of the buffer and should be jpeg_size bytes long. 1436 */ 1437typedef struct camera3_jpeg_blob { 1438 uint16_t jpeg_blob_id; 1439 uint32_t jpeg_size; 1440} camera3_jpeg_blob_t; 1441 1442enum { 1443 CAMERA3_JPEG_BLOB_ID = 0x00FF 1444}; 1445 1446/********************************************************************** 1447 * 1448 * Message definitions for the HAL notify() callback. 1449 * 1450 * These definitions are used for the HAL notify callback, to signal 1451 * asynchronous events from the HAL device to the Android framework. 1452 * 1453 */ 1454 1455/** 1456 * camera3_msg_type: 1457 * 1458 * Indicates the type of message sent, which specifies which member of the 1459 * message union is valid. 1460 * 1461 */ 1462typedef enum camera3_msg_type { 1463 /** 1464 * An error has occurred. camera3_notify_msg.message.error contains the 1465 * error information. 1466 */ 1467 CAMERA3_MSG_ERROR = 1, 1468 1469 /** 1470 * The exposure of a given request has 1471 * begun. camera3_notify_msg.message.shutter contains the information 1472 * the capture. 1473 */ 1474 CAMERA3_MSG_SHUTTER = 2, 1475 1476 /** 1477 * Number of framework message types 1478 */ 1479 CAMERA3_NUM_MESSAGES 1480 1481} camera3_msg_type_t; 1482 1483/** 1484 * Defined error codes for CAMERA_MSG_ERROR 1485 */ 1486typedef enum camera3_error_msg_code { 1487 /** 1488 * A serious failure occured. No further frames or buffer streams will 1489 * be produced by the device. Device should be treated as closed. The 1490 * client must reopen the device to use it again. The frame_number field 1491 * is unused. 1492 */ 1493 CAMERA3_MSG_ERROR_DEVICE = 1, 1494 1495 /** 1496 * An error has occurred in processing a request. No output (metadata or 1497 * buffers) will be produced for this request. The frame_number field 1498 * specifies which request has been dropped. Subsequent requests are 1499 * unaffected, and the device remains operational. 1500 */ 1501 CAMERA3_MSG_ERROR_REQUEST = 2, 1502 1503 /** 1504 * An error has occurred in producing an output result metadata buffer 1505 * for a request, but output stream buffers for it will still be 1506 * available. Subsequent requests are unaffected, and the device remains 1507 * operational. The frame_number field specifies the request for which 1508 * result metadata won't be available. 1509 */ 1510 CAMERA3_MSG_ERROR_RESULT = 3, 1511 1512 /** 1513 * An error has occurred in placing an output buffer into a stream for a 1514 * request. The frame metadata and other buffers may still be 1515 * available. Subsequent requests are unaffected, and the device remains 1516 * operational. The frame_number field specifies the request for which the 1517 * buffer was dropped, and error_stream contains a pointer to the stream 1518 * that dropped the frame.u 1519 */ 1520 CAMERA3_MSG_ERROR_BUFFER = 4, 1521 1522 /** 1523 * Number of error types 1524 */ 1525 CAMERA3_MSG_NUM_ERRORS 1526 1527} camera3_error_msg_code_t; 1528 1529/** 1530 * camera3_error_msg_t: 1531 * 1532 * Message contents for CAMERA3_MSG_ERROR 1533 */ 1534typedef struct camera3_error_msg { 1535 /** 1536 * Frame number of the request the error applies to. 0 if the frame number 1537 * isn't applicable to the error. 1538 */ 1539 uint32_t frame_number; 1540 1541 /** 1542 * Pointer to the stream that had a failure. NULL if the stream isn't 1543 * applicable to the error. 1544 */ 1545 camera3_stream_t *error_stream; 1546 1547 /** 1548 * The code for this error; one of the CAMERA_MSG_ERROR enum values. 1549 */ 1550 int error_code; 1551 1552} camera3_error_msg_t; 1553 1554/** 1555 * camera3_shutter_msg_t: 1556 * 1557 * Message contents for CAMERA3_MSG_SHUTTER 1558 */ 1559typedef struct camera3_shutter_msg { 1560 /** 1561 * Frame number of the request that has begun exposure 1562 */ 1563 uint32_t frame_number; 1564 1565 /** 1566 * Timestamp for the start of capture. This must match the capture result 1567 * metadata's sensor exposure start timestamp. 1568 */ 1569 uint64_t timestamp; 1570 1571} camera3_shutter_msg_t; 1572 1573/** 1574 * camera3_notify_msg_t: 1575 * 1576 * The message structure sent to camera3_callback_ops_t.notify() 1577 */ 1578typedef struct camera3_notify_msg { 1579 1580 /** 1581 * The message type. One of camera3_notify_msg_type, or a private extension. 1582 */ 1583 int type; 1584 1585 union { 1586 /** 1587 * Error message contents. Valid if type is CAMERA3_MSG_ERROR 1588 */ 1589 camera3_error_msg_t error; 1590 1591 /** 1592 * Shutter message contents. Valid if type is CAMERA3_MSG_SHUTTER 1593 */ 1594 camera3_shutter_msg_t shutter; 1595 1596 /** 1597 * Generic message contents. Used to ensure a minimum size for custom 1598 * message types. 1599 */ 1600 uint8_t generic[32]; 1601 } message; 1602 1603} camera3_notify_msg_t; 1604 1605/********************************************************************** 1606 * 1607 * Capture request/result definitions for the HAL process_capture_request() 1608 * method, and the process_capture_result() callback. 1609 * 1610 */ 1611 1612/** 1613 * camera3_request_template_t: 1614 * 1615 * Available template types for 1616 * camera3_device_ops.construct_default_request_settings() 1617 */ 1618typedef enum camera3_request_template { 1619 /** 1620 * Standard camera preview operation with 3A on auto. 1621 */ 1622 CAMERA3_TEMPLATE_PREVIEW = 1, 1623 1624 /** 1625 * Standard camera high-quality still capture with 3A and flash on auto. 1626 */ 1627 CAMERA3_TEMPLATE_STILL_CAPTURE = 2, 1628 1629 /** 1630 * Standard video recording plus preview with 3A on auto, torch off. 1631 */ 1632 CAMERA3_TEMPLATE_VIDEO_RECORD = 3, 1633 1634 /** 1635 * High-quality still capture while recording video. Application will 1636 * include preview, video record, and full-resolution YUV or JPEG streams in 1637 * request. Must not cause stuttering on video stream. 3A on auto. 1638 */ 1639 CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4, 1640 1641 /** 1642 * Zero-shutter-lag mode. Application will request preview and 1643 * full-resolution data for each frame, and reprocess it to JPEG when a 1644 * still image is requested by user. Settings should provide highest-quality 1645 * full-resolution images without compromising preview frame rate. 3A on 1646 * auto. 1647 */ 1648 CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5, 1649 1650 /** 1651 * A basic template for direct application control of capture 1652 * parameters. All automatic control is disabled (auto-exposure, auto-white 1653 * balance, auto-focus), and post-processing parameters are set to preview 1654 * quality. The manual capture parameters (exposure, sensitivity, etc.) 1655 * are set to reasonable defaults, but should be overridden by the 1656 * application depending on the intended use case. 1657 */ 1658 CAMERA3_TEMPLATE_MANUAL = 6, 1659 1660 /* Total number of templates */ 1661 CAMERA3_TEMPLATE_COUNT, 1662 1663 /** 1664 * First value for vendor-defined request templates 1665 */ 1666 CAMERA3_VENDOR_TEMPLATE_START = 0x40000000 1667 1668} camera3_request_template_t; 1669 1670/** 1671 * camera3_capture_request_t: 1672 * 1673 * A single request for image capture/buffer reprocessing, sent to the Camera 1674 * HAL device by the framework in process_capture_request(). 1675 * 1676 * The request contains the settings to be used for this capture, and the set of 1677 * output buffers to write the resulting image data in. It may optionally 1678 * contain an input buffer, in which case the request is for reprocessing that 1679 * input buffer instead of capturing a new image with the camera sensor. The 1680 * capture is identified by the frame_number. 1681 * 1682 * In response, the camera HAL device must send a camera3_capture_result 1683 * structure asynchronously to the framework, using the process_capture_result() 1684 * callback. 1685 */ 1686typedef struct camera3_capture_request { 1687 /** 1688 * The frame number is an incrementing integer set by the framework to 1689 * uniquely identify this capture. It needs to be returned in the result 1690 * call, and is also used to identify the request in asynchronous 1691 * notifications sent to camera3_callback_ops_t.notify(). 1692 */ 1693 uint32_t frame_number; 1694 1695 /** 1696 * The settings buffer contains the capture and processing parameters for 1697 * the request. As a special case, a NULL settings buffer indicates that the 1698 * settings are identical to the most-recently submitted capture request. A 1699 * NULL buffer cannot be used as the first submitted request after a 1700 * configure_streams() call. 1701 */ 1702 const camera_metadata_t *settings; 1703 1704 /** 1705 * The input stream buffer to use for this request, if any. 1706 * 1707 * If input_buffer is NULL, then the request is for a new capture from the 1708 * imager. If input_buffer is valid, the request is for reprocessing the 1709 * image contained in input_buffer. 1710 * 1711 * In the latter case, the HAL must set the release_fence of the 1712 * input_buffer to a valid sync fence, or to -1 if the HAL does not support 1713 * sync, before process_capture_request() returns. 1714 * 1715 * The HAL is required to wait on the acquire sync fence of the input buffer 1716 * before accessing it. 1717 * 1718 * <= CAMERA_DEVICE_API_VERSION_3_1: 1719 * 1720 * Any input buffer included here will have been registered with the HAL 1721 * through register_stream_buffers() before its inclusion in a request. 1722 * 1723 * >= CAMERA_DEVICE_API_VERSION_3_2: 1724 * 1725 * The buffers will not have been pre-registered with the HAL. 1726 * Subsequent requests may reuse buffers, or provide entirely new buffers. 1727 */ 1728 camera3_stream_buffer_t *input_buffer; 1729 1730 /** 1731 * The number of output buffers for this capture request. Must be at least 1732 * 1. 1733 */ 1734 uint32_t num_output_buffers; 1735 1736 /** 1737 * An array of num_output_buffers stream buffers, to be filled with image 1738 * data from this capture/reprocess. The HAL must wait on the acquire fences 1739 * of each stream buffer before writing to them. 1740 * 1741 * The HAL takes ownership of the actual buffer_handle_t entries in 1742 * output_buffers; the framework does not access them until they are 1743 * returned in a camera3_capture_result_t. 1744 * 1745 * <= CAMERA_DEVICE_API_VERSION_3_1: 1746 * 1747 * All the buffers included here will have been registered with the HAL 1748 * through register_stream_buffers() before their inclusion in a request. 1749 * 1750 * >= CAMERA_DEVICE_API_VERSION_3_2: 1751 * 1752 * Any or all of the buffers included here may be brand new in this 1753 * request (having never before seen by the HAL). 1754 */ 1755 const camera3_stream_buffer_t *output_buffers; 1756 1757} camera3_capture_request_t; 1758 1759/** 1760 * camera3_capture_result_t: 1761 * 1762 * The result of a single capture/reprocess by the camera HAL device. This is 1763 * sent to the framework asynchronously with process_capture_result(), in 1764 * response to a single capture request sent to the HAL with 1765 * process_capture_request(). Multiple process_capture_result() calls may be 1766 * performed by the HAL for each request. 1767 * 1768 * Each call, all with the same frame 1769 * number, may contain some subset of the output buffers, and/or the result 1770 * metadata. The metadata may only be provided once for a given frame number; 1771 * all other calls must set the result metadata to NULL. 1772 * 1773 * The result structure contains the output metadata from this capture, and the 1774 * set of output buffers that have been/will be filled for this capture. Each 1775 * output buffer may come with a release sync fence that the framework will wait 1776 * on before reading, in case the buffer has not yet been filled by the HAL. 1777 * 1778 * >= CAMERA_DEVICE_API_VERSION_3_2: 1779 * 1780 * The metadata may be provided multiple times for a single frame number. The 1781 * framework will accumulate together the final result set by combining each 1782 * partial result together into the total result set. 1783 * 1784 * Performance considerations: 1785 * 1786 * Applications will also receive these partial results immediately, so sending 1787 * partial results is a highly recommended performance optimization to avoid 1788 * the total pipeline latency before sending the results for what is known very 1789 * early on in the pipeline. 1790 * 1791 * A typical use case might be calculating the AF state halfway through the 1792 * pipeline; by sending the state back to the framework immediately, we get a 1793 * 50% performance increase and perceived responsiveness of the auto-focus. 1794 * 1795 */ 1796typedef struct camera3_capture_result { 1797 /** 1798 * The frame number is an incrementing integer set by the framework in the 1799 * submitted request to uniquely identify this capture. It is also used to 1800 * identify the request in asynchronous notifications sent to 1801 * camera3_callback_ops_t.notify(). 1802 */ 1803 uint32_t frame_number; 1804 1805 /** 1806 * The result metadata for this capture. This contains information about the 1807 * final capture parameters, the state of the capture and post-processing 1808 * hardware, the state of the 3A algorithms, if enabled, and the output of 1809 * any enabled statistics units. 1810 * 1811 * Only one call to process_capture_result() with a given frame_number may 1812 * include the result metadata. All other calls for the same frame_number 1813 * must set this to NULL. 1814 * 1815 * If there was an error producing the result metadata, result must be an 1816 * empty metadata buffer, and notify() must be called with ERROR_RESULT. 1817 * 1818 * >= CAMERA_DEVICE_API_VERSION_3_2: 1819 * 1820 * Multiple calls to process_capture_result() with a given frame_number 1821 * may include the result metadata. 1822 * 1823 * Partial metadata submitted should not include any metadata key returned 1824 * in a previous partial result for a given frame. Each new partial result 1825 * for that frame must also set a distinct partial_result value. 1826 * 1827 * If notify has been called with ERROR_RESULT, all further partial 1828 * results for that frame are ignored by the framework. 1829 */ 1830 const camera_metadata_t *result; 1831 1832 /** 1833 * The number of output buffers returned in this result structure. Must be 1834 * less than or equal to the matching capture request's count. If this is 1835 * less than the buffer count in the capture request, at least one more call 1836 * to process_capture_result with the same frame_number must be made, to 1837 * return the remaining output buffers to the framework. This may only be 1838 * zero if the structure includes valid result metadata. 1839 */ 1840 uint32_t num_output_buffers; 1841 1842 /** 1843 * The handles for the output stream buffers for this capture. They may not 1844 * yet be filled at the time the HAL calls process_capture_result(); the 1845 * framework will wait on the release sync fences provided by the HAL before 1846 * reading the buffers. 1847 * 1848 * The HAL must set the stream buffer's release sync fence to a valid sync 1849 * fd, or to -1 if the buffer has already been filled. 1850 * 1851 * If the HAL encounters an error while processing the buffer, and the 1852 * buffer is not filled, the buffer's status field must be set to 1853 * CAMERA3_BUFFER_STATUS_ERROR. If the HAL did not wait on the acquire fence 1854 * before encountering the error, the acquire fence should be copied into 1855 * the release fence, to allow the framework to wait on the fence before 1856 * reusing the buffer. 1857 * 1858 * The acquire fence must be set to -1 for all output buffers. If 1859 * num_output_buffers is zero, this may be NULL. In that case, at least one 1860 * more process_capture_result call must be made by the HAL to provide the 1861 * output buffers. 1862 * 1863 * When process_capture_result is called with a new buffer for a frame, 1864 * all previous frames' buffers for that corresponding stream must have been 1865 * already delivered (the fences need not have yet been signaled). 1866 * 1867 * >= CAMERA_DEVICE_API_VERSION_3_2: 1868 * 1869 * Gralloc buffers for a frame may be sent to framework before the 1870 * corresponding SHUTTER-notify. 1871 * 1872 * Performance considerations: 1873 * 1874 * Buffers delivered to the framework will not be dispatched to the 1875 * application layer until a start of exposure timestamp has been received 1876 * via a SHUTTER notify() call. It is highly recommended to 1877 * dispatch that call as early as possible. 1878 */ 1879 const camera3_stream_buffer_t *output_buffers; 1880 1881 /** 1882 * >= CAMERA_DEVICE_API_VERSION_3_2: 1883 * 1884 * In order to take advantage of partial results, the HAL must set the 1885 * static metadata android.request.partialResultCount to the number of 1886 * partial results it will send for each frame. 1887 * 1888 * Each new capture result with a partial result must set 1889 * this field (partial_result) to a distinct inclusive value between 1890 * 1 and android.request.partialResultCount. 1891 * 1892 * HALs not wishing to take advantage of this feature must not 1893 * set an android.request.partialResultCount or partial_result to a value 1894 * other than 1. 1895 * 1896 * This value must be set to 0 when a capture result contains buffers only 1897 * and no metadata. 1898 */ 1899 uint32_t partial_result; 1900 1901} camera3_capture_result_t; 1902 1903/********************************************************************** 1904 * 1905 * Callback methods for the HAL to call into the framework. 1906 * 1907 * These methods are used to return metadata and image buffers for a completed 1908 * or failed captures, and to notify the framework of asynchronous events such 1909 * as errors. 1910 * 1911 * The framework will not call back into the HAL from within these callbacks, 1912 * and these calls will not block for extended periods. 1913 * 1914 */ 1915typedef struct camera3_callback_ops { 1916 1917 /** 1918 * process_capture_result: 1919 * 1920 * Send results from a completed capture to the framework. 1921 * process_capture_result() may be invoked multiple times by the HAL in 1922 * response to a single capture request. This allows, for example, the 1923 * metadata and low-resolution buffers to be returned in one call, and 1924 * post-processed JPEG buffers in a later call, once it is available. Each 1925 * call must include the frame number of the request it is returning 1926 * metadata or buffers for. 1927 * 1928 * A component (buffer or metadata) of the complete result may only be 1929 * included in one process_capture_result call. A buffer for each stream, 1930 * and the result metadata, must be returned by the HAL for each request in 1931 * one of the process_capture_result calls, even in case of errors producing 1932 * some of the output. A call to process_capture_result() with neither 1933 * output buffers or result metadata is not allowed. 1934 * 1935 * The order of returning metadata and buffers for a single result does not 1936 * matter, but buffers for a given stream must be returned in FIFO order. So 1937 * the buffer for request 5 for stream A must always be returned before the 1938 * buffer for request 6 for stream A. This also applies to the result 1939 * metadata; the metadata for request 5 must be returned before the metadata 1940 * for request 6. 1941 * 1942 * However, different streams are independent of each other, so it is 1943 * acceptable and expected that the buffer for request 5 for stream A may be 1944 * returned after the buffer for request 6 for stream B is. And it is 1945 * acceptable that the result metadata for request 6 for stream B is 1946 * returned before the buffer for request 5 for stream A is. 1947 * 1948 * The HAL retains ownership of result structure, which only needs to be 1949 * valid to access during this call. The framework will copy whatever it 1950 * needs before this call returns. 1951 * 1952 * The output buffers do not need to be filled yet; the framework will wait 1953 * on the stream buffer release sync fence before reading the buffer 1954 * data. Therefore, this method should be called by the HAL as soon as 1955 * possible, even if some or all of the output buffers are still in 1956 * being filled. The HAL must include valid release sync fences into each 1957 * output_buffers stream buffer entry, or -1 if that stream buffer is 1958 * already filled. 1959 * 1960 * If the result buffer cannot be constructed for a request, the HAL should 1961 * return an empty metadata buffer, but still provide the output buffers and 1962 * their sync fences. In addition, notify() must be called with an 1963 * ERROR_RESULT message. 1964 * 1965 * If an output buffer cannot be filled, its status field must be set to 1966 * STATUS_ERROR. In addition, notify() must be called with a ERROR_BUFFER 1967 * message. 1968 * 1969 * If the entire capture has failed, then this method still needs to be 1970 * called to return the output buffers to the framework. All the buffer 1971 * statuses should be STATUS_ERROR, and the result metadata should be an 1972 * empty buffer. In addition, notify() must be called with a ERROR_REQUEST 1973 * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages 1974 * should not be sent. 1975 * 1976 * Performance requirements: 1977 * 1978 * This is a non-blocking call. The framework will return this call in 5ms. 1979 * 1980 * The pipeline latency (see S7 for definition) should be less than or equal to 1981 * 4 frame intervals, and must be less than or equal to 8 frame intervals. 1982 * 1983 */ 1984 void (*process_capture_result)(const struct camera3_callback_ops *, 1985 const camera3_capture_result_t *result); 1986 1987 /** 1988 * notify: 1989 * 1990 * Asynchronous notification callback from the HAL, fired for various 1991 * reasons. Only for information independent of frame capture, or that 1992 * require specific timing. The ownership of the message structure remains 1993 * with the HAL, and the msg only needs to be valid for the duration of this 1994 * call. 1995 * 1996 * Multiple threads may call notify() simultaneously. 1997 * 1998 * <= CAMERA_DEVICE_API_VERSION_3_1: 1999 * 2000 * The notification for the start of exposure for a given request must be 2001 * sent by the HAL before the first call to process_capture_result() for 2002 * that request is made. 2003 * 2004 * >= CAMERA_DEVICE_API_VERSION_3_2: 2005 * 2006 * Buffers delivered to the framework will not be dispatched to the 2007 * application layer until a start of exposure timestamp has been received 2008 * via a SHUTTER notify() call. It is highly recommended to 2009 * dispatch this call as early as possible. 2010 * 2011 * ------------------------------------------------------------------------ 2012 * Performance requirements: 2013 * 2014 * This is a non-blocking call. The framework will return this call in 5ms. 2015 */ 2016 void (*notify)(const struct camera3_callback_ops *, 2017 const camera3_notify_msg_t *msg); 2018 2019} camera3_callback_ops_t; 2020 2021/********************************************************************** 2022 * 2023 * Camera device operations 2024 * 2025 */ 2026typedef struct camera3_device_ops { 2027 2028 /** 2029 * initialize: 2030 * 2031 * One-time initialization to pass framework callback function pointers to 2032 * the HAL. Will be called once after a successful open() call, before any 2033 * other functions are called on the camera3_device_ops structure. 2034 * 2035 * Performance requirements: 2036 * 2037 * This should be a non-blocking call. The HAL should return from this call 2038 * in 5ms, and must return from this call in 10ms. 2039 * 2040 * Return values: 2041 * 2042 * 0: On successful initialization 2043 * 2044 * -ENODEV: If initialization fails. Only close() can be called successfully 2045 * by the framework after this. 2046 */ 2047 int (*initialize)(const struct camera3_device *, 2048 const camera3_callback_ops_t *callback_ops); 2049 2050 /********************************************************************** 2051 * Stream management 2052 */ 2053 2054 /** 2055 * configure_streams: 2056 * 2057 * CAMERA_DEVICE_API_VERSION_3_0 only: 2058 * 2059 * Reset the HAL camera device processing pipeline and set up new input and 2060 * output streams. This call replaces any existing stream configuration with 2061 * the streams defined in the stream_list. This method will be called at 2062 * least once after initialize() before a request is submitted with 2063 * process_capture_request(). 2064 * 2065 * The stream_list must contain at least one output-capable stream, and may 2066 * not contain more than one input-capable stream. 2067 * 2068 * The stream_list may contain streams that are also in the currently-active 2069 * set of streams (from the previous call to configure_stream()). These 2070 * streams will already have valid values for usage, max_buffers, and the 2071 * private pointer. 2072 * 2073 * If such a stream has already had its buffers registered, 2074 * register_stream_buffers() will not be called again for the stream, and 2075 * buffers from the stream can be immediately included in input requests. 2076 * 2077 * If the HAL needs to change the stream configuration for an existing 2078 * stream due to the new configuration, it may rewrite the values of usage 2079 * and/or max_buffers during the configure call. 2080 * 2081 * The framework will detect such a change, and will then reallocate the 2082 * stream buffers, and call register_stream_buffers() again before using 2083 * buffers from that stream in a request. 2084 * 2085 * If a currently-active stream is not included in stream_list, the HAL may 2086 * safely remove any references to that stream. It will not be reused in a 2087 * later configure() call by the framework, and all the gralloc buffers for 2088 * it will be freed after the configure_streams() call returns. 2089 * 2090 * The stream_list structure is owned by the framework, and may not be 2091 * accessed once this call completes. The address of an individual 2092 * camera3_stream_t structure will remain valid for access by the HAL until 2093 * the end of the first configure_stream() call which no longer includes 2094 * that camera3_stream_t in the stream_list argument. The HAL may not change 2095 * values in the stream structure outside of the private pointer, except for 2096 * the usage and max_buffers members during the configure_streams() call 2097 * itself. 2098 * 2099 * If the stream is new, the usage, max_buffer, and private pointer fields 2100 * of the stream structure will all be set to 0. The HAL device must set 2101 * these fields before the configure_streams() call returns. These fields 2102 * are then used by the framework and the platform gralloc module to 2103 * allocate the gralloc buffers for each stream. 2104 * 2105 * Before such a new stream can have its buffers included in a capture 2106 * request, the framework will call register_stream_buffers() with that 2107 * stream. However, the framework is not required to register buffers for 2108 * _all_ streams before submitting a request. This allows for quick startup 2109 * of (for example) a preview stream, with allocation for other streams 2110 * happening later or concurrently. 2111 * 2112 * ------------------------------------------------------------------------ 2113 * CAMERA_DEVICE_API_VERSION_3_1 only: 2114 * 2115 * Reset the HAL camera device processing pipeline and set up new input and 2116 * output streams. This call replaces any existing stream configuration with 2117 * the streams defined in the stream_list. This method will be called at 2118 * least once after initialize() before a request is submitted with 2119 * process_capture_request(). 2120 * 2121 * The stream_list must contain at least one output-capable stream, and may 2122 * not contain more than one input-capable stream. 2123 * 2124 * The stream_list may contain streams that are also in the currently-active 2125 * set of streams (from the previous call to configure_stream()). These 2126 * streams will already have valid values for usage, max_buffers, and the 2127 * private pointer. 2128 * 2129 * If such a stream has already had its buffers registered, 2130 * register_stream_buffers() will not be called again for the stream, and 2131 * buffers from the stream can be immediately included in input requests. 2132 * 2133 * If the HAL needs to change the stream configuration for an existing 2134 * stream due to the new configuration, it may rewrite the values of usage 2135 * and/or max_buffers during the configure call. 2136 * 2137 * The framework will detect such a change, and will then reallocate the 2138 * stream buffers, and call register_stream_buffers() again before using 2139 * buffers from that stream in a request. 2140 * 2141 * If a currently-active stream is not included in stream_list, the HAL may 2142 * safely remove any references to that stream. It will not be reused in a 2143 * later configure() call by the framework, and all the gralloc buffers for 2144 * it will be freed after the configure_streams() call returns. 2145 * 2146 * The stream_list structure is owned by the framework, and may not be 2147 * accessed once this call completes. The address of an individual 2148 * camera3_stream_t structure will remain valid for access by the HAL until 2149 * the end of the first configure_stream() call which no longer includes 2150 * that camera3_stream_t in the stream_list argument. The HAL may not change 2151 * values in the stream structure outside of the private pointer, except for 2152 * the usage and max_buffers members during the configure_streams() call 2153 * itself. 2154 * 2155 * If the stream is new, max_buffer, and private pointer fields of the 2156 * stream structure will all be set to 0. The usage will be set to the 2157 * consumer usage flags. The HAL device must set these fields before the 2158 * configure_streams() call returns. These fields are then used by the 2159 * framework and the platform gralloc module to allocate the gralloc 2160 * buffers for each stream. 2161 * 2162 * Before such a new stream can have its buffers included in a capture 2163 * request, the framework will call register_stream_buffers() with that 2164 * stream. However, the framework is not required to register buffers for 2165 * _all_ streams before submitting a request. This allows for quick startup 2166 * of (for example) a preview stream, with allocation for other streams 2167 * happening later or concurrently. 2168 * 2169 * ------------------------------------------------------------------------ 2170 * >= CAMERA_DEVICE_API_VERSION_3_2: 2171 * 2172 * Reset the HAL camera device processing pipeline and set up new input and 2173 * output streams. This call replaces any existing stream configuration with 2174 * the streams defined in the stream_list. This method will be called at 2175 * least once after initialize() before a request is submitted with 2176 * process_capture_request(). 2177 * 2178 * The stream_list must contain at least one output-capable stream, and may 2179 * not contain more than one input-capable stream. 2180 * 2181 * The stream_list may contain streams that are also in the currently-active 2182 * set of streams (from the previous call to configure_stream()). These 2183 * streams will already have valid values for usage, max_buffers, and the 2184 * private pointer. 2185 * 2186 * If the HAL needs to change the stream configuration for an existing 2187 * stream due to the new configuration, it may rewrite the values of usage 2188 * and/or max_buffers during the configure call. 2189 * 2190 * The framework will detect such a change, and may then reallocate the 2191 * stream buffers before using buffers from that stream in a request. 2192 * 2193 * If a currently-active stream is not included in stream_list, the HAL may 2194 * safely remove any references to that stream. It will not be reused in a 2195 * later configure() call by the framework, and all the gralloc buffers for 2196 * it will be freed after the configure_streams() call returns. 2197 * 2198 * The stream_list structure is owned by the framework, and may not be 2199 * accessed once this call completes. The address of an individual 2200 * camera3_stream_t structure will remain valid for access by the HAL until 2201 * the end of the first configure_stream() call which no longer includes 2202 * that camera3_stream_t in the stream_list argument. The HAL may not change 2203 * values in the stream structure outside of the private pointer, except for 2204 * the usage and max_buffers members during the configure_streams() call 2205 * itself. 2206 * 2207 * If the stream is new, max_buffer, and private pointer fields of the 2208 * stream structure will all be set to 0. The usage will be set to the 2209 * consumer usage flags. The HAL device must set these fields before the 2210 * configure_streams() call returns. These fields are then used by the 2211 * framework and the platform gralloc module to allocate the gralloc 2212 * buffers for each stream. 2213 * 2214 * Newly allocated buffers may be included in a capture request at any time 2215 * by the framework. Once a gralloc buffer is returned to the framework 2216 * with process_capture_result (and its respective release_fence has been 2217 * signaled) the framework may free or reuse it at any time. 2218 * 2219 * ------------------------------------------------------------------------ 2220 * 2221 * Preconditions: 2222 * 2223 * The framework will only call this method when no captures are being 2224 * processed. That is, all results have been returned to the framework, and 2225 * all in-flight input and output buffers have been returned and their 2226 * release sync fences have been signaled by the HAL. The framework will not 2227 * submit new requests for capture while the configure_streams() call is 2228 * underway. 2229 * 2230 * Postconditions: 2231 * 2232 * The HAL device must configure itself to provide maximum possible output 2233 * frame rate given the sizes and formats of the output streams, as 2234 * documented in the camera device's static metadata. 2235 * 2236 * Performance requirements: 2237 * 2238 * This call is expected to be heavyweight and possibly take several hundred 2239 * milliseconds to complete, since it may require resetting and 2240 * reconfiguring the image sensor and the camera processing pipeline. 2241 * Nevertheless, the HAL device should attempt to minimize the 2242 * reconfiguration delay to minimize the user-visible pauses during 2243 * application operational mode changes (such as switching from still 2244 * capture to video recording). 2245 * 2246 * The HAL should return from this call in 500ms, and must return from this 2247 * call in 1000ms. 2248 * 2249 * Return values: 2250 * 2251 * 0: On successful stream configuration 2252 * 2253 * -EINVAL: If the requested stream configuration is invalid. Some examples 2254 * of invalid stream configurations include: 2255 * 2256 * - Including more than 1 input-capable stream (INPUT or 2257 * BIDIRECTIONAL) 2258 * 2259 * - Not including any output-capable streams (OUTPUT or 2260 * BIDIRECTIONAL) 2261 * 2262 * - Including streams with unsupported formats, or an unsupported 2263 * size for that format. 2264 * 2265 * - Including too many output streams of a certain format. 2266 * 2267 * Note that the framework submitting an invalid stream 2268 * configuration is not normal operation, since stream 2269 * configurations are checked before configure. An invalid 2270 * configuration means that a bug exists in the framework code, or 2271 * there is a mismatch between the HAL's static metadata and the 2272 * requirements on streams. 2273 * 2274 * -ENODEV: If there has been a fatal error and the device is no longer 2275 * operational. Only close() can be called successfully by the 2276 * framework after this error is returned. 2277 */ 2278 int (*configure_streams)(const struct camera3_device *, 2279 camera3_stream_configuration_t *stream_list); 2280 2281 /** 2282 * register_stream_buffers: 2283 * 2284 * >= CAMERA_DEVICE_API_VERSION_3_2: 2285 * 2286 * DEPRECATED. This will not be called and must be set to NULL. 2287 * 2288 * <= CAMERA_DEVICE_API_VERSION_3_1: 2289 * 2290 * Register buffers for a given stream with the HAL device. This method is 2291 * called by the framework after a new stream is defined by 2292 * configure_streams, and before buffers from that stream are included in a 2293 * capture request. If the same stream is listed in a subsequent 2294 * configure_streams() call, register_stream_buffers will _not_ be called 2295 * again for that stream. 2296 * 2297 * The framework does not need to register buffers for all configured 2298 * streams before it submits the first capture request. This allows quick 2299 * startup for preview (or similar use cases) while other streams are still 2300 * being allocated. 2301 * 2302 * This method is intended to allow the HAL device to map or otherwise 2303 * prepare the buffers for later use. The buffers passed in will already be 2304 * locked for use. At the end of the call, all the buffers must be ready to 2305 * be returned to the stream. The buffer_set argument is only valid for the 2306 * duration of this call. 2307 * 2308 * If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 2309 * the camera HAL should inspect the passed-in buffers here to determine any 2310 * platform-private pixel format information. 2311 * 2312 * Performance requirements: 2313 * 2314 * This should be a non-blocking call. The HAL should return from this call 2315 * in 1ms, and must return from this call in 5ms. 2316 * 2317 * Return values: 2318 * 2319 * 0: On successful registration of the new stream buffers 2320 * 2321 * -EINVAL: If the stream_buffer_set does not refer to a valid active 2322 * stream, or if the buffers array is invalid. 2323 * 2324 * -ENOMEM: If there was a failure in registering the buffers. The framework 2325 * must consider all the stream buffers to be unregistered, and can 2326 * try to register again later. 2327 * 2328 * -ENODEV: If there is a fatal error, and the device is no longer 2329 * operational. Only close() can be called successfully by the 2330 * framework after this error is returned. 2331 */ 2332 int (*register_stream_buffers)(const struct camera3_device *, 2333 const camera3_stream_buffer_set_t *buffer_set); 2334 2335 /********************************************************************** 2336 * Request creation and submission 2337 */ 2338 2339 /** 2340 * construct_default_request_settings: 2341 * 2342 * Create capture settings for standard camera use cases. 2343 * 2344 * The device must return a settings buffer that is configured to meet the 2345 * requested use case, which must be one of the CAMERA3_TEMPLATE_* 2346 * enums. All request control fields must be included. 2347 * 2348 * The HAL retains ownership of this structure, but the pointer to the 2349 * structure must be valid until the device is closed. The framework and the 2350 * HAL may not modify the buffer once it is returned by this call. The same 2351 * buffer may be returned for subsequent calls for the same template, or for 2352 * other templates. 2353 * 2354 * Performance requirements: 2355 * 2356 * This should be a non-blocking call. The HAL should return from this call 2357 * in 1ms, and must return from this call in 5ms. 2358 * 2359 * Return values: 2360 * 2361 * Valid metadata: On successful creation of a default settings 2362 * buffer. 2363 * 2364 * NULL: In case of a fatal error. After this is returned, only 2365 * the close() method can be called successfully by the 2366 * framework. 2367 */ 2368 const camera_metadata_t* (*construct_default_request_settings)( 2369 const struct camera3_device *, 2370 int type); 2371 2372 /** 2373 * process_capture_request: 2374 * 2375 * Send a new capture request to the HAL. The HAL should not return from 2376 * this call until it is ready to accept the next request to process. Only 2377 * one call to process_capture_request() will be made at a time by the 2378 * framework, and the calls will all be from the same thread. The next call 2379 * to process_capture_request() will be made as soon as a new request and 2380 * its associated buffers are available. In a normal preview scenario, this 2381 * means the function will be called again by the framework almost 2382 * instantly. 2383 * 2384 * The actual request processing is asynchronous, with the results of 2385 * capture being returned by the HAL through the process_capture_result() 2386 * call. This call requires the result metadata to be available, but output 2387 * buffers may simply provide sync fences to wait on. Multiple requests are 2388 * expected to be in flight at once, to maintain full output frame rate. 2389 * 2390 * The framework retains ownership of the request structure. It is only 2391 * guaranteed to be valid during this call. The HAL device must make copies 2392 * of the information it needs to retain for the capture processing. The HAL 2393 * is responsible for waiting on and closing the buffers' fences and 2394 * returning the buffer handles to the framework. 2395 * 2396 * The HAL must write the file descriptor for the input buffer's release 2397 * sync fence into input_buffer->release_fence, if input_buffer is not 2398 * NULL. If the HAL returns -1 for the input buffer release sync fence, the 2399 * framework is free to immediately reuse the input buffer. Otherwise, the 2400 * framework will wait on the sync fence before refilling and reusing the 2401 * input buffer. 2402 * 2403 * >= CAMERA_DEVICE_API_VERSION_3_2: 2404 * 2405 * The input/output buffers provided by the framework in each request 2406 * may be brand new (having never before seen by the HAL). 2407 * 2408 * ------------------------------------------------------------------------ 2409 * Performance considerations: 2410 * 2411 * Handling a new buffer should be extremely lightweight and there should be 2412 * no frame rate degradation or frame jitter introduced. 2413 * 2414 * This call must return fast enough to ensure that the requested frame 2415 * rate can be sustained, especially for streaming cases (post-processing 2416 * quality settings set to FAST). The HAL should return this call in 1 2417 * frame interval, and must return from this call in 4 frame intervals. 2418 * 2419 * Return values: 2420 * 2421 * 0: On a successful start to processing the capture request 2422 * 2423 * -EINVAL: If the input is malformed (the settings are NULL when not 2424 * allowed, there are 0 output buffers, etc) and capture processing 2425 * cannot start. Failures during request processing should be 2426 * handled by calling camera3_callback_ops_t.notify(). In case of 2427 * this error, the framework will retain responsibility for the 2428 * stream buffers' fences and the buffer handles; the HAL should 2429 * not close the fences or return these buffers with 2430 * process_capture_result. 2431 * 2432 * -ENODEV: If the camera device has encountered a serious error. After this 2433 * error is returned, only the close() method can be successfully 2434 * called by the framework. 2435 * 2436 */ 2437 int (*process_capture_request)(const struct camera3_device *, 2438 camera3_capture_request_t *request); 2439 2440 /********************************************************************** 2441 * Miscellaneous methods 2442 */ 2443 2444 /** 2445 * get_metadata_vendor_tag_ops: 2446 * 2447 * Get methods to query for vendor extension metadata tag information. The 2448 * HAL should fill in all the vendor tag operation methods, or leave ops 2449 * unchanged if no vendor tags are defined. 2450 * 2451 * The definition of vendor_tag_query_ops_t can be found in 2452 * system/media/camera/include/system/camera_metadata.h. 2453 * 2454 * >= CAMERA_DEVICE_API_VERSION_3_2: 2455 * DEPRECATED. This function has been deprecated and should be set to 2456 * NULL by the HAL. Please implement get_vendor_tag_ops in camera_common.h 2457 * instead. 2458 */ 2459 void (*get_metadata_vendor_tag_ops)(const struct camera3_device*, 2460 vendor_tag_query_ops_t* ops); 2461 2462 /** 2463 * dump: 2464 * 2465 * Print out debugging state for the camera device. This will be called by 2466 * the framework when the camera service is asked for a debug dump, which 2467 * happens when using the dumpsys tool, or when capturing a bugreport. 2468 * 2469 * The passed-in file descriptor can be used to write debugging text using 2470 * dprintf() or write(). The text should be in ASCII encoding only. 2471 * 2472 * Performance requirements: 2473 * 2474 * This must be a non-blocking call. The HAL should return from this call 2475 * in 1ms, must return from this call in 10ms. This call must avoid 2476 * deadlocks, as it may be called at any point during camera operation. 2477 * Any synchronization primitives used (such as mutex locks or semaphores) 2478 * should be acquired with a timeout. 2479 */ 2480 void (*dump)(const struct camera3_device *, int fd); 2481 2482 /** 2483 * flush: 2484 * 2485 * Flush all currently in-process captures and all buffers in the pipeline 2486 * on the given device. The framework will use this to dump all state as 2487 * quickly as possible in order to prepare for a configure_streams() call. 2488 * 2489 * No buffers are required to be successfully returned, so every buffer 2490 * held at the time of flush() (whether successfully filled or not) may be 2491 * returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed 2492 * to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call, 2493 * provided they are successfully filled. 2494 * 2495 * All requests currently in the HAL are expected to be returned as soon as 2496 * possible. Not-in-process requests should return errors immediately. Any 2497 * interruptible hardware blocks should be stopped, and any uninterruptible 2498 * blocks should be waited on. 2499 * 2500 * More specifically, the HAL must follow below requirements for various cases: 2501 * 2502 * 1. For captures that are too late for the HAL to cancel/stop, and will be 2503 * completed normally by the HAL; i.e. the HAL can send shutter/notify and 2504 * process_capture_result and buffers as normal. 2505 * 2506 * 2. For pending requests that have not done any processing, the HAL must call notify 2507 * CAMERA3_MSG_ERROR_REQUEST, and return all the output buffers with 2508 * process_capture_result in the error state (CAMERA3_BUFFER_STATUS_ERROR). 2509 * The HAL must not place the release fence into an error state, instead, 2510 * the release fences must be set to the acquire fences passed by the framework, 2511 * or -1 if they have been waited on by the HAL already. This is also the path 2512 * to follow for any captures for which the HAL already called notify() with 2513 * CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers for. 2514 * After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only process_capture_results with 2515 * buffers in CAMERA3_BUFFER_STATUS_ERROR are allowed. No further notifys or 2516 * process_capture_result with non-null metadata is allowed. 2517 * 2518 * 3. For partially completed pending requests that will not have all the output 2519 * buffers or perhaps missing metadata, the HAL should follow below: 2520 * 2521 * 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected result 2522 * metadata (i.e. one or more partial metadata) won't be available for the capture. 2523 * 2524 * 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that won't 2525 * be produced for the capture. 2526 * 2527 * 3.3 Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp before 2528 * any buffers/metadata are returned with process_capture_result. 2529 * 2530 * 3.4 For captures that will produce some results, the HAL must not call 2531 * CAMERA3_MSG_ERROR_REQUEST, since that indicates complete failure. 2532 * 2533 * 3.5. Valid buffers/metadata should be passed to the framework as normal. 2534 * 2535 * 3.6. Failed buffers should be returned to the framework as described for case 2. 2536 * But failed buffers do not have to follow the strict ordering valid buffers do, 2537 * and may be out-of-order with respect to valid buffers. For example, if buffers 2538 * A, B, C, D, E are sent, D and E are failed, then A, E, B, D, C is an acceptable 2539 * return order. 2540 * 2541 * 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is sufficient, no 2542 * need to call process_capture_result with NULL metadata or equivalent. 2543 * 2544 * flush() should only return when there are no more outstanding buffers or 2545 * requests left in the HAL. The framework may call configure_streams (as 2546 * the HAL state is now quiesced) or may issue new requests. 2547 * 2548 * Note that it's sufficient to only support fully-succeeded and fully-failed result cases. 2549 * However, it is highly desirable to support the partial failure cases as well, as it 2550 * could help improve the flush call overall performance. 2551 * 2552 * Performance requirements: 2553 * 2554 * The HAL should return from this call in 100ms, and must return from this 2555 * call in 1000ms. And this call must not be blocked longer than pipeline 2556 * latency (see S7 for definition). 2557 * 2558 * Version information: 2559 * 2560 * only available if device version >= CAMERA_DEVICE_API_VERSION_3_1. 2561 * 2562 * Return values: 2563 * 2564 * 0: On a successful flush of the camera HAL. 2565 * 2566 * -EINVAL: If the input is malformed (the device is not valid). 2567 * 2568 * -ENODEV: If the camera device has encountered a serious error. After this 2569 * error is returned, only the close() method can be successfully 2570 * called by the framework. 2571 */ 2572 int (*flush)(const struct camera3_device *); 2573 2574 /* reserved for future use */ 2575 void *reserved[8]; 2576} camera3_device_ops_t; 2577 2578/********************************************************************** 2579 * 2580 * Camera device definition 2581 * 2582 */ 2583typedef struct camera3_device { 2584 /** 2585 * common.version must equal CAMERA_DEVICE_API_VERSION_3_0 to identify this 2586 * device as implementing version 3.0 of the camera device HAL. 2587 * 2588 * Performance requirements: 2589 * 2590 * common.open should return in 200ms, and must return in 500ms. 2591 */ 2592 hw_device_t common; 2593 camera3_device_ops_t *ops; 2594 void *priv; 2595} camera3_device_t; 2596 2597__END_DECLS 2598 2599#endif /* #ifdef ANDROID_INCLUDE_CAMERA3_H */ 2600
