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