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