1 /* 2 * Copyright (C) 2013-2018 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.6[ CAMERA_DEVICE_API_VERSION_3_6 ] 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 as LIMITED or above hardware level. 30 * 31 * Camera devices that support this version of the HAL must return 32 * CAMERA_DEVICE_API_VERSION_3_6 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_3 and above: 36 * Camera modules that may contain version 3.3 or above devices must 37 * implement at least version 2.2 of the camera module interface (as defined 38 * by camera_module_t.common.module_api_version). 39 * 40 * CAMERA_DEVICE_API_VERSION_3_2: 41 * Camera modules that may contain version 3.2 devices must implement at 42 * least version 2.2 of the camera module interface (as defined by 43 * camera_module_t.common.module_api_version). 44 * 45 * <= CAMERA_DEVICE_API_VERSION_3_1: 46 * Camera modules that may contain version 3.1 (or 3.0) devices must 47 * implement at least version 2.0 of the camera module interface 48 * (as defined by camera_module_t.common.module_api_version). 49 * 50 * See camera_common.h for more versioning details. 51 * 52 * Documentation index: 53 * S1. Version history 54 * S2. Startup and operation sequencing 55 * S3. Operational modes 56 * S4. 3A modes and state machines 57 * S5. Cropping 58 * S6. Error management 59 * S7. Key Performance Indicator (KPI) glossary 60 * S8. Sample Use Cases 61 * S9. Notes on Controls and Metadata 62 * S10. Reprocessing flow and controls 63 */ 64 65 /** 66 * S1. Version history: 67 * 68 * 1.0: Initial Android camera HAL (Android 4.0) [camera.h]: 69 * 70 * - Converted from C++ CameraHardwareInterface abstraction layer. 71 * 72 * - Supports android.hardware.Camera API. 73 * 74 * 2.0: Initial release of expanded-capability HAL (Android 4.2) [camera2.h]: 75 * 76 * - Sufficient for implementing existing android.hardware.Camera API. 77 * 78 * - Allows for ZSL queue in camera service layer 79 * 80 * - Not tested for any new features such manual capture control, Bayer RAW 81 * capture, reprocessing of RAW data. 82 * 83 * 3.0: First revision of expanded-capability HAL: 84 * 85 * - Major version change since the ABI is completely different. No change to 86 * the required hardware capabilities or operational model from 2.0. 87 * 88 * - Reworked input request and stream queue interfaces: Framework calls into 89 * HAL with next request and stream buffers already dequeued. Sync framework 90 * support is included, necessary for efficient implementations. 91 * 92 * - Moved triggers into requests, most notifications into results. 93 * 94 * - Consolidated all callbacks into framework into one structure, and all 95 * setup methods into a single initialize() call. 96 * 97 * - Made stream configuration into a single call to simplify stream 98 * management. Bidirectional streams replace STREAM_FROM_STREAM construct. 99 * 100 * - Limited mode semantics for older/limited hardware devices. 101 * 102 * 3.1: Minor revision of expanded-capability HAL: 103 * 104 * - configure_streams passes consumer usage flags to the HAL. 105 * 106 * - flush call to drop all in-flight requests/buffers as fast as possible. 107 * 108 * 3.2: Minor revision of expanded-capability HAL: 109 * 110 * - Deprecates get_metadata_vendor_tag_ops. Please use get_vendor_tag_ops 111 * in camera_common.h instead. 112 * 113 * - register_stream_buffers deprecated. All gralloc buffers provided 114 * by framework to HAL in process_capture_request may be new at any time. 115 * 116 * - add partial result support. process_capture_result may be called 117 * multiple times with a subset of the available result before the full 118 * result is available. 119 * 120 * - add manual template to camera3_request_template. The applications may 121 * use this template to control the capture settings directly. 122 * 123 * - Rework the bidirectional and input stream specifications. 124 * 125 * - change the input buffer return path. The buffer is returned in 126 * process_capture_result instead of process_capture_request. 127 * 128 * 3.3: Minor revision of expanded-capability HAL: 129 * 130 * - OPAQUE and YUV reprocessing API updates. 131 * 132 * - Basic support for depth output buffers. 133 * 134 * - Addition of data_space field to camera3_stream_t. 135 * 136 * - Addition of rotation field to camera3_stream_t. 137 * 138 * - Addition of camera3 stream configuration operation mode to camera3_stream_configuration_t 139 * 140 * 3.4: Minor additions to supported metadata and changes to data_space support 141 * 142 * - Add ANDROID_SENSOR_OPAQUE_RAW_SIZE static metadata as mandatory if 143 * RAW_OPAQUE format is supported. 144 * 145 * - Add ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE static metadata as 146 * mandatory if any RAW format is supported 147 * 148 * - Switch camera3_stream_t data_space field to a more flexible definition, 149 * using the version 0 definition of dataspace encoding. 150 * 151 * - General metadata additions which are available to use for HALv3.2 or 152 * newer: 153 * - ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3 154 * - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST 155 * - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE 156 * - ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL 157 * - ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL 158 * - ANDROID_SENSOR_OPAQUE_RAW_SIZE 159 * - ANDROID_SENSOR_OPTICAL_BLACK_REGIONS 160 * 161 * 3.5: Minor revisions to support session parameters and logical multi camera: 162 * 163 * - Add ANDROID_REQUEST_AVAILABLE_SESSION_KEYS static metadata, which is 164 * optional for implementations that want to support session parameters. If support is 165 * needed, then Hal should populate the list with all available capture request keys 166 * that can cause severe processing delays when modified by client. Typical examples 167 * include parameters that require time-consuming HW re-configuration or internal camera 168 * pipeline update. 169 * 170 * - Add a session parameter field to camera3_stream_configuration which can be populated 171 * by clients with initial values for the keys found in ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. 172 * 173 * - Metadata additions for logical multi camera capability: 174 * - ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA 175 * - ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS 176 * - ANDROID_LOGICAL_MULTI_CAMERA_SYNC_TYPE 177 * 178 * - Add physical camera id field in camera3_stream, so that for a logical 179 * multi camera, the application has the option to specify which physical camera 180 * a particular stream is configured on. 181 * 182 * - Add physical camera id and settings field in camera3_capture_request, so that 183 * for a logical multi camera, the application has the option to specify individual 184 * settings for a particular physical device. 185 * 186 * 3.6: Minor revisions to support HAL buffer management APIs: 187 * 188 * - Add ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION static metadata, which allows HAL to 189 * opt in to the new buffer management APIs described below. 190 * 191 * - Add request_stream_buffers() and return_stream_buffers() to camera3_callback_ops_t for HAL to 192 * request and return output buffers from camera service. 193 * 194 * - Add signal_stream_flush() to camera3_device_ops_t for camera service to notify HAL an 195 * upcoming configure_streams() call requires HAL to return buffers of certain streams. 196 * 197 * - Add CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID to support BLOB with only JPEG apps 198 * segments and thumbnail (without main image bitstream). Camera framework 199 * uses such stream togerther with a HAL YUV_420_888/IMPLEMENTATION_DEFINED 200 * stream to encode HEIC (ISO/IEC 23008-12) image. 201 * 202 * - Add is_reconfiguration_required() to camera3_device_ops_t to enable HAL to skip or 203 * trigger stream reconfiguration depending on new session parameter values. 204 * 205 */ 206 207 /** 208 * S2. Startup and general expected operation sequence: 209 * 210 * 1. Framework calls camera_module_t->common.open(), which returns a 211 * hardware_device_t structure. 212 * 213 * 2. Framework inspects the hardware_device_t->version field, and instantiates 214 * the appropriate handler for that version of the camera hardware device. In 215 * case the version is CAMERA_DEVICE_API_VERSION_3_0, the device is cast to 216 * a camera3_device_t. 217 * 218 * 3. Framework calls camera3_device_t->ops->initialize() with the framework 219 * callback function pointers. This will only be called this one time after 220 * open(), before any other functions in the ops structure are called. 221 * 222 * 4. The framework calls camera3_device_t->ops->configure_streams() with a list 223 * of input/output streams to the HAL device. 224 * 225 * 5. <= CAMERA_DEVICE_API_VERSION_3_1: 226 * 227 * The framework allocates gralloc buffers and calls 228 * camera3_device_t->ops->register_stream_buffers() for at least one of the 229 * output streams listed in configure_streams. The same stream is registered 230 * only once. 231 * 232 * >= CAMERA_DEVICE_API_VERSION_3_2: 233 * 234 * camera3_device_t->ops->register_stream_buffers() is not called and must 235 * be NULL. 236 * 237 * 6. The framework requests default settings for some number of use cases with 238 * calls to camera3_device_t->ops->construct_default_request_settings(). This 239 * may occur any time after step 3. 240 * 241 * 7. The framework constructs and sends the first capture request to the HAL, 242 * with settings based on one of the sets of default settings, and with at 243 * least one output stream, which has been registered earlier by the 244 * framework. This is sent to the HAL with 245 * camera3_device_t->ops->process_capture_request(). The HAL must block the 246 * return of this call until it is ready for the next request to be sent. 247 * 248 * >= CAMERA_DEVICE_API_VERSION_3_2: 249 * 250 * The buffer_handle_t provided in the camera3_stream_buffer_t array 251 * in the camera3_capture_request_t may be new and never-before-seen 252 * by the HAL on any given new request. 253 * 254 * 8. The framework continues to submit requests, and call 255 * construct_default_request_settings to get default settings buffers for 256 * other use cases. 257 * 258 * <= CAMERA_DEVICE_API_VERSION_3_1: 259 * 260 * The framework may call register_stream_buffers() at this time for 261 * not-yet-registered streams. 262 * 263 * 9. When the capture of a request begins (sensor starts exposing for the 264 * capture) or processing a reprocess request begins, the HAL 265 * calls camera3_callback_ops_t->notify() with the SHUTTER event, including 266 * the frame number and the timestamp for start of exposure. For a reprocess 267 * request, the timestamp must be the start of exposure of the input image 268 * which can be looked up with android.sensor.timestamp from 269 * camera3_capture_request_t.settings when process_capture_request() is 270 * called. 271 * 272 * <= CAMERA_DEVICE_API_VERSION_3_1: 273 * 274 * This notify call must be made before the first call to 275 * process_capture_result() for that frame number. 276 * 277 * >= CAMERA_DEVICE_API_VERSION_3_2: 278 * 279 * The camera3_callback_ops_t->notify() call with the SHUTTER event should 280 * be made as early as possible since the framework will be unable to 281 * deliver gralloc buffers to the application layer (for that frame) until 282 * it has a valid timestamp for the start of exposure (or the input image's 283 * start of exposure for a reprocess request). 284 * 285 * Both partial metadata results and the gralloc buffers may be sent to the 286 * framework at any time before or after the SHUTTER event. 287 * 288 * 10. After some pipeline delay, the HAL begins to return completed captures to 289 * the framework with camera3_callback_ops_t->process_capture_result(). These 290 * are returned in the same order as the requests were submitted. Multiple 291 * requests can be in flight at once, depending on the pipeline depth of the 292 * camera HAL device. 293 * 294 * >= CAMERA_DEVICE_API_VERSION_3_2: 295 * 296 * Once a buffer is returned by process_capture_result as part of the 297 * camera3_stream_buffer_t array, and the fence specified by release_fence 298 * has been signaled (this is a no-op for -1 fences), the ownership of that 299 * buffer is considered to be transferred back to the framework. After that, 300 * the HAL must no longer retain that particular buffer, and the 301 * framework may clean up the memory for it immediately. 302 * 303 * process_capture_result may be called multiple times for a single frame, 304 * each time with a new disjoint piece of metadata and/or set of gralloc 305 * buffers. The framework will accumulate these partial metadata results 306 * into one result. 307 * 308 * In particular, it is legal for a process_capture_result to be called 309 * simultaneously for both a frame N and a frame N+1 as long as the 310 * above rule holds for gralloc buffers (both input and output). 311 * 312 * 11. After some time, the framework may stop submitting new requests, wait for 313 * the existing captures to complete (all buffers filled, all results 314 * returned), and then call configure_streams() again. This resets the camera 315 * hardware and pipeline for a new set of input/output streams. Some streams 316 * may be reused from the previous configuration; if these streams' buffers 317 * had already been registered with the HAL, they will not be registered 318 * again. The framework then continues from step 7, if at least one 319 * registered output stream remains (otherwise, step 5 is required first). 320 * 321 * 12. Alternatively, the framework may call camera3_device_t->common->close() 322 * to end the camera session. This may be called at any time when no other 323 * calls from the framework are active, although the call may block until all 324 * in-flight captures have completed (all results returned, all buffers 325 * filled). After the close call returns, no more calls to the 326 * camera3_callback_ops_t functions are allowed from the HAL. Once the 327 * close() call is underway, the framework may not call any other HAL device 328 * functions. 329 * 330 * 13. In case of an error or other asynchronous event, the HAL must call 331 * camera3_callback_ops_t->notify() with the appropriate error/event 332 * message. After returning from a fatal device-wide error notification, the 333 * HAL should act as if close() had been called on it. However, the HAL must 334 * either cancel or complete all outstanding captures before calling 335 * notify(), so that once notify() is called with a fatal error, the 336 * framework will not receive further callbacks from the device. Methods 337 * besides close() should return -ENODEV or NULL after the notify() method 338 * returns from a fatal error message. 339 */ 340 341 /** 342 * S3. Operational modes: 343 * 344 * The camera 3 HAL device can implement one of two possible operational modes; 345 * limited and full. Full support is expected from new higher-end 346 * devices. Limited mode has hardware requirements roughly in line with those 347 * for a camera HAL device v1 implementation, and is expected from older or 348 * inexpensive devices. Full is a strict superset of limited, and they share the 349 * same essential operational flow, as documented above. 350 * 351 * The HAL must indicate its level of support with the 352 * android.info.supportedHardwareLevel static metadata entry, with 0 indicating 353 * limited mode, and 1 indicating full mode support. 354 * 355 * Roughly speaking, limited-mode devices do not allow for application control 356 * of capture settings (3A control only), high-rate capture of high-resolution 357 * images, raw sensor readout, or support for YUV output streams above maximum 358 * recording resolution (JPEG only for large images). 359 * 360 * ** Details of limited mode behavior: 361 * 362 * - Limited-mode devices do not need to implement accurate synchronization 363 * between capture request settings and the actual image data 364 * captured. Instead, changes to settings may take effect some time in the 365 * future, and possibly not for the same output frame for each settings 366 * entry. Rapid changes in settings may result in some settings never being 367 * used for a capture. However, captures that include high-resolution output 368 * buffers ( > 1080p ) have to use the settings as specified (but see below 369 * for processing rate). 370 * 371 * - Limited-mode devices do not need to support most of the 372 * settings/result/static info metadata. Specifically, only the following settings 373 * are expected to be consumed or produced by a limited-mode HAL device: 374 * 375 * android.control.aeAntibandingMode (controls and dynamic) 376 * android.control.aeExposureCompensation (controls and dynamic) 377 * android.control.aeLock (controls and dynamic) 378 * android.control.aeMode (controls and dynamic) 379 * android.control.aeRegions (controls and dynamic) 380 * android.control.aeTargetFpsRange (controls and dynamic) 381 * android.control.aePrecaptureTrigger (controls and dynamic) 382 * android.control.afMode (controls and dynamic) 383 * android.control.afRegions (controls and dynamic) 384 * android.control.awbLock (controls and dynamic) 385 * android.control.awbMode (controls and dynamic) 386 * android.control.awbRegions (controls and dynamic) 387 * android.control.captureIntent (controls and dynamic) 388 * android.control.effectMode (controls and dynamic) 389 * android.control.mode (controls and dynamic) 390 * android.control.sceneMode (controls and dynamic) 391 * android.control.videoStabilizationMode (controls and dynamic) 392 * android.control.aeAvailableAntibandingModes (static) 393 * android.control.aeAvailableModes (static) 394 * android.control.aeAvailableTargetFpsRanges (static) 395 * android.control.aeCompensationRange (static) 396 * android.control.aeCompensationStep (static) 397 * android.control.afAvailableModes (static) 398 * android.control.availableEffects (static) 399 * android.control.availableSceneModes (static) 400 * android.control.availableVideoStabilizationModes (static) 401 * android.control.awbAvailableModes (static) 402 * android.control.maxRegions (static) 403 * android.control.sceneModeOverrides (static) 404 * android.control.aeState (dynamic) 405 * android.control.afState (dynamic) 406 * android.control.awbState (dynamic) 407 * 408 * android.flash.mode (controls and dynamic) 409 * android.flash.info.available (static) 410 * 411 * android.info.supportedHardwareLevel (static) 412 * 413 * android.jpeg.gpsCoordinates (controls and dynamic) 414 * android.jpeg.gpsProcessingMethod (controls and dynamic) 415 * android.jpeg.gpsTimestamp (controls and dynamic) 416 * android.jpeg.orientation (controls and dynamic) 417 * android.jpeg.quality (controls and dynamic) 418 * android.jpeg.thumbnailQuality (controls and dynamic) 419 * android.jpeg.thumbnailSize (controls and dynamic) 420 * android.jpeg.availableThumbnailSizes (static) 421 * android.jpeg.maxSize (static) 422 * 423 * android.lens.info.minimumFocusDistance (static) 424 * 425 * android.request.id (controls and dynamic) 426 * 427 * android.scaler.cropRegion (controls and dynamic) 428 * android.scaler.availableStreamConfigurations (static) 429 * android.scaler.availableMinFrameDurations (static) 430 * android.scaler.availableStallDurations (static) 431 * android.scaler.availableMaxDigitalZoom (static) 432 * android.scaler.maxDigitalZoom (static) 433 * android.scaler.croppingType (static) 434 * 435 * android.sensor.orientation (static) 436 * android.sensor.timestamp (dynamic) 437 * 438 * android.statistics.faceDetectMode (controls and dynamic) 439 * android.statistics.info.availableFaceDetectModes (static) 440 * android.statistics.faceIds (dynamic) 441 * android.statistics.faceLandmarks (dynamic) 442 * android.statistics.faceRectangles (dynamic) 443 * android.statistics.faceScores (dynamic) 444 * 445 * android.sync.frameNumber (dynamic) 446 * android.sync.maxLatency (static) 447 * 448 * - Captures in limited mode that include high-resolution (> 1080p) output 449 * buffers may block in process_capture_request() until all the output buffers 450 * have been filled. A full-mode HAL device must process sequences of 451 * high-resolution requests at the rate indicated in the static metadata for 452 * that pixel format. The HAL must still call process_capture_result() to 453 * provide the output; the framework must simply be prepared for 454 * process_capture_request() to block until after process_capture_result() for 455 * that request completes for high-resolution captures for limited-mode 456 * devices. 457 * 458 * - Full-mode devices must support below additional capabilities: 459 * - 30fps at maximum resolution is preferred, more than 20fps is required. 460 * - Per frame control (android.sync.maxLatency == PER_FRAME_CONTROL). 461 * - Sensor manual control metadata. See MANUAL_SENSOR defined in 462 * android.request.availableCapabilities. 463 * - Post-processing manual control metadata. See MANUAL_POST_PROCESSING defined 464 * in android.request.availableCapabilities. 465 * 466 */ 467 468 /** 469 * S4. 3A modes and state machines: 470 * 471 * While the actual 3A algorithms are up to the HAL implementation, a high-level 472 * state machine description is defined by the HAL interface, to allow the HAL 473 * device and the framework to communicate about the current state of 3A, and to 474 * trigger 3A events. 475 * 476 * When the device is opened, all the individual 3A states must be 477 * STATE_INACTIVE. Stream configuration does not reset 3A. For example, locked 478 * focus must be maintained across the configure() call. 479 * 480 * Triggering a 3A action involves simply setting the relevant trigger entry in 481 * the settings for the next request to indicate start of trigger. For example, 482 * the trigger for starting an autofocus scan is setting the entry 483 * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTROL_AF_TRIGGER_START for one 484 * request, and cancelling an autofocus scan is triggered by setting 485 * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTRL_AF_TRIGGER_CANCEL. Otherwise, 486 * the entry will not exist, or be set to ANDROID_CONTROL_AF_TRIGGER_IDLE. Each 487 * request with a trigger entry set to a non-IDLE value will be treated as an 488 * independent triggering event. 489 * 490 * At the top level, 3A is controlled by the ANDROID_CONTROL_MODE setting, which 491 * selects between no 3A (ANDROID_CONTROL_MODE_OFF), normal AUTO mode 492 * (ANDROID_CONTROL_MODE_AUTO), and using the scene mode setting 493 * (ANDROID_CONTROL_USE_SCENE_MODE). 494 * 495 * - In OFF mode, each of the individual AE/AF/AWB modes are effectively OFF, 496 * and none of the capture controls may be overridden by the 3A routines. 497 * 498 * - In AUTO mode, Auto-focus, auto-exposure, and auto-whitebalance all run 499 * their own independent algorithms, and have their own mode, state, and 500 * trigger metadata entries, as listed in the next section. 501 * 502 * - In USE_SCENE_MODE, the value of the ANDROID_CONTROL_SCENE_MODE entry must 503 * be used to determine the behavior of 3A routines. In SCENE_MODEs other than 504 * FACE_PRIORITY, the HAL must override the values of 505 * ANDROId_CONTROL_AE/AWB/AF_MODE to be the mode it prefers for the selected 506 * SCENE_MODE. For example, the HAL may prefer SCENE_MODE_NIGHT to use 507 * CONTINUOUS_FOCUS AF mode. Any user selection of AE/AWB/AF_MODE when scene 508 * must be ignored for these scene modes. 509 * 510 * - For SCENE_MODE_FACE_PRIORITY, the AE/AWB/AF_MODE controls work as in 511 * ANDROID_CONTROL_MODE_AUTO, but the 3A routines must bias toward metering 512 * and focusing on any detected faces in the scene. 513 * 514 * S4.1. Auto-focus settings and result entries: 515 * 516 * Main metadata entries: 517 * 518 * ANDROID_CONTROL_AF_MODE: Control for selecting the current autofocus 519 * mode. Set by the framework in the request settings. 520 * 521 * AF_MODE_OFF: AF is disabled; the framework/app directly controls lens 522 * position. 523 * 524 * AF_MODE_AUTO: Single-sweep autofocus. No lens movement unless AF is 525 * triggered. 526 * 527 * AF_MODE_MACRO: Single-sweep up-close autofocus. No lens movement unless 528 * AF is triggered. 529 * 530 * AF_MODE_CONTINUOUS_VIDEO: Smooth continuous focusing, for recording 531 * video. Triggering immediately locks focus in current 532 * position. Canceling resumes cotinuous focusing. 533 * 534 * AF_MODE_CONTINUOUS_PICTURE: Fast continuous focusing, for 535 * zero-shutter-lag still capture. Triggering locks focus once currently 536 * active sweep concludes. Canceling resumes continuous focusing. 537 * 538 * AF_MODE_EDOF: Advanced extended depth of field focusing. There is no 539 * autofocus scan, so triggering one or canceling one has no effect. 540 * Images are focused automatically by the HAL. 541 * 542 * ANDROID_CONTROL_AF_STATE: Dynamic metadata describing the current AF 543 * algorithm state, reported by the HAL in the result metadata. 544 * 545 * AF_STATE_INACTIVE: No focusing has been done, or algorithm was 546 * reset. Lens is not moving. Always the state for MODE_OFF or MODE_EDOF. 547 * When the device is opened, it must start in this state. 548 * 549 * AF_STATE_PASSIVE_SCAN: A continuous focus algorithm is currently scanning 550 * for good focus. The lens is moving. 551 * 552 * AF_STATE_PASSIVE_FOCUSED: A continuous focus algorithm believes it is 553 * well focused. The lens is not moving. The HAL may spontaneously leave 554 * this state. 555 * 556 * AF_STATE_PASSIVE_UNFOCUSED: A continuous focus algorithm believes it is 557 * not well focused. The lens is not moving. The HAL may spontaneously 558 * leave this state. 559 * 560 * AF_STATE_ACTIVE_SCAN: A scan triggered by the user is underway. 561 * 562 * AF_STATE_FOCUSED_LOCKED: The AF algorithm believes it is focused. The 563 * lens is not moving. 564 * 565 * AF_STATE_NOT_FOCUSED_LOCKED: The AF algorithm has been unable to 566 * focus. The lens is not moving. 567 * 568 * ANDROID_CONTROL_AF_TRIGGER: Control for starting an autofocus scan, the 569 * meaning of which is mode- and state- dependent. Set by the framework in 570 * the request settings. 571 * 572 * AF_TRIGGER_IDLE: No current trigger. 573 * 574 * AF_TRIGGER_START: Trigger start of AF scan. Effect is mode and state 575 * dependent. 576 * 577 * AF_TRIGGER_CANCEL: Cancel current AF scan if any, and reset algorithm to 578 * default. 579 * 580 * Additional metadata entries: 581 * 582 * ANDROID_CONTROL_AF_REGIONS: Control for selecting the regions of the FOV 583 * that should be used to determine good focus. This applies to all AF 584 * modes that scan for focus. Set by the framework in the request 585 * settings. 586 * 587 * S4.2. Auto-exposure settings and result entries: 588 * 589 * Main metadata entries: 590 * 591 * ANDROID_CONTROL_AE_MODE: Control for selecting the current auto-exposure 592 * mode. Set by the framework in the request settings. 593 * 594 * AE_MODE_OFF: Autoexposure is disabled; the user controls exposure, gain, 595 * frame duration, and flash. 596 * 597 * AE_MODE_ON: Standard autoexposure, with flash control disabled. User may 598 * set flash to fire or to torch mode. 599 * 600 * AE_MODE_ON_AUTO_FLASH: Standard autoexposure, with flash on at HAL's 601 * discretion for precapture and still capture. User control of flash 602 * disabled. 603 * 604 * AE_MODE_ON_ALWAYS_FLASH: Standard autoexposure, with flash always fired 605 * for capture, and at HAL's discretion for precapture.. User control of 606 * flash disabled. 607 * 608 * AE_MODE_ON_AUTO_FLASH_REDEYE: Standard autoexposure, with flash on at 609 * HAL's discretion for precapture and still capture. Use a flash burst 610 * at end of precapture sequence to reduce redeye in the final 611 * picture. User control of flash disabled. 612 * 613 * ANDROID_CONTROL_AE_STATE: Dynamic metadata describing the current AE 614 * algorithm state, reported by the HAL in the result metadata. 615 * 616 * AE_STATE_INACTIVE: Initial AE state after mode switch. When the device is 617 * opened, it must start in this state. 618 * 619 * AE_STATE_SEARCHING: AE is not converged to a good value, and is adjusting 620 * exposure parameters. 621 * 622 * AE_STATE_CONVERGED: AE has found good exposure values for the current 623 * scene, and the exposure parameters are not changing. HAL may 624 * spontaneously leave this state to search for better solution. 625 * 626 * AE_STATE_LOCKED: AE has been locked with the AE_LOCK control. Exposure 627 * values are not changing. 628 * 629 * AE_STATE_FLASH_REQUIRED: The HAL has converged exposure, but believes 630 * flash is required for a sufficiently bright picture. Used for 631 * determining if a zero-shutter-lag frame can be used. 632 * 633 * AE_STATE_PRECAPTURE: The HAL is in the middle of a precapture 634 * sequence. Depending on AE mode, this mode may involve firing the 635 * flash for metering, or a burst of flash pulses for redeye reduction. 636 * 637 * ANDROID_CONTROL_AE_PRECAPTURE_TRIGGER: Control for starting a metering 638 * sequence before capturing a high-quality image. Set by the framework in 639 * the request settings. 640 * 641 * PRECAPTURE_TRIGGER_IDLE: No current trigger. 642 * 643 * PRECAPTURE_TRIGGER_START: Start a precapture sequence. The HAL should 644 * use the subsequent requests to measure good exposure/white balance 645 * for an upcoming high-resolution capture. 646 * 647 * Additional metadata entries: 648 * 649 * ANDROID_CONTROL_AE_LOCK: Control for locking AE controls to their current 650 * values 651 * 652 * ANDROID_CONTROL_AE_EXPOSURE_COMPENSATION: Control for adjusting AE 653 * algorithm target brightness point. 654 * 655 * ANDROID_CONTROL_AE_TARGET_FPS_RANGE: Control for selecting the target frame 656 * rate range for the AE algorithm. The AE routine cannot change the frame 657 * rate to be outside these bounds. 658 * 659 * ANDROID_CONTROL_AE_REGIONS: Control for selecting the regions of the FOV 660 * that should be used to determine good exposure levels. This applies to 661 * all AE modes besides OFF. 662 * 663 * S4.3. Auto-whitebalance settings and result entries: 664 * 665 * Main metadata entries: 666 * 667 * ANDROID_CONTROL_AWB_MODE: Control for selecting the current white-balance 668 * mode. 669 * 670 * AWB_MODE_OFF: Auto-whitebalance is disabled. User controls color matrix. 671 * 672 * AWB_MODE_AUTO: Automatic white balance is enabled; 3A controls color 673 * transform, possibly using more complex transforms than a simple 674 * matrix. 675 * 676 * AWB_MODE_INCANDESCENT: Fixed white balance settings good for indoor 677 * incandescent (tungsten) lighting, roughly 2700K. 678 * 679 * AWB_MODE_FLUORESCENT: Fixed white balance settings good for fluorescent 680 * lighting, roughly 5000K. 681 * 682 * AWB_MODE_WARM_FLUORESCENT: Fixed white balance settings good for 683 * fluorescent lighting, roughly 3000K. 684 * 685 * AWB_MODE_DAYLIGHT: Fixed white balance settings good for daylight, 686 * roughly 5500K. 687 * 688 * AWB_MODE_CLOUDY_DAYLIGHT: Fixed white balance settings good for clouded 689 * daylight, roughly 6500K. 690 * 691 * AWB_MODE_TWILIGHT: Fixed white balance settings good for 692 * near-sunset/sunrise, roughly 15000K. 693 * 694 * AWB_MODE_SHADE: Fixed white balance settings good for areas indirectly 695 * lit by the sun, roughly 7500K. 696 * 697 * ANDROID_CONTROL_AWB_STATE: Dynamic metadata describing the current AWB 698 * algorithm state, reported by the HAL in the result metadata. 699 * 700 * AWB_STATE_INACTIVE: Initial AWB state after mode switch. When the device 701 * is opened, it must start in this state. 702 * 703 * AWB_STATE_SEARCHING: AWB is not converged to a good value, and is 704 * changing color adjustment parameters. 705 * 706 * AWB_STATE_CONVERGED: AWB has found good color adjustment values for the 707 * current scene, and the parameters are not changing. HAL may 708 * spontaneously leave this state to search for better solution. 709 * 710 * AWB_STATE_LOCKED: AWB has been locked with the AWB_LOCK control. Color 711 * adjustment values are not changing. 712 * 713 * Additional metadata entries: 714 * 715 * ANDROID_CONTROL_AWB_LOCK: Control for locking AWB color adjustments to 716 * their current values. 717 * 718 * ANDROID_CONTROL_AWB_REGIONS: Control for selecting the regions of the FOV 719 * that should be used to determine good color balance. This applies only 720 * to auto-WB mode. 721 * 722 * S4.4. General state machine transition notes 723 * 724 * Switching between AF, AE, or AWB modes always resets the algorithm's state 725 * to INACTIVE. Similarly, switching between CONTROL_MODE or 726 * CONTROL_SCENE_MODE if CONTROL_MODE == USE_SCENE_MODE resets all the 727 * algorithm states to INACTIVE. 728 * 729 * The tables below are per-mode. 730 * 731 * S4.5. AF state machines 732 * 733 * when enabling AF or changing AF mode 734 *| state | trans. cause | new state | notes | 735 *+--------------------+---------------+--------------------+------------------+ 736 *| Any | AF mode change| INACTIVE | | 737 *+--------------------+---------------+--------------------+------------------+ 738 * 739 * mode = AF_MODE_OFF or AF_MODE_EDOF 740 *| state | trans. cause | new state | notes | 741 *+--------------------+---------------+--------------------+------------------+ 742 *| INACTIVE | | INACTIVE | Never changes | 743 *+--------------------+---------------+--------------------+------------------+ 744 * 745 * mode = AF_MODE_AUTO or AF_MODE_MACRO 746 *| state | trans. cause | new state | notes | 747 *+--------------------+---------------+--------------------+------------------+ 748 *| INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep | 749 *| | | | Lens now moving | 750 *+--------------------+---------------+--------------------+------------------+ 751 *| ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | If AF successful | 752 *| | | | Lens now locked | 753 *+--------------------+---------------+--------------------+------------------+ 754 *| ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | If AF successful | 755 *| | | | Lens now locked | 756 *+--------------------+---------------+--------------------+------------------+ 757 *| ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF | 758 *| | | | Lens now locked | 759 *+--------------------+---------------+--------------------+------------------+ 760 *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | 761 *+--------------------+---------------+--------------------+------------------+ 762 *| FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | 763 *| | | | Lens now moving | 764 *+--------------------+---------------+--------------------+------------------+ 765 *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | 766 *+--------------------+---------------+--------------------+------------------+ 767 *| NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | 768 *| | | | Lens now moving | 769 *+--------------------+---------------+--------------------+------------------+ 770 *| All states | mode change | INACTIVE | | 771 *+--------------------+---------------+--------------------+------------------+ 772 * 773 * mode = AF_MODE_CONTINUOUS_VIDEO 774 *| state | trans. cause | new state | notes | 775 *+--------------------+---------------+--------------------+------------------+ 776 *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | 777 *| | new scan | | Lens now moving | 778 *+--------------------+---------------+--------------------+------------------+ 779 *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | 780 *| | | | Lens now locked | 781 *+--------------------+---------------+--------------------+------------------+ 782 *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | 783 *| | current scan | | Lens now locked | 784 *+--------------------+---------------+--------------------+------------------+ 785 *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | 786 *| | current scan | | Lens now locked | 787 *+--------------------+---------------+--------------------+------------------+ 788 *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | 789 *| | | | if focus is good | 790 *| | | | Lens now locked | 791 *+--------------------+---------------+--------------------+------------------+ 792 *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | 793 *| | | | if focus is bad | 794 *| | | | Lens now locked | 795 *+--------------------+---------------+--------------------+------------------+ 796 *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | 797 *| | | | position | 798 *| | | | Lens now locked | 799 *+--------------------+---------------+--------------------+------------------+ 800 *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 801 *| | new scan | | Lens now moving | 802 *+--------------------+---------------+--------------------+------------------+ 803 *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 804 *| | new scan | | Lens now moving | 805 *+--------------------+---------------+--------------------+------------------+ 806 *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | 807 *| | | | Lens now locked | 808 *+--------------------+---------------+--------------------+------------------+ 809 *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | 810 *| | | | Lens now locked | 811 *+--------------------+---------------+--------------------+------------------+ 812 *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | 813 *+--------------------+---------------+--------------------+------------------+ 814 *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 815 *+--------------------+---------------+--------------------+------------------+ 816 *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | 817 *+--------------------+---------------+--------------------+------------------+ 818 *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 819 *+--------------------+---------------+--------------------+------------------+ 820 * 821 * mode = AF_MODE_CONTINUOUS_PICTURE 822 *| state | trans. cause | new state | notes | 823 *+--------------------+---------------+--------------------+------------------+ 824 *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | 825 *| | new scan | | Lens now moving | 826 *+--------------------+---------------+--------------------+------------------+ 827 *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | 828 *| | | | Lens now locked | 829 *+--------------------+---------------+--------------------+------------------+ 830 *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | 831 *| | current scan | | Lens now locked | 832 *+--------------------+---------------+--------------------+------------------+ 833 *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | 834 *| | current scan | | Lens now locked | 835 *+--------------------+---------------+--------------------+------------------+ 836 *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual trans. | 837 *| | | | once focus good | 838 *| | | | Lens now locked | 839 *+--------------------+---------------+--------------------+------------------+ 840 *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual trans. | 841 *| | | | if cannot focus | 842 *| | | | Lens now locked | 843 *+--------------------+---------------+--------------------+------------------+ 844 *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | 845 *| | | | position | 846 *| | | | Lens now locked | 847 *+--------------------+---------------+--------------------+------------------+ 848 *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 849 *| | new scan | | Lens now moving | 850 *+--------------------+---------------+--------------------+------------------+ 851 *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | 852 *| | new scan | | Lens now moving | 853 *+--------------------+---------------+--------------------+------------------+ 854 *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | 855 *| | | | Lens now locked | 856 *+--------------------+---------------+--------------------+------------------+ 857 *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | 858 *| | | | Lens now locked | 859 *+--------------------+---------------+--------------------+------------------+ 860 *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | 861 *+--------------------+---------------+--------------------+------------------+ 862 *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 863 *+--------------------+---------------+--------------------+------------------+ 864 *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | 865 *+--------------------+---------------+--------------------+------------------+ 866 *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | 867 *+--------------------+---------------+--------------------+------------------+ 868 * 869 * S4.6. AE and AWB state machines 870 * 871 * The AE and AWB state machines are mostly identical. AE has additional 872 * FLASH_REQUIRED and PRECAPTURE states. So rows below that refer to those two 873 * states should be ignored for the AWB state machine. 874 * 875 * when enabling AE/AWB or changing AE/AWB mode 876 *| state | trans. cause | new state | notes | 877 *+--------------------+---------------+--------------------+------------------+ 878 *| Any | mode change | INACTIVE | | 879 *+--------------------+---------------+--------------------+------------------+ 880 * 881 * mode = AE_MODE_OFF / AWB mode not AUTO 882 *| state | trans. cause | new state | notes | 883 *+--------------------+---------------+--------------------+------------------+ 884 *| INACTIVE | | INACTIVE | AE/AWB disabled | 885 *+--------------------+---------------+--------------------+------------------+ 886 * 887 * mode = AE_MODE_ON_* / AWB_MODE_AUTO 888 *| state | trans. cause | new state | notes | 889 *+--------------------+---------------+--------------------+------------------+ 890 *| INACTIVE | HAL initiates | SEARCHING | | 891 *| | AE/AWB scan | | | 892 *+--------------------+---------------+--------------------+------------------+ 893 *| INACTIVE | AE/AWB_LOCK | LOCKED | values locked | 894 *| | on | | | 895 *+--------------------+---------------+--------------------+------------------+ 896 *| SEARCHING | HAL finishes | CONVERGED | good values, not | 897 *| | AE/AWB scan | | changing | 898 *+--------------------+---------------+--------------------+------------------+ 899 *| SEARCHING | HAL finishes | FLASH_REQUIRED | converged but too| 900 *| | AE scan | | dark w/o flash | 901 *+--------------------+---------------+--------------------+------------------+ 902 *| SEARCHING | AE/AWB_LOCK | LOCKED | values locked | 903 *| | on | | | 904 *+--------------------+---------------+--------------------+------------------+ 905 *| CONVERGED | HAL initiates | SEARCHING | values locked | 906 *| | AE/AWB scan | | | 907 *+--------------------+---------------+--------------------+------------------+ 908 *| CONVERGED | AE/AWB_LOCK | LOCKED | values locked | 909 *| | on | | | 910 *+--------------------+---------------+--------------------+------------------+ 911 *| FLASH_REQUIRED | HAL initiates | SEARCHING | values locked | 912 *| | AE/AWB scan | | | 913 *+--------------------+---------------+--------------------+------------------+ 914 *| FLASH_REQUIRED | AE/AWB_LOCK | LOCKED | values locked | 915 *| | on | | | 916 *+--------------------+---------------+--------------------+------------------+ 917 *| LOCKED | AE/AWB_LOCK | SEARCHING | values not good | 918 *| | off | | after unlock | 919 *+--------------------+---------------+--------------------+------------------+ 920 *| LOCKED | AE/AWB_LOCK | CONVERGED | values good | 921 *| | off | | after unlock | 922 *+--------------------+---------------+--------------------+------------------+ 923 *| LOCKED | AE_LOCK | FLASH_REQUIRED | exposure good, | 924 *| | off | | but too dark | 925 *+--------------------+---------------+--------------------+------------------+ 926 *| All AE states | PRECAPTURE_ | PRECAPTURE | Start precapture | 927 *| | START | | sequence | 928 *+--------------------+---------------+--------------------+------------------+ 929 *| PRECAPTURE | Sequence done.| CONVERGED | Ready for high- | 930 *| | AE_LOCK off | | quality capture | 931 *+--------------------+---------------+--------------------+------------------+ 932 *| PRECAPTURE | Sequence done.| LOCKED | Ready for high- | 933 *| | AE_LOCK on | | quality capture | 934 *+--------------------+---------------+--------------------+------------------+ 935 * 936 */ 937 938 /** 939 * S5. Cropping: 940 * 941 * Cropping of the full pixel array (for digital zoom and other use cases where 942 * a smaller FOV is desirable) is communicated through the 943 * ANDROID_SCALER_CROP_REGION setting. This is a per-request setting, and can 944 * change on a per-request basis, which is critical for implementing smooth 945 * digital zoom. 946 * 947 * The region is defined as a rectangle (x, y, width, height), with (x, y) 948 * describing the top-left corner of the rectangle. The rectangle is defined on 949 * the coordinate system of the sensor active pixel array, with (0,0) being the 950 * top-left pixel of the active pixel array. Therefore, the width and height 951 * cannot be larger than the dimensions reported in the 952 * ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY static info field. The minimum allowed 953 * width and height are reported by the HAL through the 954 * ANDROID_SCALER_MAX_DIGITAL_ZOOM static info field, which describes the 955 * maximum supported zoom factor. Therefore, the minimum crop region width and 956 * height are: 957 * 958 * {width, height} = 959 * { floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[0] / 960 * ANDROID_SCALER_MAX_DIGITAL_ZOOM), 961 * floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[1] / 962 * ANDROID_SCALER_MAX_DIGITAL_ZOOM) } 963 * 964 * If the crop region needs to fulfill specific requirements (for example, it 965 * needs to start on even coordinates, and its width/height needs to be even), 966 * the HAL must do the necessary rounding and write out the final crop region 967 * used in the output result metadata. Similarly, if the HAL implements video 968 * stabilization, it must adjust the result crop region to describe the region 969 * actually included in the output after video stabilization is applied. In 970 * general, a camera-using application must be able to determine the field of 971 * view it is receiving based on the crop region, the dimensions of the image 972 * sensor, and the lens focal length. 973 * 974 * It is assumed that the cropping is applied after raw to other color space 975 * conversion. Raw streams (RAW16 and RAW_OPAQUE) don't have this conversion stage, 976 * and are not croppable. Therefore, the crop region must be ignored by the HAL 977 * for raw streams. 978 * 979 * Since the crop region applies to all non-raw streams, which may have different aspect 980 * ratios than the crop region, the exact sensor region used for each stream may 981 * be smaller than the crop region. Specifically, each stream should maintain 982 * square pixels and its aspect ratio by minimally further cropping the defined 983 * crop region. If the stream's aspect ratio is wider than the crop region, the 984 * stream should be further cropped vertically, and if the stream's aspect ratio 985 * is narrower than the crop region, the stream should be further cropped 986 * horizontally. 987 * 988 * In all cases, the stream crop must be centered within the full crop region, 989 * and each stream is only either cropped horizontally or vertical relative to 990 * the full crop region, never both. 991 * 992 * For example, if two streams are defined, a 640x480 stream (4:3 aspect), and a 993 * 1280x720 stream (16:9 aspect), below demonstrates the expected output regions 994 * for each stream for a few sample crop regions, on a hypothetical 3 MP (2000 x 995 * 1500 pixel array) sensor. 996 * 997 * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) 998 * 999 * 640x480 stream crop: (500, 375, 1000, 750) (equal to crop region) 1000 * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) 1001 * 1002 * 0 1000 2000 1003 * +---------+---------+---------+----------+ 1004 * | Active pixel array | 1005 * | | 1006 * | | 1007 * + +-------------------+ + 375 1008 * | | | | 1009 * | O===================O | 1010 * | I 1280x720 stream I | 1011 * + I I + 750 1012 * | I I | 1013 * | O===================O | 1014 * | | | | 1015 * + +-------------------+ + 1125 1016 * | Crop region, 640x480 stream | 1017 * | | 1018 * | | 1019 * +---------+---------+---------+----------+ 1500 1020 * 1021 * Crop region: (500, 375, 1333, 750) (16:9 aspect ratio) 1022 * 1023 * 640x480 stream crop: (666, 375, 1000, 750) (marked with =) 1024 * 1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region) 1025 * 1026 * 0 1000 2000 1027 * +---------+---------+---------+----------+ 1028 * | Active pixel array | 1029 * | | 1030 * | | 1031 * + +---O==================O---+ + 375 1032 * | | I 640x480 stream I | | 1033 * | | I I | | 1034 * | | I I | | 1035 * + | I I | + 750 1036 * | | I I | | 1037 * | | I I | | 1038 * | | I I | | 1039 * + +---O==================O---+ + 1125 1040 * | Crop region, 1280x720 stream | 1041 * | | 1042 * | | 1043 * +---------+---------+---------+----------+ 1500 1044 * 1045 * Crop region: (500, 375, 750, 750) (1:1 aspect ratio) 1046 * 1047 * 640x480 stream crop: (500, 469, 750, 562) (marked with =) 1048 * 1280x720 stream crop: (500, 543, 750, 414) (marged with #) 1049 * 1050 * 0 1000 2000 1051 * +---------+---------+---------+----------+ 1052 * | Active pixel array | 1053 * | | 1054 * | | 1055 * + +--------------+ + 375 1056 * | O==============O | 1057 * | ################ | 1058 * | # # | 1059 * + # # + 750 1060 * | # # | 1061 * | ################ 1280x720 | 1062 * | O==============O 640x480 | 1063 * + +--------------+ + 1125 1064 * | Crop region | 1065 * | | 1066 * | | 1067 * +---------+---------+---------+----------+ 1500 1068 * 1069 * And a final example, a 1024x1024 square aspect ratio stream instead of the 1070 * 480p stream: 1071 * 1072 * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) 1073 * 1074 * 1024x1024 stream crop: (625, 375, 750, 750) (marked with #) 1075 * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) 1076 * 1077 * 0 1000 2000 1078 * +---------+---------+---------+----------+ 1079 * | Active pixel array | 1080 * | | 1081 * | 1024x1024 stream | 1082 * + +--###############--+ + 375 1083 * | | # # | | 1084 * | O===================O | 1085 * | I 1280x720 stream I | 1086 * + I I + 750 1087 * | I I | 1088 * | O===================O | 1089 * | | # # | | 1090 * + +--###############--+ + 1125 1091 * | Crop region | 1092 * | | 1093 * | | 1094 * +---------+---------+---------+----------+ 1500 1095 * 1096 */ 1097 1098 /** 1099 * S6. Error management: 1100 * 1101 * Camera HAL device ops functions that have a return value will all return 1102 * -ENODEV / NULL in case of a serious error. This means the device cannot 1103 * continue operation, and must be closed by the framework. Once this error is 1104 * returned by some method, or if notify() is called with ERROR_DEVICE, only 1105 * the close() method can be called successfully. All other methods will return 1106 * -ENODEV / NULL. 1107 * 1108 * If a device op is called in the wrong sequence, for example if the framework 1109 * calls configure_streams() is called before initialize(), the device must 1110 * return -ENOSYS from the call, and do nothing. 1111 * 1112 * Transient errors in image capture must be reported through notify() as follows: 1113 * 1114 * - The failure of an entire capture to occur must be reported by the HAL by 1115 * calling notify() with ERROR_REQUEST. Individual errors for the result 1116 * metadata or the output buffers must not be reported in this case. 1117 * 1118 * - If the metadata for a capture cannot be produced, but some image buffers 1119 * were filled, the HAL must call notify() with ERROR_RESULT. 1120 * 1121 * - If an output image buffer could not be filled, but either the metadata was 1122 * produced or some other buffers were filled, the HAL must call notify() with 1123 * ERROR_BUFFER for each failed buffer. 1124 * 1125 * In each of these transient failure cases, the HAL must still call 1126 * process_capture_result, with valid output and input (if an input buffer was 1127 * submitted) buffer_handle_t. If the result metadata could not be produced, it 1128 * should be NULL. If some buffers could not be filled, they must be returned with 1129 * process_capture_result in the error state, their release fences must be set to 1130 * the acquire fences passed by the framework, or -1 if they have been waited on by 1131 * the HAL already. 1132 * 1133 * Invalid input arguments result in -EINVAL from the appropriate methods. In 1134 * that case, the framework must act as if that call had never been made. 1135 * 1136 */ 1137 1138 /** 1139 * S7. Key Performance Indicator (KPI) glossary: 1140 * 1141 * This includes some critical definitions that are used by KPI metrics. 1142 * 1143 * Pipeline Latency: 1144 * For a given capture request, the duration from the framework calling 1145 * process_capture_request to the HAL sending capture result and all buffers 1146 * back by process_capture_result call. To make the Pipeline Latency measure 1147 * independent of frame rate, it is measured by frame count. 1148 * 1149 * For example, when frame rate is 30 (fps), the frame duration (time interval 1150 * between adjacent frame capture time) is 33 (ms). 1151 * If it takes 5 frames for framework to get the result and buffers back for 1152 * a given request, then the Pipeline Latency is 5 (frames), instead of 1153 * 5 x 33 = 165 (ms). 1154 * 1155 * The Pipeline Latency is determined by android.request.pipelineDepth and 1156 * android.request.pipelineMaxDepth, see their definitions for more details. 1157 * 1158 */ 1159 1160 /** 1161 * S8. Sample Use Cases: 1162 * 1163 * This includes some typical use case examples the camera HAL may support. 1164 * 1165 * S8.1 Zero Shutter Lag (ZSL) with CAMERA3_STREAM_BIDIRECTIONAL stream. 1166 * 1167 * For this use case, the bidirectional stream will be used by the framework as follows: 1168 * 1169 * 1. The framework includes a buffer from this stream as output buffer in a 1170 * request as normal. 1171 * 1172 * 2. Once the HAL device returns a filled output buffer to the framework, 1173 * the framework may do one of two things with the filled buffer: 1174 * 1175 * 2. a. The framework uses the filled data, and returns the now-used buffer 1176 * to the stream queue for reuse. This behavior exactly matches the 1177 * OUTPUT type of stream. 1178 * 1179 * 2. b. The framework wants to reprocess the filled data, and uses the 1180 * buffer as an input buffer for a request. Once the HAL device has 1181 * used the reprocessing buffer, it then returns it to the 1182 * framework. The framework then returns the now-used buffer to the 1183 * stream queue for reuse. 1184 * 1185 * 3. The HAL device will be given the buffer again as an output buffer for 1186 * a request at some future point. 1187 * 1188 * For ZSL use case, the pixel format for bidirectional stream will be 1189 * HAL_PIXEL_FORMAT_RAW_OPAQUE or HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED if it 1190 * is listed in android.scaler.availableInputOutputFormatsMap. When 1191 * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, the gralloc 1192 * usage flags for the consumer endpoint will be set to GRALLOC_USAGE_HW_CAMERA_ZSL. 1193 * A configuration stream list that has BIDIRECTIONAL stream used as input, will 1194 * usually also have a distinct OUTPUT stream to get the reprocessing data. For example, 1195 * for the ZSL use case, the stream list might be configured with the following: 1196 * 1197 * - A HAL_PIXEL_FORMAT_RAW_OPAQUE bidirectional stream is used 1198 * as input. 1199 * - And a HAL_PIXEL_FORMAT_BLOB (JPEG) output stream. 1200 * 1201 * S8.2 ZSL (OPAQUE) reprocessing with CAMERA3_STREAM_INPUT stream. 1202 * 1203 * CAMERA_DEVICE_API_VERSION_3_3: 1204 * When OPAQUE_REPROCESSING capability is supported by the camera device, the INPUT stream 1205 * can be used for application/framework implemented use case like Zero Shutter Lag (ZSL). 1206 * This kind of stream will be used by the framework as follows: 1207 * 1208 * 1. Application/framework configures an opaque (RAW or YUV based) format output stream that is 1209 * used to produce the ZSL output buffers. The stream pixel format will be 1210 * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. 1211 * 1212 * 2. Application/framework configures an opaque format input stream that is used to 1213 * send the reprocessing ZSL buffers to the HAL. The stream pixel format will 1214 * also be HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. 1215 * 1216 * 3. Application/framework configures a YUV/JPEG output stream that is used to receive the 1217 * reprocessed data. The stream pixel format will be YCbCr_420/HAL_PIXEL_FORMAT_BLOB. 1218 * 1219 * 4. Application/framework picks a ZSL buffer from the ZSL output stream when a ZSL capture is 1220 * issued by the application, and sends the data back as an input buffer in a 1221 * reprocessing request, then sends to the HAL for reprocessing. 1222 * 1223 * 5. The HAL sends back the output YUV/JPEG result to framework. 1224 * 1225 * The HAL can select the actual opaque buffer format and configure the ISP pipeline 1226 * appropriately based on the HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED format and 1227 * the gralloc usage flag GRALLOC_USAGE_HW_CAMERA_ZSL. 1228 1229 * S8.3 YUV reprocessing with CAMERA3_STREAM_INPUT stream. 1230 * 1231 * When YUV reprocessing is supported by the HAL, the INPUT stream 1232 * can be used for the YUV reprocessing use cases like lucky-shot and image fusion. 1233 * This kind of stream will be used by the framework as follows: 1234 * 1235 * 1. Application/framework configures an YCbCr_420 format output stream that is 1236 * used to produce the output buffers. 1237 * 1238 * 2. Application/framework configures an YCbCr_420 format input stream that is used to 1239 * send the reprocessing YUV buffers to the HAL. 1240 * 1241 * 3. Application/framework configures a YUV/JPEG output stream that is used to receive the 1242 * reprocessed data. The stream pixel format will be YCbCr_420/HAL_PIXEL_FORMAT_BLOB. 1243 * 1244 * 4. Application/framework processes the output buffers (could be as simple as picking 1245 * an output buffer directly) from the output stream when a capture is issued, and sends 1246 * the data back as an input buffer in a reprocessing request, then sends to the HAL 1247 * for reprocessing. 1248 * 1249 * 5. The HAL sends back the output YUV/JPEG result to framework. 1250 * 1251 */ 1252 1253 /** 1254 * S9. Notes on Controls and Metadata 1255 * 1256 * This section contains notes about the interpretation and usage of various metadata tags. 1257 * 1258 * S9.1 HIGH_QUALITY and FAST modes. 1259 * 1260 * Many camera post-processing blocks may be listed as having HIGH_QUALITY, 1261 * FAST, and OFF operating modes. These blocks will typically also have an 1262 * 'available modes' tag representing which of these operating modes are 1263 * available on a given device. The general policy regarding implementing 1264 * these modes is as follows: 1265 * 1266 * 1. Operating mode controls of hardware blocks that cannot be disabled 1267 * must not list OFF in their corresponding 'available modes' tags. 1268 * 1269 * 2. OFF will always be included in their corresponding 'available modes' 1270 * tag if it is possible to disable that hardware block. 1271 * 1272 * 3. FAST must always be included in the 'available modes' tags for all 1273 * post-processing blocks supported on the device. If a post-processing 1274 * block also has a slower and higher quality operating mode that does 1275 * not meet the framerate requirements for FAST mode, HIGH_QUALITY should 1276 * be included in the 'available modes' tag to represent this operating 1277 * mode. 1278 */ 1279 1280 /** 1281 * S10. Reprocessing flow and controls 1282 * 1283 * This section describes the OPAQUE and YUV reprocessing flow and controls. OPAQUE reprocessing 1284 * uses an opaque format that is not directly application-visible, and the application can 1285 * only select some of the output buffers and send back to HAL for reprocessing, while YUV 1286 * reprocessing gives the application opportunity to process the buffers before reprocessing. 1287 * 1288 * S8 gives the stream configurations for the typical reprocessing uses cases, 1289 * this section specifies the buffer flow and controls in more details. 1290 * 1291 * S10.1 OPAQUE (typically for ZSL use case) reprocessing flow and controls 1292 * 1293 * For OPAQUE reprocessing (e.g. ZSL) use case, after the application creates the specific 1294 * output and input streams, runtime buffer flow and controls are specified as below: 1295 * 1296 * 1. Application starts output streaming by sending repeating requests for output 1297 * opaque buffers and preview. The buffers are held by an application 1298 * maintained circular buffer. The requests are based on CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG 1299 * capture template, which should have all necessary settings that guarantee output 1300 * frame rate is not slowed down relative to sensor output frame rate. 1301 * 1302 * 2. When a capture is issued, the application selects one output buffer based 1303 * on application buffer selection logic, e.g. good AE and AF statistics etc. 1304 * Application then creates an reprocess request based on the capture result associated 1305 * with this selected buffer. The selected output buffer is now added to this reprocess 1306 * request as an input buffer, the output buffer of this reprocess request should be 1307 * either JPEG output buffer or YUV output buffer, or both, depending on the application 1308 * choice. 1309 * 1310 * 3. Application then alters the reprocess settings to get best image quality. The HAL must 1311 * support and only support below controls if the HAL support OPAQUE_REPROCESSING capability: 1312 * - android.jpeg.* (if JPEG buffer is included as one of the output) 1313 * - android.noiseReduction.mode (change to HIGH_QUALITY if it is supported) 1314 * - android.edge.mode (change to HIGH_QUALITY if it is supported) 1315 * All other controls must be ignored by the HAL. 1316 * 4. HAL processed the input buffer and return the output buffers in the capture results 1317 * as normal. 1318 * 1319 * S10.2 YUV reprocessing flow and controls 1320 * 1321 * The YUV reprocessing buffer flow is similar as OPAQUE reprocessing, with below difference: 1322 * 1323 * 1. Application may want to have finer granularity control of the intermediate YUV images 1324 * (before reprocessing). For example, application may choose 1325 * - android.noiseReduction.mode == MINIMAL 1326 * to make sure the no YUV domain noise reduction has applied to the output YUV buffers, 1327 * then it can do its own advanced noise reduction on them. For OPAQUE reprocessing case, this 1328 * doesn't matter, as long as the final reprocessed image has the best quality. 1329 * 2. Application may modify the YUV output buffer data. For example, for image fusion use 1330 * case, where multiple output images are merged together to improve the signal-to-noise 1331 * ratio (SNR). The input buffer may be generated from multiple buffers by the application. 1332 * To avoid excessive amount of noise reduction and insufficient amount of edge enhancement 1333 * being applied to the input buffer, the application can hint the HAL how much effective 1334 * exposure time improvement has been done by the application, then the HAL can adjust the 1335 * noise reduction and edge enhancement parameters to get best reprocessed image quality. 1336 * Below tag can be used for this purpose: 1337 * - android.reprocess.effectiveExposureFactor 1338 * The value would be exposure time increase factor applied to the original output image, 1339 * for example, if there are N image merged, the exposure time increase factor would be up 1340 * to sqrt(N). See this tag spec for more details. 1341 * 1342 * S10.3 Reprocessing pipeline characteristics 1343 * 1344 * Reprocessing pipeline has below different characteristics comparing with normal output 1345 * pipeline: 1346 * 1347 * 1. The reprocessing result can be returned ahead of the pending normal output results. But 1348 * the FIFO ordering must be maintained for all reprocessing results. For example, there are 1349 * below requests (A stands for output requests, B stands for reprocessing requests) 1350 * being processed by the HAL: 1351 * A1, A2, A3, A4, B1, A5, B2, A6... 1352 * result of B1 can be returned before A1-A4, but result of B2 must be returned after B1. 1353 * 2. Single input rule: For a given reprocessing request, all output buffers must be from the 1354 * input buffer, rather than sensor output. For example, if a reprocess request include both 1355 * JPEG and preview buffers, all output buffers must be produced from the input buffer 1356 * included by the reprocessing request, rather than sensor. The HAL must not output preview 1357 * buffers from sensor, while output JPEG buffer from the input buffer. 1358 * 3. Input buffer will be from camera output directly (ZSL case) or indirectly(image fusion 1359 * case). For the case where buffer is modified, the size will remain same. The HAL can 1360 * notify CAMERA3_MSG_ERROR_REQUEST if buffer from unknown source is sent. 1361 * 4. Result as reprocessing request: The HAL can expect that a reprocessing request is a copy 1362 * of one of the output results with minor allowed setting changes. The HAL can notify 1363 * CAMERA3_MSG_ERROR_REQUEST if a request from unknown source is issued. 1364 * 5. Output buffers may not be used as inputs across the configure stream boundary, This is 1365 * because an opaque stream like the ZSL output stream may have different actual image size 1366 * inside of the ZSL buffer to save power and bandwidth for smaller resolution JPEG capture. 1367 * The HAL may notify CAMERA3_MSG_ERROR_REQUEST if this case occurs. 1368 * 6. HAL Reprocess requests error reporting during flush should follow the same rule specified 1369 * by flush() method. 1370 * 1371 */ 1372 1373 __BEGIN_DECLS 1374 1375 struct camera3_device; 1376 1377 /********************************************************************** 1378 * 1379 * Camera3 stream and stream buffer definitions. 1380 * 1381 * These structs and enums define the handles and contents of the input and 1382 * output streams connecting the HAL to various framework and application buffer 1383 * consumers. Each stream is backed by a gralloc buffer queue. 1384 * 1385 */ 1386 1387 /** 1388 * camera3_stream_type_t: 1389 * 1390 * The type of the camera stream, which defines whether the camera HAL device is 1391 * the producer or the consumer for that stream, and how the buffers of the 1392 * stream relate to the other streams. 1393 */ 1394 typedef enum camera3_stream_type { 1395 /** 1396 * This stream is an output stream; the camera HAL device will be 1397 * responsible for filling buffers from this stream with newly captured or 1398 * reprocessed image data. 1399 */ 1400 CAMERA3_STREAM_OUTPUT = 0, 1401 1402 /** 1403 * This stream is an input stream; the camera HAL device will be responsible 1404 * for reading buffers from this stream and sending them through the camera 1405 * processing pipeline, as if the buffer was a newly captured image from the 1406 * imager. 1407 * 1408 * The pixel format for input stream can be any format reported by 1409 * android.scaler.availableInputOutputFormatsMap. The pixel format of the 1410 * output stream that is used to produce the reprocessing data may be any 1411 * format reported by android.scaler.availableStreamConfigurations. The 1412 * supported input/output stream combinations depends the camera device 1413 * capabilities, see android.scaler.availableInputOutputFormatsMap for 1414 * stream map details. 1415 * 1416 * This kind of stream is generally used to reprocess data into higher 1417 * quality images (that otherwise would cause a frame rate performance 1418 * loss), or to do off-line reprocessing. 1419 * 1420 * CAMERA_DEVICE_API_VERSION_3_3: 1421 * The typical use cases are OPAQUE (typically ZSL) and YUV reprocessing, 1422 * see S8.2, S8.3 and S10 for more details. 1423 */ 1424 CAMERA3_STREAM_INPUT = 1, 1425 1426 /** 1427 * This stream can be used for input and output. Typically, the stream is 1428 * used as an output stream, but occasionally one already-filled buffer may 1429 * be sent back to the HAL device for reprocessing. 1430 * 1431 * This kind of stream is meant generally for Zero Shutter Lag (ZSL) 1432 * features, where copying the captured image from the output buffer to the 1433 * reprocessing input buffer would be expensive. See S8.1 for more details. 1434 * 1435 * Note that the HAL will always be reprocessing data it produced. 1436 * 1437 */ 1438 CAMERA3_STREAM_BIDIRECTIONAL = 2, 1439 1440 /** 1441 * Total number of framework-defined stream types 1442 */ 1443 CAMERA3_NUM_STREAM_TYPES 1444 1445 } camera3_stream_type_t; 1446 1447 /** 1448 * camera3_stream_rotation_t: 1449 * 1450 * The required counterclockwise rotation of camera stream. 1451 */ 1452 typedef enum camera3_stream_rotation { 1453 /* No rotation */ 1454 CAMERA3_STREAM_ROTATION_0 = 0, 1455 1456 /* Rotate by 90 degree counterclockwise */ 1457 CAMERA3_STREAM_ROTATION_90 = 1, 1458 1459 /* Rotate by 180 degree counterclockwise */ 1460 CAMERA3_STREAM_ROTATION_180 = 2, 1461 1462 /* Rotate by 270 degree counterclockwise */ 1463 CAMERA3_STREAM_ROTATION_270 = 3 1464 } camera3_stream_rotation_t; 1465 1466 /** 1467 * camera3_stream_configuration_mode_t: 1468 * 1469 * This defines the general operation mode for the HAL (for a given stream configuration), where 1470 * modes besides NORMAL have different semantics, and usually limit the generality of the API in 1471 * exchange for higher performance in some particular area. 1472 */ 1473 typedef enum camera3_stream_configuration_mode { 1474 /** 1475 * Normal stream configuration operation mode. This is the default camera operation mode, 1476 * where all semantics of HAL APIs and metadata controls apply. 1477 */ 1478 CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0, 1479 1480 /** 1481 * Special constrained high speed operation mode for devices that can not support high 1482 * speed output in NORMAL mode. All streams in this configuration are operating at high speed 1483 * mode and have different characteristics and limitations to achieve high speed output. 1484 * The NORMAL mode can still be used for high speed output if the HAL can support high speed 1485 * output while satisfying all the semantics of HAL APIs and metadata controls. It is 1486 * recommended for the HAL to support high speed output in NORMAL mode (by advertising the high 1487 * speed FPS ranges in android.control.aeAvailableTargetFpsRanges) if possible. 1488 * 1489 * This mode has below limitations/requirements: 1490 * 1491 * 1. The HAL must support up to 2 streams with sizes reported by 1492 * android.control.availableHighSpeedVideoConfigurations. 1493 * 2. In this mode, the HAL is expected to output up to 120fps or higher. This mode must 1494 * support the targeted FPS range and size configurations reported by 1495 * android.control.availableHighSpeedVideoConfigurations. 1496 * 3. The HAL must support HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED output stream format. 1497 * 4. To achieve efficient high speed streaming, the HAL may have to aggregate 1498 * multiple frames together and send to camera device for processing where the request 1499 * controls are same for all the frames in this batch (batch mode). The HAL must support 1500 * max batch size and the max batch size requirements defined by 1501 * android.control.availableHighSpeedVideoConfigurations. 1502 * 5. In this mode, the HAL must override aeMode, awbMode, and afMode to ON, ON, and 1503 * CONTINUOUS_VIDEO, respectively. All post-processing block mode controls must be 1504 * overridden to be FAST. Therefore, no manual control of capture and post-processing 1505 * parameters is possible. All other controls operate the same as when 1506 * android.control.mode == AUTO. This means that all other android.control.* fields 1507 * must continue to work, such as 1508 * 1509 * android.control.aeTargetFpsRange 1510 * android.control.aeExposureCompensation 1511 * android.control.aeLock 1512 * android.control.awbLock 1513 * android.control.effectMode 1514 * android.control.aeRegions 1515 * android.control.afRegions 1516 * android.control.awbRegions 1517 * android.control.afTrigger 1518 * android.control.aePrecaptureTrigger 1519 * 1520 * Outside of android.control.*, the following controls must work: 1521 * 1522 * android.flash.mode (TORCH mode only, automatic flash for still capture will not work 1523 * since aeMode is ON) 1524 * android.lens.opticalStabilizationMode (if it is supported) 1525 * android.scaler.cropRegion 1526 * android.statistics.faceDetectMode (if it is supported) 1527 * 6. To reduce the amount of data passed across process boundaries at 1528 * high frame rate, within one batch, camera framework only propagates 1529 * the last shutter notify and the last capture results (including partial 1530 * results and final result) to the app. The shutter notifies and capture 1531 * results for the other requests in the batch are derived by 1532 * the camera framework. As a result, the HAL can return empty metadata 1533 * except for the last result in the batch. 1534 * 1535 * For more details about high speed stream requirements, see 1536 * android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO 1537 * capability defined in android.request.availableCapabilities. 1538 * 1539 * This mode only needs to be supported by HALs that include CONSTRAINED_HIGH_SPEED_VIDEO in 1540 * the android.request.availableCapabilities static metadata. 1541 */ 1542 CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE = 1, 1543 1544 /** 1545 * First value for vendor-defined stream configuration modes. 1546 */ 1547 CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000 1548 } camera3_stream_configuration_mode_t; 1549 1550 /** 1551 * camera3_stream_t: 1552 * 1553 * A handle to a single camera input or output stream. A stream is defined by 1554 * the framework by its buffer resolution and format, and additionally by the 1555 * HAL with the gralloc usage flags and the maximum in-flight buffer count. 1556 * 1557 * The stream structures are owned by the framework, but pointers to a 1558 * camera3_stream passed into the HAL by configure_streams() are valid until the 1559 * end of the first subsequent configure_streams() call that _does not_ include 1560 * that camera3_stream as an argument, or until the end of the close() call. 1561 * 1562 * All camera3_stream framework-controlled members are immutable once the 1563 * camera3_stream is passed into configure_streams(). The HAL may only change 1564 * the HAL-controlled parameters during a configure_streams() call, except for 1565 * the contents of the private pointer. 1566 * 1567 * If a configure_streams() call returns a non-fatal error, all active streams 1568 * remain valid as if configure_streams() had not been called. 1569 * 1570 * The endpoint of the stream is not visible to the camera HAL device. 1571 * In DEVICE_API_VERSION_3_1, this was changed to share consumer usage flags 1572 * on streams where the camera is a producer (OUTPUT and BIDIRECTIONAL stream 1573 * types) see the usage field below. 1574 */ 1575 typedef struct camera3_stream { 1576 1577 /***** 1578 * Set by framework before configure_streams() 1579 */ 1580 1581 /** 1582 * The type of the stream, one of the camera3_stream_type_t values. 1583 */ 1584 int stream_type; 1585 1586 /** 1587 * The width in pixels of the buffers in this stream 1588 */ 1589 uint32_t width; 1590 1591 /** 1592 * The height in pixels of the buffers in this stream 1593 */ 1594 uint32_t height; 1595 1596 /** 1597 * The pixel format for the buffers in this stream. Format is a value from 1598 * the HAL_PIXEL_FORMAT_* list in system/core/include/system/graphics.h, or 1599 * from device-specific headers. 1600 * 1601 * If HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform 1602 * gralloc module will select a format based on the usage flags provided by 1603 * the camera device and the other endpoint of the stream. 1604 * 1605 * <= CAMERA_DEVICE_API_VERSION_3_1: 1606 * 1607 * The camera HAL device must inspect the buffers handed to it in the 1608 * subsequent register_stream_buffers() call to obtain the 1609 * implementation-specific format details, if necessary. 1610 * 1611 * >= CAMERA_DEVICE_API_VERSION_3_2: 1612 * 1613 * register_stream_buffers() won't be called by the framework, so the HAL 1614 * should configure the ISP and sensor pipeline based purely on the sizes, 1615 * usage flags, and formats for the configured streams. 1616 */ 1617 int format; 1618 1619 /***** 1620 * Set by HAL during configure_streams(). 1621 */ 1622 1623 /** 1624 * The gralloc usage flags for this stream, as needed by the HAL. The usage 1625 * flags are defined in gralloc.h (GRALLOC_USAGE_*), or in device-specific 1626 * headers. 1627 * 1628 * For output streams, these are the HAL's producer usage flags. For input 1629 * streams, these are the HAL's consumer usage flags. The usage flags from 1630 * the producer and the consumer will be combined together and then passed 1631 * to the platform gralloc HAL module for allocating the gralloc buffers for 1632 * each stream. 1633 * 1634 * Version information: 1635 * 1636 * == CAMERA_DEVICE_API_VERSION_3_0: 1637 * 1638 * No initial value guaranteed when passed via configure_streams(). 1639 * HAL may not use this field as input, and must write over this field 1640 * with its usage flags. 1641 * 1642 * >= CAMERA_DEVICE_API_VERSION_3_1: 1643 * 1644 * For stream_type OUTPUT and BIDIRECTIONAL, when passed via 1645 * configure_streams(), the initial value of this is the consumer's 1646 * usage flags. The HAL may use these consumer flags to decide stream 1647 * configuration. 1648 * For stream_type INPUT, when passed via configure_streams(), the initial 1649 * value of this is 0. 1650 * For all streams passed via configure_streams(), the HAL must write 1651 * over this field with its usage flags. 1652 * 1653 * From Android O, the usage flag for an output stream may be bitwise 1654 * combination of usage flags for multiple consumers, for the purpose of 1655 * sharing one camera stream between those consumers. The HAL must fail 1656 * configure_streams call with -EINVAL if the combined flags cannot be 1657 * supported due to imcompatible buffer format, dataSpace, or other hardware 1658 * limitations. 1659 */ 1660 uint32_t usage; 1661 1662 /** 1663 * The maximum number of buffers the HAL device may need to have dequeued at 1664 * the same time. The HAL device may not have more buffers in-flight from 1665 * this stream than this value. 1666 */ 1667 uint32_t max_buffers; 1668 1669 /** 1670 * A handle to HAL-private information for the stream. Will not be inspected 1671 * by the framework code. 1672 */ 1673 void *priv; 1674 1675 /** 1676 * A field that describes the contents of the buffer. The format and buffer 1677 * dimensions define the memory layout and structure of the stream buffers, 1678 * while dataSpace defines the meaning of the data within the buffer. 1679 * 1680 * For most formats, dataSpace defines the color space of the image data. 1681 * In addition, for some formats, dataSpace indicates whether image- or 1682 * depth-based data is requested. See system/core/include/system/graphics.h 1683 * for details of formats and valid dataSpace values for each format. 1684 * 1685 * Version information: 1686 * 1687 * < CAMERA_DEVICE_API_VERSION_3_3: 1688 * 1689 * Not defined and should not be accessed. dataSpace should be assumed to 1690 * be HAL_DATASPACE_UNKNOWN, and the appropriate color space, etc, should 1691 * be determined from the usage flags and the format. 1692 * 1693 * = CAMERA_DEVICE_API_VERSION_3_3: 1694 * 1695 * Always set by the camera service. HAL must use this dataSpace to 1696 * configure the stream to the correct colorspace, or to select between 1697 * color and depth outputs if supported. The dataspace values are the 1698 * legacy definitions in graphics.h 1699 * 1700 * >= CAMERA_DEVICE_API_VERSION_3_4: 1701 * 1702 * Always set by the camera service. HAL must use this dataSpace to 1703 * configure the stream to the correct colorspace, or to select between 1704 * color and depth outputs if supported. The dataspace values are set 1705 * using the V0 dataspace definitions in graphics.h 1706 */ 1707 android_dataspace_t data_space; 1708 1709 /** 1710 * The required output rotation of the stream, one of 1711 * the camera3_stream_rotation_t values. This must be inspected by HAL along 1712 * with stream width and height. For example, if the rotation is 90 degree 1713 * and the stream width and height is 720 and 1280 respectively, camera service 1714 * will supply buffers of size 720x1280, and HAL should capture a 1280x720 image 1715 * and rotate the image by 90 degree counterclockwise. The rotation field is 1716 * no-op when the stream type is input. Camera HAL must ignore the rotation 1717 * field for an input stream. 1718 * 1719 * <= CAMERA_DEVICE_API_VERSION_3_2: 1720 * 1721 * Not defined and must not be accessed. HAL must not apply any rotation 1722 * on output images. 1723 * 1724 * >= CAMERA_DEVICE_API_VERSION_3_3: 1725 * 1726 * Always set by camera service. HAL must inspect this field during stream 1727 * configuration and returns -EINVAL if HAL cannot perform such rotation. 1728 * HAL must always support CAMERA3_STREAM_ROTATION_0, so a 1729 * configure_streams() call must not fail for unsupported rotation if 1730 * rotation field of all streams is CAMERA3_STREAM_ROTATION_0. 1731 * 1732 */ 1733 int rotation; 1734 1735 /** 1736 * The physical camera id this stream belongs to. 1737 * 1738 * <= CAMERA_DEVICE_API_VERISON_3_4: 1739 * 1740 * Not defined and must not be accessed. 1741 * 1742 * >= CAMERA_DEVICE_API_VERISON_3_5: 1743 * 1744 * Always set by camera service. If the camera device is not a logical 1745 * multi camera, or if the camera is a logical multi camera but the stream 1746 * is not a physical output stream, this field will point to a 0-length 1747 * string. 1748 * 1749 * A logical multi camera is a camera device backed by multiple physical 1750 * cameras that are also exposed to the application. And for a logical 1751 * multi camera, a physical output stream is an output stream specifically 1752 * requested on an underlying physical camera. 1753 * 1754 * For an input stream, this field is guaranteed to be a 0-length string. 1755 */ 1756 const char* physical_camera_id; 1757 1758 /* reserved for future use */ 1759 void *reserved[6]; 1760 1761 } camera3_stream_t; 1762 1763 /** 1764 * camera3_stream_configuration_t: 1765 * 1766 * A structure of stream definitions, used by configure_streams(). This 1767 * structure defines all the output streams and the reprocessing input 1768 * stream for the current camera use case. 1769 */ 1770 typedef struct camera3_stream_configuration { 1771 /** 1772 * The total number of streams requested by the framework. This includes 1773 * both input and output streams. The number of streams will be at least 1, 1774 * and there will be at least one output-capable stream. 1775 */ 1776 uint32_t num_streams; 1777 1778 /** 1779 * An array of camera stream pointers, defining the input/output 1780 * configuration for the camera HAL device. 1781 * 1782 * At most one input-capable stream may be defined (INPUT or BIDIRECTIONAL) 1783 * in a single configuration. 1784 * 1785 * At least one output-capable stream must be defined (OUTPUT or 1786 * BIDIRECTIONAL). 1787 */ 1788 camera3_stream_t **streams; 1789 1790 /** 1791 * >= CAMERA_DEVICE_API_VERSION_3_3: 1792 * 1793 * The operation mode of streams in this configuration, one of the value 1794 * defined in camera3_stream_configuration_mode_t. The HAL can use this 1795 * mode as an indicator to set the stream property (e.g., 1796 * camera3_stream->max_buffers) appropriately. For example, if the 1797 * configuration is 1798 * CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE, the HAL may 1799 * want to set aside more buffers for batch mode operation (see 1800 * android.control.availableHighSpeedVideoConfigurations for batch mode 1801 * definition). 1802 * 1803 */ 1804 uint32_t operation_mode; 1805 1806 /** 1807 * >= CAMERA_DEVICE_API_VERSION_3_5: 1808 * 1809 * The session metadata buffer contains the initial values of 1810 * ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. This field is optional 1811 * and camera clients can choose to ignore it, in which case it will 1812 * be set to NULL. If parameters are present, then Hal should examine 1813 * the parameter values and configure its internal camera pipeline 1814 * accordingly. 1815 */ 1816 const camera_metadata_t *session_parameters; 1817 } camera3_stream_configuration_t; 1818 1819 /** 1820 * camera3_buffer_status_t: 1821 * 1822 * The current status of a single stream buffer. 1823 */ 1824 typedef enum camera3_buffer_status { 1825 /** 1826 * The buffer is in a normal state, and can be used after waiting on its 1827 * sync fence. 1828 */ 1829 CAMERA3_BUFFER_STATUS_OK = 0, 1830 1831 /** 1832 * The buffer does not contain valid data, and the data in it should not be 1833 * used. The sync fence must still be waited on before reusing the buffer. 1834 */ 1835 CAMERA3_BUFFER_STATUS_ERROR = 1 1836 1837 } camera3_buffer_status_t; 1838 1839 /** 1840 * camera3_stream_buffer_t: 1841 * 1842 * A single buffer from a camera3 stream. It includes a handle to its parent 1843 * stream, the handle to the gralloc buffer itself, and sync fences 1844 * 1845 * The buffer does not specify whether it is to be used for input or output; 1846 * that is determined by its parent stream type and how the buffer is passed to 1847 * the HAL device. 1848 */ 1849 typedef struct camera3_stream_buffer { 1850 /** 1851 * The handle of the stream this buffer is associated with 1852 */ 1853 camera3_stream_t *stream; 1854 1855 /** 1856 * The native handle to the buffer 1857 */ 1858 buffer_handle_t *buffer; 1859 1860 /** 1861 * Current state of the buffer, one of the camera3_buffer_status_t 1862 * values. The framework will not pass buffers to the HAL that are in an 1863 * error state. In case a buffer could not be filled by the HAL, it must 1864 * have its status set to CAMERA3_BUFFER_STATUS_ERROR when returned to the 1865 * framework with process_capture_result(). 1866 */ 1867 int status; 1868 1869 /** 1870 * The acquire sync fence for this buffer. The HAL must wait on this fence 1871 * fd before attempting to read from or write to this buffer. 1872 * 1873 * The framework may be set to -1 to indicate that no waiting is necessary 1874 * for this buffer. 1875 * 1876 * When the HAL returns an output buffer to the framework with 1877 * process_capture_result(), the acquire_fence must be set to -1. If the HAL 1878 * never waits on the acquire_fence due to an error in filling a buffer, 1879 * when calling process_capture_result() the HAL must set the release_fence 1880 * of the buffer to be the acquire_fence passed to it by the framework. This 1881 * will allow the framework to wait on the fence before reusing the buffer. 1882 * 1883 * For input buffers, the HAL must not change the acquire_fence field during 1884 * the process_capture_request() call. 1885 * 1886 * >= CAMERA_DEVICE_API_VERSION_3_2: 1887 * 1888 * When the HAL returns an input buffer to the framework with 1889 * process_capture_result(), the acquire_fence must be set to -1. If the HAL 1890 * never waits on input buffer acquire fence due to an error, the sync 1891 * fences should be handled similarly to the way they are handled for output 1892 * buffers. 1893 */ 1894 int acquire_fence; 1895 1896 /** 1897 * The release sync fence for this buffer. The HAL must set this fence when 1898 * returning buffers to the framework, or write -1 to indicate that no 1899 * waiting is required for this buffer. 1900 * 1901 * For the output buffers, the fences must be set in the output_buffers 1902 * array passed to process_capture_result(). 1903 * 1904 * <= CAMERA_DEVICE_API_VERSION_3_1: 1905 * 1906 * For the input buffer, the release fence must be set by the 1907 * process_capture_request() call. 1908 * 1909 * >= CAMERA_DEVICE_API_VERSION_3_2: 1910 * 1911 * For the input buffer, the fences must be set in the input_buffer 1912 * passed to process_capture_result(). 1913 * 1914 * After signaling the release_fence for this buffer, the HAL 1915 * should not make any further attempts to access this buffer as the 1916 * ownership has been fully transferred back to the framework. 1917 * 1918 * If a fence of -1 was specified then the ownership of this buffer 1919 * is transferred back immediately upon the call of process_capture_result. 1920 */ 1921 int release_fence; 1922 1923 } camera3_stream_buffer_t; 1924 1925 /** 1926 * camera3_stream_buffer_set_t: 1927 * 1928 * The complete set of gralloc buffers for a stream. This structure is given to 1929 * register_stream_buffers() to allow the camera HAL device to register/map/etc 1930 * newly allocated stream buffers. 1931 * 1932 * >= CAMERA_DEVICE_API_VERSION_3_2: 1933 * 1934 * Deprecated (and not used). In particular, 1935 * register_stream_buffers is also deprecated and will never be invoked. 1936 * 1937 */ 1938 typedef struct camera3_stream_buffer_set { 1939 /** 1940 * The stream handle for the stream these buffers belong to 1941 */ 1942 camera3_stream_t *stream; 1943 1944 /** 1945 * The number of buffers in this stream. It is guaranteed to be at least 1946 * stream->max_buffers. 1947 */ 1948 uint32_t num_buffers; 1949 1950 /** 1951 * The array of gralloc buffer handles for this stream. If the stream format 1952 * is set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL device 1953 * should inspect the passed-in buffers to determine any platform-private 1954 * pixel format information. 1955 */ 1956 buffer_handle_t **buffers; 1957 1958 } camera3_stream_buffer_set_t; 1959 1960 /** 1961 * camera3_jpeg_blob: 1962 * 1963 * Transport header for compressed JPEG or JPEG_APP_SEGMENTS buffers in output streams. 1964 * 1965 * To capture JPEG or JPEG_APP_SEGMENTS images, a stream is created using the pixel format 1966 * HAL_PIXEL_FORMAT_BLOB. The buffer size for the stream is calculated by the 1967 * framework, based on the static metadata field android.jpeg.maxSize for JPEG, 1968 * and android.jpeg.maxAppsSegments for JPEG_APP_SEGMENTS. 1969 * 1970 * Since compressed JPEG/JPEG_APP_SEGMENTS images are of variable size, the HAL needs to 1971 * include the final size of the image using this structure inside the output 1972 * stream buffer. The JPEG blob ID field must be set to CAMERA3_JPEG_BLOB_ID for 1973 * JPEG and CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID for APP segments. 1974 * 1975 * Transport header should be at the end of the output stream buffer. That 1976 * means the jpeg_blob_id must start at byte[buffer_size - 1977 * sizeof(camera3_jpeg_blob)], where the buffer_size is the size of gralloc buffer. 1978 * The blob data itself starts at the beginning of the buffer and should be 1979 * jpeg_size bytes long. HAL using this transport header for JPEG must account for 1980 * it in android.jpeg.maxSize. For JPEG APP segments, camera framework makes 1981 * sure that the output stream buffer is large enough for the transport header. 1982 */ 1983 typedef struct camera3_jpeg_blob { 1984 uint16_t jpeg_blob_id; 1985 uint32_t jpeg_size; 1986 } camera3_jpeg_blob_t; 1987 1988 enum { 1989 CAMERA3_JPEG_BLOB_ID = 0x00FF, 1990 CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID = 0x0100, 1991 }; 1992 1993 /********************************************************************** 1994 * 1995 * Message definitions for the HAL notify() callback. 1996 * 1997 * These definitions are used for the HAL notify callback, to signal 1998 * asynchronous events from the HAL device to the Android framework. 1999 * 2000 */ 2001 2002 /** 2003 * camera3_msg_type: 2004 * 2005 * Indicates the type of message sent, which specifies which member of the 2006 * message union is valid. 2007 * 2008 */ 2009 typedef enum camera3_msg_type { 2010 /** 2011 * An error has occurred. camera3_notify_msg.message.error contains the 2012 * error information. 2013 */ 2014 CAMERA3_MSG_ERROR = 1, 2015 2016 /** 2017 * The exposure of a given request or processing a reprocess request has 2018 * begun. camera3_notify_msg.message.shutter contains the information 2019 * the capture. 2020 */ 2021 CAMERA3_MSG_SHUTTER = 2, 2022 2023 /** 2024 * Number of framework message types 2025 */ 2026 CAMERA3_NUM_MESSAGES 2027 2028 } camera3_msg_type_t; 2029 2030 /** 2031 * Defined error codes for CAMERA_MSG_ERROR 2032 */ 2033 typedef enum camera3_error_msg_code { 2034 /** 2035 * A serious failure occured. No further frames or buffer streams will 2036 * be produced by the device. Device should be treated as closed. The 2037 * client must reopen the device to use it again. The frame_number field 2038 * is unused. 2039 */ 2040 CAMERA3_MSG_ERROR_DEVICE = 1, 2041 2042 /** 2043 * An error has occurred in processing a request. No output (metadata or 2044 * buffers) will be produced for this request. The frame_number field 2045 * specifies which request has been dropped. Subsequent requests are 2046 * unaffected, and the device remains operational. 2047 */ 2048 CAMERA3_MSG_ERROR_REQUEST = 2, 2049 2050 /** 2051 * An error has occurred in producing an output result metadata buffer 2052 * for a request, but output stream buffers for it will still be 2053 * available. Subsequent requests are unaffected, and the device remains 2054 * operational. The frame_number field specifies the request for which 2055 * result metadata won't be available. 2056 * 2057 * >= CAMERA_DEVICE_API_VERSION_3_6: 2058 * 2059 * In case the result metadata is absent for a logical camera device, then the 2060 * error_stream pointer must be set to NULL. 2061 * If the result metadata cannot be produced for a physical camera device, then 2062 * error_stream must contain a pointer to a respective stream associated with 2063 * that physical device. 2064 */ 2065 CAMERA3_MSG_ERROR_RESULT = 3, 2066 2067 /** 2068 * An error has occurred in placing an output buffer into a stream for a 2069 * request. The frame metadata and other buffers may still be 2070 * available. Subsequent requests are unaffected, and the device remains 2071 * operational. The frame_number field specifies the request for which the 2072 * buffer was dropped, and error_stream contains a pointer to the stream 2073 * that dropped the frame. 2074 */ 2075 CAMERA3_MSG_ERROR_BUFFER = 4, 2076 2077 /** 2078 * Number of error types 2079 */ 2080 CAMERA3_MSG_NUM_ERRORS 2081 2082 } camera3_error_msg_code_t; 2083 2084 /** 2085 * camera3_error_msg_t: 2086 * 2087 * Message contents for CAMERA3_MSG_ERROR 2088 */ 2089 typedef struct camera3_error_msg { 2090 /** 2091 * Frame number of the request the error applies to. 0 if the frame number 2092 * isn't applicable to the error. 2093 */ 2094 uint32_t frame_number; 2095 2096 /** 2097 * Pointer to the stream that had a failure. NULL if the stream isn't 2098 * applicable to the error. 2099 */ 2100 camera3_stream_t *error_stream; 2101 2102 /** 2103 * The code for this error; one of the CAMERA_MSG_ERROR enum values. 2104 */ 2105 int error_code; 2106 2107 } camera3_error_msg_t; 2108 2109 /** 2110 * camera3_shutter_msg_t: 2111 * 2112 * Message contents for CAMERA3_MSG_SHUTTER 2113 */ 2114 typedef struct camera3_shutter_msg { 2115 /** 2116 * Frame number of the request that has begun exposure or reprocessing. 2117 */ 2118 uint32_t frame_number; 2119 2120 /** 2121 * Timestamp for the start of capture. For a reprocess request, this must 2122 * be input image's start of capture. This must match the capture result 2123 * metadata's sensor exposure start timestamp. 2124 */ 2125 uint64_t timestamp; 2126 2127 } camera3_shutter_msg_t; 2128 2129 /** 2130 * camera3_notify_msg_t: 2131 * 2132 * The message structure sent to camera3_callback_ops_t.notify() 2133 */ 2134 typedef struct camera3_notify_msg { 2135 2136 /** 2137 * The message type. One of camera3_notify_msg_type, or a private extension. 2138 */ 2139 int type; 2140 2141 union { 2142 /** 2143 * Error message contents. Valid if type is CAMERA3_MSG_ERROR 2144 */ 2145 camera3_error_msg_t error; 2146 2147 /** 2148 * Shutter message contents. Valid if type is CAMERA3_MSG_SHUTTER 2149 */ 2150 camera3_shutter_msg_t shutter; 2151 2152 /** 2153 * Generic message contents. Used to ensure a minimum size for custom 2154 * message types. 2155 */ 2156 uint8_t generic[32]; 2157 } message; 2158 2159 } camera3_notify_msg_t; 2160 2161 2162 /********************************************************************** 2163 * 2164 * Types definition for request_stream_buffers() callback. 2165 * 2166 */ 2167 2168 /** 2169 * camera3_buffer_request_status_t: 2170 * 2171 * The overall buffer request status returned by request_stream_buffers() 2172 */ 2173 typedef enum camera3_buffer_request_status { 2174 /** 2175 * request_stream_buffers() call succeeded and all requested buffers are 2176 * returned. 2177 */ 2178 CAMERA3_BUF_REQ_OK = 0, 2179 2180 /** 2181 * request_stream_buffers() call failed for some streams. 2182 * Check per stream status for each returned camera3_stream_buffer_ret_t. 2183 */ 2184 CAMERA3_BUF_REQ_FAILED_PARTIAL = 1, 2185 2186 /** 2187 * request_stream_buffers() call failed for all streams and no buffers are 2188 * returned at all. Camera service is about to or is performing 2189 * configure_streams() call. HAL must wait until next configure_streams() 2190 * call is finished before requesting buffers again. 2191 */ 2192 CAMERA3_BUF_REQ_FAILED_CONFIGURING = 2, 2193 2194 /** 2195 * request_stream_buffers() call failed for all streams and no buffers are 2196 * returned at all. Failure due to bad camera3_buffer_request input, eg: 2197 * unknown stream or repeated stream in the list of buffer requests. 2198 */ 2199 CAMERA3_BUF_REQ_FAILED_ILLEGAL_ARGUMENTS = 3, 2200 2201 /** 2202 * request_stream_buffers() call failed for all streams and no buffers are 2203 * returned at all. This can happen for unknown reasons or a combination 2204 * of different failure reasons per stream. For the latter case, caller can 2205 * check per stream failure reason returned in camera3_stream_buffer_ret. 2206 */ 2207 CAMERA3_BUF_REQ_FAILED_UNKNOWN = 4, 2208 2209 /** 2210 * Number of buffer request status 2211 */ 2212 CAMERA3_BUF_REQ_NUM_STATUS 2213 2214 } camera3_buffer_request_status_t; 2215 2216 /** 2217 * camera3_stream_buffer_req_status_t: 2218 * 2219 * The per stream buffer request status returned by request_stream_buffers() 2220 */ 2221 typedef enum camera3_stream_buffer_req_status { 2222 /** 2223 * Get buffer succeeds and all requested buffers are returned. 2224 */ 2225 CAMERA3_PS_BUF_REQ_OK = 0, 2226 2227 /** 2228 * Get buffer failed due to timeout waiting for an available buffer. This is 2229 * likely due to the client application holding too many buffers, or the 2230 * system is under memory pressure. 2231 * This is not a fatal error. HAL can try to request buffer for this stream 2232 * later. If HAL cannot get a buffer for certain capture request in time 2233 * due to this error, HAL can send an ERROR_REQUEST to camera service and 2234 * drop processing that request. 2235 */ 2236 CAMERA3_PS_BUF_REQ_NO_BUFFER_AVAILABLE = 1, 2237 2238 /** 2239 * Get buffer failed due to HAL has reached its maxBuffer count. This is not 2240 * a fatal error. HAL can try to request buffer for this stream again after 2241 * it returns at least one buffer of that stream to camera service. 2242 */ 2243 CAMERA3_PS_BUF_REQ_MAX_BUFFER_EXCEEDED = 2, 2244 2245 /** 2246 * Get buffer failed due to the stream is disconnected by client 2247 * application, has been removed, or not recognized by camera service. 2248 * This means application is no longer interested in this stream. 2249 * Requesting buffer for this stream will never succeed after this error is 2250 * returned. HAL must safely return all buffers of this stream after 2251 * getting this error. If HAL gets another capture request later targeting 2252 * a disconnected stream, HAL must send an ERROR_REQUEST to camera service 2253 * and drop processing that request. 2254 */ 2255 CAMERA3_PS_BUF_REQ_STREAM_DISCONNECTED = 3, 2256 2257 /** 2258 * Get buffer failed for unknown reason. This is a fatal error and HAL must 2259 * send ERROR_DEVICE to camera service and be ready to be closed. 2260 */ 2261 CAMERA3_PS_BUF_REQ_UNKNOWN_ERROR = 4, 2262 2263 /** 2264 * Number of buffer request status 2265 */ 2266 CAMERA3_PS_BUF_REQ_NUM_STATUS 2267 } camera3_stream_buffer_req_status_t; 2268 2269 typedef struct camera3_buffer_request { 2270 /** 2271 * The stream HAL wants to request buffer from 2272 */ 2273 camera3_stream_t *stream; 2274 2275 /** 2276 * The number of buffers HAL requested 2277 */ 2278 uint32_t num_buffers_requested; 2279 } camera3_buffer_request_t; 2280 2281 typedef struct camera3_stream_buffer_ret { 2282 /** 2283 * The stream HAL wants to request buffer from 2284 */ 2285 camera3_stream_t *stream; 2286 2287 /** 2288 * The status of buffer request of this stream 2289 */ 2290 camera3_stream_buffer_req_status_t status; 2291 2292 /** 2293 * Number of output buffers returned. Must be 0 when above status is not 2294 * CAMERA3_PS_BUF_REQ_OK; otherwise the value must be equal to 2295 * num_buffers_requested in the corresponding camera3_buffer_request_t 2296 */ 2297 uint32_t num_output_buffers; 2298 2299 /** 2300 * The returned output buffers for the stream. 2301 * Caller of request_stream_buffers() should supply this with enough memory 2302 * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) 2303 */ 2304 camera3_stream_buffer_t *output_buffers; 2305 } camera3_stream_buffer_ret_t; 2306 2307 2308 /********************************************************************** 2309 * 2310 * Capture request/result definitions for the HAL process_capture_request() 2311 * method, and the process_capture_result() callback. 2312 * 2313 */ 2314 2315 /** 2316 * camera3_request_template_t: 2317 * 2318 * Available template types for 2319 * camera3_device_ops.construct_default_request_settings() 2320 */ 2321 typedef enum camera3_request_template { 2322 /** 2323 * Standard camera preview operation with 3A on auto. 2324 */ 2325 CAMERA3_TEMPLATE_PREVIEW = 1, 2326 2327 /** 2328 * Standard camera high-quality still capture with 3A and flash on auto. 2329 */ 2330 CAMERA3_TEMPLATE_STILL_CAPTURE = 2, 2331 2332 /** 2333 * Standard video recording plus preview with 3A on auto, torch off. 2334 */ 2335 CAMERA3_TEMPLATE_VIDEO_RECORD = 3, 2336 2337 /** 2338 * High-quality still capture while recording video. Application will 2339 * include preview, video record, and full-resolution YUV or JPEG streams in 2340 * request. Must not cause stuttering on video stream. 3A on auto. 2341 */ 2342 CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4, 2343 2344 /** 2345 * Zero-shutter-lag mode. Application will request preview and 2346 * full-resolution data for each frame, and reprocess it to JPEG when a 2347 * still image is requested by user. Settings should provide highest-quality 2348 * full-resolution images without compromising preview frame rate. 3A on 2349 * auto. 2350 */ 2351 CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5, 2352 2353 /** 2354 * A basic template for direct application control of capture 2355 * parameters. All automatic control is disabled (auto-exposure, auto-white 2356 * balance, auto-focus), and post-processing parameters are set to preview 2357 * quality. The manual capture parameters (exposure, sensitivity, etc.) 2358 * are set to reasonable defaults, but should be overridden by the 2359 * application depending on the intended use case. 2360 */ 2361 CAMERA3_TEMPLATE_MANUAL = 6, 2362 2363 /* Total number of templates */ 2364 CAMERA3_TEMPLATE_COUNT, 2365 2366 /** 2367 * First value for vendor-defined request templates 2368 */ 2369 CAMERA3_VENDOR_TEMPLATE_START = 0x40000000 2370 2371 } camera3_request_template_t; 2372 2373 /** 2374 * camera3_capture_request_t: 2375 * 2376 * A single request for image capture/buffer reprocessing, sent to the Camera 2377 * HAL device by the framework in process_capture_request(). 2378 * 2379 * The request contains the settings to be used for this capture, and the set of 2380 * output buffers to write the resulting image data in. It may optionally 2381 * contain an input buffer, in which case the request is for reprocessing that 2382 * input buffer instead of capturing a new image with the camera sensor. The 2383 * capture is identified by the frame_number. 2384 * 2385 * In response, the camera HAL device must send a camera3_capture_result 2386 * structure asynchronously to the framework, using the process_capture_result() 2387 * callback. 2388 */ 2389 typedef struct camera3_capture_request { 2390 /** 2391 * The frame number is an incrementing integer set by the framework to 2392 * uniquely identify this capture. It needs to be returned in the result 2393 * call, and is also used to identify the request in asynchronous 2394 * notifications sent to camera3_callback_ops_t.notify(). 2395 */ 2396 uint32_t frame_number; 2397 2398 /** 2399 * The settings buffer contains the capture and processing parameters for 2400 * the request. As a special case, a NULL settings buffer indicates that the 2401 * settings are identical to the most-recently submitted capture request. A 2402 * NULL buffer cannot be used as the first submitted request after a 2403 * configure_streams() call. 2404 */ 2405 const camera_metadata_t *settings; 2406 2407 /** 2408 * The input stream buffer to use for this request, if any. 2409 * 2410 * If input_buffer is NULL, then the request is for a new capture from the 2411 * imager. If input_buffer is valid, the request is for reprocessing the 2412 * image contained in input_buffer. 2413 * 2414 * In the latter case, the HAL must set the release_fence of the 2415 * input_buffer to a valid sync fence, or to -1 if the HAL does not support 2416 * sync, before process_capture_request() returns. 2417 * 2418 * The HAL is required to wait on the acquire sync fence of the input buffer 2419 * before accessing it. 2420 * 2421 * <= CAMERA_DEVICE_API_VERSION_3_1: 2422 * 2423 * Any input buffer included here will have been registered with the HAL 2424 * through register_stream_buffers() before its inclusion in a request. 2425 * 2426 * >= CAMERA_DEVICE_API_VERSION_3_2: 2427 * 2428 * The buffers will not have been pre-registered with the HAL. 2429 * Subsequent requests may reuse buffers, or provide entirely new buffers. 2430 */ 2431 camera3_stream_buffer_t *input_buffer; 2432 2433 /** 2434 * The number of output buffers for this capture request. Must be at least 2435 * 1. 2436 */ 2437 uint32_t num_output_buffers; 2438 2439 /** 2440 * An array of num_output_buffers stream buffers, to be filled with image 2441 * data from this capture/reprocess. The HAL must wait on the acquire fences 2442 * of each stream buffer before writing to them. 2443 * 2444 * The HAL takes ownership of the actual buffer_handle_t entries in 2445 * output_buffers; the framework does not access them until they are 2446 * returned in a camera3_capture_result_t. 2447 * 2448 * <= CAMERA_DEVICE_API_VERSION_3_1: 2449 * 2450 * All the buffers included here will have been registered with the HAL 2451 * through register_stream_buffers() before their inclusion in a request. 2452 * 2453 * >= CAMERA_DEVICE_API_VERSION_3_2: 2454 * 2455 * Any or all of the buffers included here may be brand new in this 2456 * request (having never before seen by the HAL). 2457 */ 2458 const camera3_stream_buffer_t *output_buffers; 2459 2460 /** 2461 * <= CAMERA_DEVICE_API_VERISON_3_4: 2462 * 2463 * Not defined and must not be accessed. 2464 * 2465 * >= CAMERA_DEVICE_API_VERSION_3_5: 2466 * The number of physical camera settings to be applied. If 'num_physcam_settings' 2467 * equals 0 or a physical device is not included, then Hal must decide the 2468 * specific physical device settings based on the default 'settings'. 2469 */ 2470 uint32_t num_physcam_settings; 2471 2472 /** 2473 * <= CAMERA_DEVICE_API_VERISON_3_4: 2474 * 2475 * Not defined and must not be accessed. 2476 * 2477 * >= CAMERA_DEVICE_API_VERSION_3_5: 2478 * The physical camera ids. The array will contain 'num_physcam_settings' 2479 * camera id strings for all physical devices that have specific settings. 2480 * In case some id is invalid, the process capture request must fail and return 2481 * -EINVAL. 2482 */ 2483 const char **physcam_id; 2484 2485 /** 2486 * <= CAMERA_DEVICE_API_VERISON_3_4: 2487 * 2488 * Not defined and must not be accessed. 2489 * 2490 * >= CAMERA_DEVICE_API_VERSION_3_5: 2491 * The capture settings for the physical cameras. The array will contain 2492 * 'num_physcam_settings' settings for invididual physical devices. In 2493 * case the settings at some particular index are empty, the process capture 2494 * request must fail and return -EINVAL. 2495 */ 2496 const camera_metadata_t **physcam_settings; 2497 2498 } camera3_capture_request_t; 2499 2500 /** 2501 * camera3_capture_result_t: 2502 * 2503 * The result of a single capture/reprocess by the camera HAL device. This is 2504 * sent to the framework asynchronously with process_capture_result(), in 2505 * response to a single capture request sent to the HAL with 2506 * process_capture_request(). Multiple process_capture_result() calls may be 2507 * performed by the HAL for each request. 2508 * 2509 * Each call, all with the same frame 2510 * number, may contain some subset of the output buffers, and/or the result 2511 * metadata. The metadata may only be provided once for a given frame number; 2512 * all other calls must set the result metadata to NULL. 2513 * 2514 * The result structure contains the output metadata from this capture, and the 2515 * set of output buffers that have been/will be filled for this capture. Each 2516 * output buffer may come with a release sync fence that the framework will wait 2517 * on before reading, in case the buffer has not yet been filled by the HAL. 2518 * 2519 * >= CAMERA_DEVICE_API_VERSION_3_2: 2520 * 2521 * The metadata may be provided multiple times for a single frame number. The 2522 * framework will accumulate together the final result set by combining each 2523 * partial result together into the total result set. 2524 * 2525 * If an input buffer is given in a request, the HAL must return it in one of 2526 * the process_capture_result calls, and the call may be to just return the input 2527 * buffer, without metadata and output buffers; the sync fences must be handled 2528 * the same way they are done for output buffers. 2529 * 2530 * 2531 * Performance considerations: 2532 * 2533 * Applications will also receive these partial results immediately, so sending 2534 * partial results is a highly recommended performance optimization to avoid 2535 * the total pipeline latency before sending the results for what is known very 2536 * early on in the pipeline. 2537 * 2538 * A typical use case might be calculating the AF state halfway through the 2539 * pipeline; by sending the state back to the framework immediately, we get a 2540 * 50% performance increase and perceived responsiveness of the auto-focus. 2541 * 2542 */ 2543 typedef struct camera3_capture_result { 2544 /** 2545 * The frame number is an incrementing integer set by the framework in the 2546 * submitted request to uniquely identify this capture. It is also used to 2547 * identify the request in asynchronous notifications sent to 2548 * camera3_callback_ops_t.notify(). 2549 */ 2550 uint32_t frame_number; 2551 2552 /** 2553 * The result metadata for this capture. This contains information about the 2554 * final capture parameters, the state of the capture and post-processing 2555 * hardware, the state of the 3A algorithms, if enabled, and the output of 2556 * any enabled statistics units. 2557 * 2558 * Only one call to process_capture_result() with a given frame_number may 2559 * include the result metadata. All other calls for the same frame_number 2560 * must set this to NULL. 2561 * 2562 * If there was an error producing the result metadata, result must be an 2563 * empty metadata buffer, and notify() must be called with ERROR_RESULT. 2564 * 2565 * >= CAMERA_DEVICE_API_VERSION_3_2: 2566 * 2567 * Multiple calls to process_capture_result() with a given frame_number 2568 * may include the result metadata. 2569 * 2570 * Partial metadata submitted should not include any metadata key returned 2571 * in a previous partial result for a given frame. Each new partial result 2572 * for that frame must also set a distinct partial_result value. 2573 * 2574 * If notify has been called with ERROR_RESULT, all further partial 2575 * results for that frame are ignored by the framework. 2576 */ 2577 const camera_metadata_t *result; 2578 2579 /** 2580 * The number of output buffers returned in this result structure. Must be 2581 * less than or equal to the matching capture request's count. If this is 2582 * less than the buffer count in the capture request, at least one more call 2583 * to process_capture_result with the same frame_number must be made, to 2584 * return the remaining output buffers to the framework. This may only be 2585 * zero if the structure includes valid result metadata or an input buffer 2586 * is returned in this result. 2587 */ 2588 uint32_t num_output_buffers; 2589 2590 /** 2591 * The handles for the output stream buffers for this capture. They may not 2592 * yet be filled at the time the HAL calls process_capture_result(); the 2593 * framework will wait on the release sync fences provided by the HAL before 2594 * reading the buffers. 2595 * 2596 * The HAL must set the stream buffer's release sync fence to a valid sync 2597 * fd, or to -1 if the buffer has already been filled. 2598 * 2599 * If the HAL encounters an error while processing the buffer, and the 2600 * buffer is not filled, the buffer's status field must be set to 2601 * CAMERA3_BUFFER_STATUS_ERROR. If the HAL did not wait on the acquire fence 2602 * before encountering the error, the acquire fence should be copied into 2603 * the release fence, to allow the framework to wait on the fence before 2604 * reusing the buffer. 2605 * 2606 * The acquire fence must be set to -1 for all output buffers. If 2607 * num_output_buffers is zero, this may be NULL. In that case, at least one 2608 * more process_capture_result call must be made by the HAL to provide the 2609 * output buffers. 2610 * 2611 * When process_capture_result is called with a new buffer for a frame, 2612 * all previous frames' buffers for that corresponding stream must have been 2613 * already delivered (the fences need not have yet been signaled). 2614 * 2615 * >= CAMERA_DEVICE_API_VERSION_3_2: 2616 * 2617 * Gralloc buffers for a frame may be sent to framework before the 2618 * corresponding SHUTTER-notify. 2619 * 2620 * Performance considerations: 2621 * 2622 * Buffers delivered to the framework will not be dispatched to the 2623 * application layer until a start of exposure timestamp has been received 2624 * via a SHUTTER notify() call. It is highly recommended to 2625 * dispatch that call as early as possible. 2626 */ 2627 const camera3_stream_buffer_t *output_buffers; 2628 2629 /** 2630 * >= CAMERA_DEVICE_API_VERSION_3_2: 2631 * 2632 * The handle for the input stream buffer for this capture. It may not 2633 * yet be consumed at the time the HAL calls process_capture_result(); the 2634 * framework will wait on the release sync fences provided by the HAL before 2635 * reusing the buffer. 2636 * 2637 * The HAL should handle the sync fences the same way they are done for 2638 * output_buffers. 2639 * 2640 * Only one input buffer is allowed to be sent per request. Similarly to 2641 * output buffers, the ordering of returned input buffers must be 2642 * maintained by the HAL. 2643 * 2644 * Performance considerations: 2645 * 2646 * The input buffer should be returned as early as possible. If the HAL 2647 * supports sync fences, it can call process_capture_result to hand it back 2648 * with sync fences being set appropriately. If the sync fences are not 2649 * supported, the buffer can only be returned when it is consumed, which 2650 * may take long time; the HAL may choose to copy this input buffer to make 2651 * the buffer return sooner. 2652 */ 2653 const camera3_stream_buffer_t *input_buffer; 2654 2655 /** 2656 * >= CAMERA_DEVICE_API_VERSION_3_2: 2657 * 2658 * In order to take advantage of partial results, the HAL must set the 2659 * static metadata android.request.partialResultCount to the number of 2660 * partial results it will send for each frame. 2661 * 2662 * Each new capture result with a partial result must set 2663 * this field (partial_result) to a distinct inclusive value between 2664 * 1 and android.request.partialResultCount. 2665 * 2666 * HALs not wishing to take advantage of this feature must not 2667 * set an android.request.partialResultCount or partial_result to a value 2668 * other than 1. 2669 * 2670 * This value must be set to 0 when a capture result contains buffers only 2671 * and no metadata. 2672 */ 2673 uint32_t partial_result; 2674 2675 /** 2676 * >= CAMERA_DEVICE_API_VERSION_3_5: 2677 * 2678 * Specifies the number of physical camera metadata this capture result 2679 * contains. It must be equal to the number of physical cameras being 2680 * requested from. 2681 * 2682 * If the current camera device is not a logical multi-camera, or the 2683 * corresponding capture_request doesn't request on any physical camera, 2684 * this field must be 0. 2685 */ 2686 uint32_t num_physcam_metadata; 2687 2688 /** 2689 * >= CAMERA_DEVICE_API_VERSION_3_5: 2690 * 2691 * An array of strings containing the physical camera ids for the returned 2692 * physical camera metadata. The length of the array is 2693 * num_physcam_metadata. 2694 */ 2695 const char **physcam_ids; 2696 2697 /** 2698 * >= CAMERA_DEVICE_API_VERSION_3_5: 2699 * 2700 * The array of physical camera metadata for the physical cameras being 2701 * requested upon. This array should have a 1-to-1 mapping with the 2702 * physcam_ids. The length of the array is num_physcam_metadata. 2703 */ 2704 const camera_metadata_t **physcam_metadata; 2705 2706 } camera3_capture_result_t; 2707 2708 /********************************************************************** 2709 * 2710 * Callback methods for the HAL to call into the framework. 2711 * 2712 * These methods are used to return metadata and image buffers for a completed 2713 * or failed captures, and to notify the framework of asynchronous events such 2714 * as errors. 2715 * 2716 * The framework will not call back into the HAL from within these callbacks, 2717 * and these calls will not block for extended periods. 2718 * 2719 */ 2720 typedef struct camera3_callback_ops { 2721 2722 /** 2723 * process_capture_result: 2724 * 2725 * Send results from a completed capture to the framework. 2726 * process_capture_result() may be invoked multiple times by the HAL in 2727 * response to a single capture request. This allows, for example, the 2728 * metadata and low-resolution buffers to be returned in one call, and 2729 * post-processed JPEG buffers in a later call, once it is available. Each 2730 * call must include the frame number of the request it is returning 2731 * metadata or buffers for. 2732 * 2733 * A component (buffer or metadata) of the complete result may only be 2734 * included in one process_capture_result call. A buffer for each stream, 2735 * and the result metadata, must be returned by the HAL for each request in 2736 * one of the process_capture_result calls, even in case of errors producing 2737 * some of the output. A call to process_capture_result() with neither 2738 * output buffers or result metadata is not allowed. 2739 * 2740 * The order of returning metadata and buffers for a single result does not 2741 * matter, but buffers for a given stream must be returned in FIFO order. So 2742 * the buffer for request 5 for stream A must always be returned before the 2743 * buffer for request 6 for stream A. This also applies to the result 2744 * metadata; the metadata for request 5 must be returned before the metadata 2745 * for request 6. 2746 * 2747 * However, different streams are independent of each other, so it is 2748 * acceptable and expected that the buffer for request 5 for stream A may be 2749 * returned after the buffer for request 6 for stream B is. And it is 2750 * acceptable that the result metadata for request 6 for stream B is 2751 * returned before the buffer for request 5 for stream A is. 2752 * 2753 * The HAL retains ownership of result structure, which only needs to be 2754 * valid to access during this call. The framework will copy whatever it 2755 * needs before this call returns. 2756 * 2757 * The output buffers do not need to be filled yet; the framework will wait 2758 * on the stream buffer release sync fence before reading the buffer 2759 * data. Therefore, this method should be called by the HAL as soon as 2760 * possible, even if some or all of the output buffers are still in 2761 * being filled. The HAL must include valid release sync fences into each 2762 * output_buffers stream buffer entry, or -1 if that stream buffer is 2763 * already filled. 2764 * 2765 * If the result buffer cannot be constructed for a request, the HAL should 2766 * return an empty metadata buffer, but still provide the output buffers and 2767 * their sync fences. In addition, notify() must be called with an 2768 * ERROR_RESULT message. 2769 * 2770 * If an output buffer cannot be filled, its status field must be set to 2771 * STATUS_ERROR. In addition, notify() must be called with a ERROR_BUFFER 2772 * message. 2773 * 2774 * If the entire capture has failed, then this method still needs to be 2775 * called to return the output buffers to the framework. All the buffer 2776 * statuses should be STATUS_ERROR, and the result metadata should be an 2777 * empty buffer. In addition, notify() must be called with a ERROR_REQUEST 2778 * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages 2779 * should not be sent. 2780 * 2781 * Performance requirements: 2782 * 2783 * This is a non-blocking call. The framework will return this call in 5ms. 2784 * 2785 * The pipeline latency (see S7 for definition) should be less than or equal to 2786 * 4 frame intervals, and must be less than or equal to 8 frame intervals. 2787 * 2788 */ 2789 void (*process_capture_result)(const struct camera3_callback_ops *, 2790 const camera3_capture_result_t *result); 2791 2792 /** 2793 * notify: 2794 * 2795 * Asynchronous notification callback from the HAL, fired for various 2796 * reasons. Only for information independent of frame capture, or that 2797 * require specific timing. The ownership of the message structure remains 2798 * with the HAL, and the msg only needs to be valid for the duration of this 2799 * call. 2800 * 2801 * Multiple threads may call notify() simultaneously. 2802 * 2803 * <= CAMERA_DEVICE_API_VERSION_3_1: 2804 * 2805 * The notification for the start of exposure for a given request must be 2806 * sent by the HAL before the first call to process_capture_result() for 2807 * that request is made. 2808 * 2809 * >= CAMERA_DEVICE_API_VERSION_3_2: 2810 * 2811 * Buffers delivered to the framework will not be dispatched to the 2812 * application layer until a start of exposure timestamp (or input image's 2813 * start of exposure timestamp for a reprocess request) has been received 2814 * via a SHUTTER notify() call. It is highly recommended to dispatch this 2815 * call as early as possible. 2816 * 2817 * ------------------------------------------------------------------------ 2818 * Performance requirements: 2819 * 2820 * This is a non-blocking call. The framework will return this call in 5ms. 2821 */ 2822 void (*notify)(const struct camera3_callback_ops *, 2823 const camera3_notify_msg_t *msg); 2824 2825 /** 2826 * request_stream_buffers: 2827 * 2828 * <= CAMERA_DEVICE_API_VERISON_3_5: 2829 * 2830 * DO NOT USE: not defined and must be NULL. 2831 * 2832 * >= CAMERA_DEVICE_API_VERISON_3_6: 2833 * 2834 * Synchronous callback for HAL to ask for output buffer from camera service. 2835 * 2836 * This call may be serialized in camera service so it is strongly 2837 * recommended to only call this method from one thread. 2838 * 2839 * When camera device advertises 2840 * (android.info.supportedBufferManagementVersion == 2841 * ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION_HIDL_DEVICE_3_5), HAL 2842 * can use this method to request buffers from camera service. 2843 * 2844 * Caller is responsible for allocating enough memory for returned_buf_reqs 2845 * argument (num_buffer_reqs * sizeof(camera3_stream_buffer_ret_t)) bytes 2846 * and also the memory for the output_buffers field in each 2847 * camera3_stream_buffer_ret_t 2848 * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) bytes 2849 * 2850 * Performance requirements: 2851 * This is a blocking call that takes more time with more buffers requested. 2852 * HAL should not request large amount of buffers on a latency critical code 2853 * path. It is highly recommended to use a dedicated thread to perform 2854 * all requestStreamBuffer calls, and adjust the thread priority and/or 2855 * timing of making the call in order for buffers to arrive before HAL is 2856 * ready to fill the buffer. 2857 */ 2858 camera3_buffer_request_status_t (*request_stream_buffers)( 2859 const struct camera3_callback_ops *, 2860 uint32_t num_buffer_reqs, 2861 const camera3_buffer_request_t *buffer_reqs, 2862 /*out*/uint32_t *num_returned_buf_reqs, 2863 /*out*/camera3_stream_buffer_ret_t *returned_buf_reqs); 2864 2865 /** 2866 * return_stream_buffers: 2867 * 2868 * <= CAMERA_DEVICE_API_VERISON_3_5: 2869 * 2870 * DO NOT USE: not defined and must be NULL. 2871 * 2872 * >= CAMERA_DEVICE_API_VERISON_3_6: 2873 * 2874 * Synchronous callback for HAL to return output buffers to camera service. 2875 * 2876 * If this method is called during a configure_streams() call, it will be 2877 * blocked until camera service finishes the ongoing configure_streams() call. 2878 */ 2879 void (*return_stream_buffers)( 2880 const struct camera3_callback_ops *, 2881 uint32_t num_buffers, 2882 const camera3_stream_buffer_t* const* buffers); 2883 2884 } camera3_callback_ops_t; 2885 2886 /********************************************************************** 2887 * 2888 * Camera device operations 2889 * 2890 */ 2891 typedef struct camera3_device_ops { 2892 2893 /** 2894 * initialize: 2895 * 2896 * One-time initialization to pass framework callback function pointers to 2897 * the HAL. Will be called once after a successful open() call, before any 2898 * other functions are called on the camera3_device_ops structure. 2899 * 2900 * Performance requirements: 2901 * 2902 * This should be a non-blocking call. The HAL should return from this call 2903 * in 5ms, and must return from this call in 10ms. 2904 * 2905 * Return values: 2906 * 2907 * 0: On successful initialization 2908 * 2909 * -ENODEV: If initialization fails. Only close() can be called successfully 2910 * by the framework after this. 2911 */ 2912 int (*initialize)(const struct camera3_device *, 2913 const camera3_callback_ops_t *callback_ops); 2914 2915 /********************************************************************** 2916 * Stream management 2917 */ 2918 2919 /** 2920 * configure_streams: 2921 * 2922 * CAMERA_DEVICE_API_VERSION_3_0 only: 2923 * 2924 * Reset the HAL camera device processing pipeline and set up new input and 2925 * output streams. This call replaces any existing stream configuration with 2926 * the streams defined in the stream_list. This method will be called at 2927 * least once after initialize() before a request is submitted with 2928 * process_capture_request(). 2929 * 2930 * The stream_list must contain at least one output-capable stream, and may 2931 * not contain more than one input-capable stream. 2932 * 2933 * The stream_list may contain streams that are also in the currently-active 2934 * set of streams (from the previous call to configure_stream()). These 2935 * streams will already have valid values for usage, max_buffers, and the 2936 * private pointer. 2937 * 2938 * If such a stream has already had its buffers registered, 2939 * register_stream_buffers() will not be called again for the stream, and 2940 * buffers from the stream can be immediately included in input requests. 2941 * 2942 * If the HAL needs to change the stream configuration for an existing 2943 * stream due to the new configuration, it may rewrite the values of usage 2944 * and/or max_buffers during the configure call. 2945 * 2946 * The framework will detect such a change, and will then reallocate the 2947 * stream buffers, and call register_stream_buffers() again before using 2948 * buffers from that stream in a request. 2949 * 2950 * If a currently-active stream is not included in stream_list, the HAL may 2951 * safely remove any references to that stream. It will not be reused in a 2952 * later configure() call by the framework, and all the gralloc buffers for 2953 * it will be freed after the configure_streams() call returns. 2954 * 2955 * The stream_list structure is owned by the framework, and may not be 2956 * accessed once this call completes. The address of an individual 2957 * camera3_stream_t structure will remain valid for access by the HAL until 2958 * the end of the first configure_stream() call which no longer includes 2959 * that camera3_stream_t in the stream_list argument. The HAL may not change 2960 * values in the stream structure outside of the private pointer, except for 2961 * the usage and max_buffers members during the configure_streams() call 2962 * itself. 2963 * 2964 * If the stream is new, the usage, max_buffer, and private pointer fields 2965 * of the stream structure will all be set to 0. The HAL device must set 2966 * these fields before the configure_streams() call returns. These fields 2967 * are then used by the framework and the platform gralloc module to 2968 * allocate the gralloc buffers for each stream. 2969 * 2970 * Before such a new stream can have its buffers included in a capture 2971 * request, the framework will call register_stream_buffers() with that 2972 * stream. However, the framework is not required to register buffers for 2973 * _all_ streams before submitting a request. This allows for quick startup 2974 * of (for example) a preview stream, with allocation for other streams 2975 * happening later or concurrently. 2976 * 2977 * ------------------------------------------------------------------------ 2978 * CAMERA_DEVICE_API_VERSION_3_1 only: 2979 * 2980 * Reset the HAL camera device processing pipeline and set up new input and 2981 * output streams. This call replaces any existing stream configuration with 2982 * the streams defined in the stream_list. This method will be called at 2983 * least once after initialize() before a request is submitted with 2984 * process_capture_request(). 2985 * 2986 * The stream_list must contain at least one output-capable stream, and may 2987 * not contain more than one input-capable stream. 2988 * 2989 * The stream_list may contain streams that are also in the currently-active 2990 * set of streams (from the previous call to configure_stream()). These 2991 * streams will already have valid values for usage, max_buffers, and the 2992 * private pointer. 2993 * 2994 * If such a stream has already had its buffers registered, 2995 * register_stream_buffers() will not be called again for the stream, and 2996 * buffers from the stream can be immediately included in input requests. 2997 * 2998 * If the HAL needs to change the stream configuration for an existing 2999 * stream due to the new configuration, it may rewrite the values of usage 3000 * and/or max_buffers during the configure call. 3001 * 3002 * The framework will detect such a change, and will then reallocate the 3003 * stream buffers, and call register_stream_buffers() again before using 3004 * buffers from that stream in a request. 3005 * 3006 * If a currently-active stream is not included in stream_list, the HAL may 3007 * safely remove any references to that stream. It will not be reused in a 3008 * later configure() call by the framework, and all the gralloc buffers for 3009 * it will be freed after the configure_streams() call returns. 3010 * 3011 * The stream_list structure is owned by the framework, and may not be 3012 * accessed once this call completes. The address of an individual 3013 * camera3_stream_t structure will remain valid for access by the HAL until 3014 * the end of the first configure_stream() call which no longer includes 3015 * that camera3_stream_t in the stream_list argument. The HAL may not change 3016 * values in the stream structure outside of the private pointer, except for 3017 * the usage and max_buffers members during the configure_streams() call 3018 * itself. 3019 * 3020 * If the stream is new, max_buffer, and private pointer fields of the 3021 * stream structure will all be set to 0. The usage will be set to the 3022 * consumer usage flags. The HAL device must set these fields before the 3023 * configure_streams() call returns. These fields are then used by the 3024 * framework and the platform gralloc module to allocate the gralloc 3025 * buffers for each stream. 3026 * 3027 * Before such a new stream can have its buffers included in a capture 3028 * request, the framework will call register_stream_buffers() with that 3029 * stream. However, the framework is not required to register buffers for 3030 * _all_ streams before submitting a request. This allows for quick startup 3031 * of (for example) a preview stream, with allocation for other streams 3032 * happening later or concurrently. 3033 * 3034 * ------------------------------------------------------------------------ 3035 * >= CAMERA_DEVICE_API_VERSION_3_2: 3036 * 3037 * Reset the HAL camera device processing pipeline and set up new input and 3038 * output streams. This call replaces any existing stream configuration with 3039 * the streams defined in the stream_list. This method will be called at 3040 * least once after initialize() before a request is submitted with 3041 * process_capture_request(). 3042 * 3043 * The stream_list must contain at least one output-capable stream, and may 3044 * not contain more than one input-capable stream. 3045 * 3046 * The stream_list may contain streams that are also in the currently-active 3047 * set of streams (from the previous call to configure_stream()). These 3048 * streams will already have valid values for usage, max_buffers, and the 3049 * private pointer. 3050 * 3051 * If the HAL needs to change the stream configuration for an existing 3052 * stream due to the new configuration, it may rewrite the values of usage 3053 * and/or max_buffers during the configure call. 3054 * 3055 * The framework will detect such a change, and may then reallocate the 3056 * stream buffers before using buffers from that stream in a request. 3057 * 3058 * If a currently-active stream is not included in stream_list, the HAL may 3059 * safely remove any references to that stream. It will not be reused in a 3060 * later configure() call by the framework, and all the gralloc buffers for 3061 * it will be freed after the configure_streams() call returns. 3062 * 3063 * The stream_list structure is owned by the framework, and may not be 3064 * accessed once this call completes. The address of an individual 3065 * camera3_stream_t structure will remain valid for access by the HAL until 3066 * the end of the first configure_stream() call which no longer includes 3067 * that camera3_stream_t in the stream_list argument. The HAL may not change 3068 * values in the stream structure outside of the private pointer, except for 3069 * the usage and max_buffers members during the configure_streams() call 3070 * itself. 3071 * 3072 * If the stream is new, max_buffer, and private pointer fields of the 3073 * stream structure will all be set to 0. The usage will be set to the 3074 * consumer usage flags. The HAL device must set these fields before the 3075 * configure_streams() call returns. These fields are then used by the 3076 * framework and the platform gralloc module to allocate the gralloc 3077 * buffers for each stream. 3078 * 3079 * Newly allocated buffers may be included in a capture request at any time 3080 * by the framework. Once a gralloc buffer is returned to the framework 3081 * with process_capture_result (and its respective release_fence has been 3082 * signaled) the framework may free or reuse it at any time. 3083 * 3084 * ------------------------------------------------------------------------ 3085 * 3086 * Preconditions: 3087 * 3088 * The framework will only call this method when no captures are being 3089 * processed. That is, all results have been returned to the framework, and 3090 * all in-flight input and output buffers have been returned and their 3091 * release sync fences have been signaled by the HAL. The framework will not 3092 * submit new requests for capture while the configure_streams() call is 3093 * underway. 3094 * 3095 * Postconditions: 3096 * 3097 * The HAL device must configure itself to provide maximum possible output 3098 * frame rate given the sizes and formats of the output streams, as 3099 * documented in the camera device's static metadata. 3100 * 3101 * Performance requirements: 3102 * 3103 * This call is expected to be heavyweight and possibly take several hundred 3104 * milliseconds to complete, since it may require resetting and 3105 * reconfiguring the image sensor and the camera processing pipeline. 3106 * Nevertheless, the HAL device should attempt to minimize the 3107 * reconfiguration delay to minimize the user-visible pauses during 3108 * application operational mode changes (such as switching from still 3109 * capture to video recording). 3110 * 3111 * The HAL should return from this call in 500ms, and must return from this 3112 * call in 1000ms. 3113 * 3114 * Return values: 3115 * 3116 * 0: On successful stream configuration 3117 * 3118 * -EINVAL: If the requested stream configuration is invalid. Some examples 3119 * of invalid stream configurations include: 3120 * 3121 * - Including more than 1 input-capable stream (INPUT or 3122 * BIDIRECTIONAL) 3123 * 3124 * - Not including any output-capable streams (OUTPUT or 3125 * BIDIRECTIONAL) 3126 * 3127 * - Including streams with unsupported formats, or an unsupported 3128 * size for that format. 3129 * 3130 * - Including too many output streams of a certain format. 3131 * 3132 * - Unsupported rotation configuration (only applies to 3133 * devices with version >= CAMERA_DEVICE_API_VERSION_3_3) 3134 * 3135 * - Stream sizes/formats don't satisfy the 3136 * camera3_stream_configuration_t->operation_mode requirements for non-NORMAL mode, 3137 * or the requested operation_mode is not supported by the HAL. 3138 * (only applies to devices with version >= CAMERA_DEVICE_API_VERSION_3_3) 3139 * 3140 * Note that the framework submitting an invalid stream 3141 * configuration is not normal operation, since stream 3142 * configurations are checked before configure. An invalid 3143 * configuration means that a bug exists in the framework code, or 3144 * there is a mismatch between the HAL's static metadata and the 3145 * requirements on streams. 3146 * 3147 * -ENODEV: If there has been a fatal error and the device is no longer 3148 * operational. Only close() can be called successfully by the 3149 * framework after this error is returned. 3150 */ 3151 int (*configure_streams)(const struct camera3_device *, 3152 camera3_stream_configuration_t *stream_list); 3153 3154 /** 3155 * register_stream_buffers: 3156 * 3157 * >= CAMERA_DEVICE_API_VERSION_3_2: 3158 * 3159 * DEPRECATED. This will not be called and must be set to NULL. 3160 * 3161 * <= CAMERA_DEVICE_API_VERSION_3_1: 3162 * 3163 * Register buffers for a given stream with the HAL device. This method is 3164 * called by the framework after a new stream is defined by 3165 * configure_streams, and before buffers from that stream are included in a 3166 * capture request. If the same stream is listed in a subsequent 3167 * configure_streams() call, register_stream_buffers will _not_ be called 3168 * again for that stream. 3169 * 3170 * The framework does not need to register buffers for all configured 3171 * streams before it submits the first capture request. This allows quick 3172 * startup for preview (or similar use cases) while other streams are still 3173 * being allocated. 3174 * 3175 * This method is intended to allow the HAL device to map or otherwise 3176 * prepare the buffers for later use. The buffers passed in will already be 3177 * locked for use. At the end of the call, all the buffers must be ready to 3178 * be returned to the stream. The buffer_set argument is only valid for the 3179 * duration of this call. 3180 * 3181 * If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 3182 * the camera HAL should inspect the passed-in buffers here to determine any 3183 * platform-private pixel format information. 3184 * 3185 * Performance requirements: 3186 * 3187 * This should be a non-blocking call. The HAL should return from this call 3188 * in 1ms, and must return from this call in 5ms. 3189 * 3190 * Return values: 3191 * 3192 * 0: On successful registration of the new stream buffers 3193 * 3194 * -EINVAL: If the stream_buffer_set does not refer to a valid active 3195 * stream, or if the buffers array is invalid. 3196 * 3197 * -ENOMEM: If there was a failure in registering the buffers. The framework 3198 * must consider all the stream buffers to be unregistered, and can 3199 * try to register again later. 3200 * 3201 * -ENODEV: If there is a fatal error, and the device is no longer 3202 * operational. Only close() can be called successfully by the 3203 * framework after this error is returned. 3204 */ 3205 int (*register_stream_buffers)(const struct camera3_device *, 3206 const camera3_stream_buffer_set_t *buffer_set); 3207 3208 /********************************************************************** 3209 * Request creation and submission 3210 */ 3211 3212 /** 3213 * construct_default_request_settings: 3214 * 3215 * Create capture settings for standard camera use cases. 3216 * 3217 * The device must return a settings buffer that is configured to meet the 3218 * requested use case, which must be one of the CAMERA3_TEMPLATE_* 3219 * enums. All request control fields must be included. 3220 * 3221 * The HAL retains ownership of this structure, but the pointer to the 3222 * structure must be valid until the device is closed. The framework and the 3223 * HAL may not modify the buffer once it is returned by this call. The same 3224 * buffer may be returned for subsequent calls for the same template, or for 3225 * other templates. 3226 * 3227 * Performance requirements: 3228 * 3229 * This should be a non-blocking call. The HAL should return from this call 3230 * in 1ms, and must return from this call in 5ms. 3231 * 3232 * Return values: 3233 * 3234 * Valid metadata: On successful creation of a default settings 3235 * buffer. 3236 * 3237 * NULL: In case of a fatal error. After this is returned, only 3238 * the close() method can be called successfully by the 3239 * framework. 3240 */ 3241 const camera_metadata_t* (*construct_default_request_settings)( 3242 const struct camera3_device *, 3243 int type); 3244 3245 /** 3246 * process_capture_request: 3247 * 3248 * Send a new capture request to the HAL. The HAL should not return from 3249 * this call until it is ready to accept the next request to process. Only 3250 * one call to process_capture_request() will be made at a time by the 3251 * framework, and the calls will all be from the same thread. The next call 3252 * to process_capture_request() will be made as soon as a new request and 3253 * its associated buffers are available. In a normal preview scenario, this 3254 * means the function will be called again by the framework almost 3255 * instantly. 3256 * 3257 * The actual request processing is asynchronous, with the results of 3258 * capture being returned by the HAL through the process_capture_result() 3259 * call. This call requires the result metadata to be available, but output 3260 * buffers may simply provide sync fences to wait on. Multiple requests are 3261 * expected to be in flight at once, to maintain full output frame rate. 3262 * 3263 * The framework retains ownership of the request structure. It is only 3264 * guaranteed to be valid during this call. The HAL device must make copies 3265 * of the information it needs to retain for the capture processing. The HAL 3266 * is responsible for waiting on and closing the buffers' fences and 3267 * returning the buffer handles to the framework. 3268 * 3269 * The HAL must write the file descriptor for the input buffer's release 3270 * sync fence into input_buffer->release_fence, if input_buffer is not 3271 * NULL. If the HAL returns -1 for the input buffer release sync fence, the 3272 * framework is free to immediately reuse the input buffer. Otherwise, the 3273 * framework will wait on the sync fence before refilling and reusing the 3274 * input buffer. 3275 * 3276 * >= CAMERA_DEVICE_API_VERSION_3_2: 3277 * 3278 * The input/output buffers provided by the framework in each request 3279 * may be brand new (having never before seen by the HAL). 3280 * 3281 * ------------------------------------------------------------------------ 3282 * Performance considerations: 3283 * 3284 * Handling a new buffer should be extremely lightweight and there should be 3285 * no frame rate degradation or frame jitter introduced. 3286 * 3287 * This call must return fast enough to ensure that the requested frame 3288 * rate can be sustained, especially for streaming cases (post-processing 3289 * quality settings set to FAST). The HAL should return this call in 1 3290 * frame interval, and must return from this call in 4 frame intervals. 3291 * 3292 * Return values: 3293 * 3294 * 0: On a successful start to processing the capture request 3295 * 3296 * -EINVAL: If the input is malformed (the settings are NULL when not 3297 * allowed, invalid physical camera settings, 3298 * there are 0 output buffers, etc) and capture processing 3299 * cannot start. Failures during request processing should be 3300 * handled by calling camera3_callback_ops_t.notify(). In case of 3301 * this error, the framework will retain responsibility for the 3302 * stream buffers' fences and the buffer handles; the HAL should 3303 * not close the fences or return these buffers with 3304 * process_capture_result. 3305 * 3306 * -ENODEV: If the camera device has encountered a serious error. After this 3307 * error is returned, only the close() method can be successfully 3308 * called by the framework. 3309 * 3310 */ 3311 int (*process_capture_request)(const struct camera3_device *, 3312 camera3_capture_request_t *request); 3313 3314 /********************************************************************** 3315 * Miscellaneous methods 3316 */ 3317 3318 /** 3319 * get_metadata_vendor_tag_ops: 3320 * 3321 * Get methods to query for vendor extension metadata tag information. The 3322 * HAL should fill in all the vendor tag operation methods, or leave ops 3323 * unchanged if no vendor tags are defined. 3324 * 3325 * The definition of vendor_tag_query_ops_t can be found in 3326 * system/media/camera/include/system/camera_metadata.h. 3327 * 3328 * >= CAMERA_DEVICE_API_VERSION_3_2: 3329 * DEPRECATED. This function has been deprecated and should be set to 3330 * NULL by the HAL. Please implement get_vendor_tag_ops in camera_common.h 3331 * instead. 3332 */ 3333 void (*get_metadata_vendor_tag_ops)(const struct camera3_device*, 3334 vendor_tag_query_ops_t* ops); 3335 3336 /** 3337 * dump: 3338 * 3339 * Print out debugging state for the camera device. This will be called by 3340 * the framework when the camera service is asked for a debug dump, which 3341 * happens when using the dumpsys tool, or when capturing a bugreport. 3342 * 3343 * The passed-in file descriptor can be used to write debugging text using 3344 * dprintf() or write(). The text should be in ASCII encoding only. 3345 * 3346 * Performance requirements: 3347 * 3348 * This must be a non-blocking call. The HAL should return from this call 3349 * in 1ms, must return from this call in 10ms. This call must avoid 3350 * deadlocks, as it may be called at any point during camera operation. 3351 * Any synchronization primitives used (such as mutex locks or semaphores) 3352 * should be acquired with a timeout. 3353 */ 3354 void (*dump)(const struct camera3_device *, int fd); 3355 3356 /** 3357 * flush: 3358 * 3359 * Flush all currently in-process captures and all buffers in the pipeline 3360 * on the given device. The framework will use this to dump all state as 3361 * quickly as possible in order to prepare for a configure_streams() call. 3362 * 3363 * No buffers are required to be successfully returned, so every buffer 3364 * held at the time of flush() (whether successfully filled or not) may be 3365 * returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed 3366 * to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call, 3367 * provided they are successfully filled. 3368 * 3369 * All requests currently in the HAL are expected to be returned as soon as 3370 * possible. Not-in-process requests should return errors immediately. Any 3371 * interruptible hardware blocks should be stopped, and any uninterruptible 3372 * blocks should be waited on. 3373 * 3374 * flush() may be called concurrently to process_capture_request(), with the expectation that 3375 * process_capture_request will return quickly and the request submitted in that 3376 * process_capture_request call is treated like all other in-flight requests. Due to 3377 * concurrency issues, it is possible that from the HAL's point of view, a 3378 * process_capture_request() call may be started after flush has been invoked but has not 3379 * returned yet. If such a call happens before flush() returns, the HAL should treat the new 3380 * capture request like other in-flight pending requests (see #4 below). 3381 * 3382 * More specifically, the HAL must follow below requirements for various cases: 3383 * 3384 * 1. For captures that are too late for the HAL to cancel/stop, and will be 3385 * completed normally by the HAL; i.e. the HAL can send shutter/notify and 3386 * process_capture_result and buffers as normal. 3387 * 3388 * 2. For pending requests that have not done any processing, the HAL must call notify 3389 * CAMERA3_MSG_ERROR_REQUEST, and return all the output buffers with 3390 * process_capture_result in the error state (CAMERA3_BUFFER_STATUS_ERROR). 3391 * The HAL must not place the release fence into an error state, instead, 3392 * the release fences must be set to the acquire fences passed by the framework, 3393 * or -1 if they have been waited on by the HAL already. This is also the path 3394 * to follow for any captures for which the HAL already called notify() with 3395 * CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers for. 3396 * After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only process_capture_results with 3397 * buffers in CAMERA3_BUFFER_STATUS_ERROR are allowed. No further notifys or 3398 * process_capture_result with non-null metadata is allowed. 3399 * 3400 * 3. For partially completed pending requests that will not have all the output 3401 * buffers or perhaps missing metadata, the HAL should follow below: 3402 * 3403 * 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected result 3404 * metadata (i.e. one or more partial metadata) won't be available for the capture. 3405 * 3406 * 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that won't 3407 * be produced for the capture. 3408 * 3409 * 3.3 Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp before 3410 * any buffers/metadata are returned with process_capture_result. 3411 * 3412 * 3.4 For captures that will produce some results, the HAL must not call 3413 * CAMERA3_MSG_ERROR_REQUEST, since that indicates complete failure. 3414 * 3415 * 3.5. Valid buffers/metadata should be passed to the framework as normal. 3416 * 3417 * 3.6. Failed buffers should be returned to the framework as described for case 2. 3418 * But failed buffers do not have to follow the strict ordering valid buffers do, 3419 * and may be out-of-order with respect to valid buffers. For example, if buffers 3420 * A, B, C, D, E are sent, D and E are failed, then A, E, B, D, C is an acceptable 3421 * return order. 3422 * 3423 * 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is sufficient, no 3424 * need to call process_capture_result with NULL metadata or equivalent. 3425 * 3426 * 4. If a flush() is invoked while a process_capture_request() invocation is active, that 3427 * process call should return as soon as possible. In addition, if a process_capture_request() 3428 * call is made after flush() has been invoked but before flush() has returned, the 3429 * capture request provided by the late process_capture_request call should be treated like 3430 * a pending request in case #2 above. 3431 * 3432 * flush() should only return when there are no more outstanding buffers or 3433 * requests left in the HAL. The framework may call configure_streams (as 3434 * the HAL state is now quiesced) or may issue new requests. 3435 * 3436 * Note that it's sufficient to only support fully-succeeded and fully-failed result cases. 3437 * However, it is highly desirable to support the partial failure cases as well, as it 3438 * could help improve the flush call overall performance. 3439 * 3440 * Performance requirements: 3441 * 3442 * The HAL should return from this call in 100ms, and must return from this 3443 * call in 1000ms. And this call must not be blocked longer than pipeline 3444 * latency (see S7 for definition). 3445 * 3446 * Version information: 3447 * 3448 * only available if device version >= CAMERA_DEVICE_API_VERSION_3_1. 3449 * 3450 * Return values: 3451 * 3452 * 0: On a successful flush of the camera HAL. 3453 * 3454 * -EINVAL: If the input is malformed (the device is not valid). 3455 * 3456 * -ENODEV: If the camera device has encountered a serious error. After this 3457 * error is returned, only the close() method can be successfully 3458 * called by the framework. 3459 */ 3460 int (*flush)(const struct camera3_device *); 3461 3462 /** 3463 * signal_stream_flush: 3464 * 3465 * <= CAMERA_DEVICE_API_VERISON_3_5: 3466 * 3467 * Not defined and must be NULL 3468 * 3469 * >= CAMERA_DEVICE_API_VERISON_3_6: 3470 * 3471 * Signaling HAL camera service is about to perform configure_streams() call 3472 * and HAL must return all buffers of designated streams. HAL must finish 3473 * inflight requests normally and return all buffers belonging to the 3474 * designated streams through process_capture_result() or 3475 * return_stream_buffers() API in a timely manner, or camera service will run 3476 * into a fatal error. 3477 * 3478 * Note that this call serves as an optional hint and camera service may 3479 * skip calling this if all buffers are already returned. 3480 * 3481 */ 3482 void (*signal_stream_flush)(const struct camera3_device*, 3483 uint32_t num_streams, 3484 const camera3_stream_t* const* streams); 3485 3486 /** 3487 * is_reconfiguration_required: 3488 * 3489 * <= CAMERA_DEVICE_API_VERISON_3_5: 3490 * 3491 * Not defined and must be NULL 3492 * 3493 * >= CAMERA_DEVICE_API_VERISON_3_6: 3494 * 3495 * Check whether complete stream reconfiguration is required for possible new session 3496 * parameter values. 3497 * 3498 * This method must be called by the camera framework in case the client changes 3499 * the value of any advertised session parameters. Depending on the specific values 3500 * the HAL can decide whether a complete stream reconfiguration is required. In case 3501 * the HAL returns -ENVAL, the camera framework must skip the internal reconfiguration. 3502 * In case Hal returns 0, the framework must reconfigure the streams and pass the 3503 * new session parameter values accordingly. 3504 * This call may be done by the framework some time before the request with new parameters 3505 * is submitted to the HAL, and the request may be cancelled before it ever gets submitted. 3506 * Therefore, the HAL must not use this query as an indication to change its behavior in any 3507 * way. 3508 * ------------------------------------------------------------------------ 3509 * 3510 * Preconditions: 3511 * 3512 * The framework can call this method at any time after active 3513 * session configuration. There must be no impact on the performance of 3514 * pending camera requests in any way. In particular there must not be 3515 * any glitches or delays during normal camera streaming. 3516 * 3517 * Performance requirements: 3518 * HW and SW camera settings must not be changed and there must not be 3519 * a user-visible impact on camera performance. 3520 * 3521 * @param oldSessionParams The currently applied session parameters. 3522 * @param newSessionParams The new session parameters set by client. 3523 * 3524 * @return Status Status code for the operation, one of: 3525 * 0: In case the stream reconfiguration is required 3526 * 3527 * -EINVAL: In case the stream reconfiguration is not required. 3528 * 3529 * -ENOSYS: In case the camera device does not support the 3530 * reconfiguration query. 3531 */ 3532 int (*is_reconfiguration_required)(const struct camera3_device*, 3533 const camera_metadata_t* old_session_params, 3534 const camera_metadata_t* new_session_params); 3535 3536 /* reserved for future use */ 3537 void *reserved[6]; 3538 } camera3_device_ops_t; 3539 3540 /********************************************************************** 3541 * 3542 * Camera device definition 3543 * 3544 */ 3545 typedef struct camera3_device { 3546 /** 3547 * common.version must equal CAMERA_DEVICE_API_VERSION_3_0 to identify this 3548 * device as implementing version 3.0 of the camera device HAL. 3549 * 3550 * Performance requirements: 3551 * 3552 * Camera open (common.module->common.methods->open) should return in 200ms, and must return 3553 * in 500ms. 3554 * Camera close (common.close) should return in 200ms, and must return in 500ms. 3555 * 3556 */ 3557 hw_device_t common; 3558 camera3_device_ops_t *ops; 3559 void *priv; 3560 } camera3_device_t; 3561 3562 __END_DECLS 3563 3564 #endif /* #ifdef ANDROID_INCLUDE_CAMERA3_H */ 3565
