1<?xml version="1.0" encoding="utf-8"?> 2<!-- Copyright (C) 2012 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15--> 16<metadata xmlns="http://schemas.android.com/service/camera/metadata/" 17xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 18xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata_definitions.xsd"> 19 20 <tags> 21 <tag id="BC"> 22 Needed for backwards compatibility with old Java API 23 </tag> 24 <tag id="V1"> 25 New features for first camera 2 release (API1) 26 </tag> 27 <tag id="RAW"> 28 Needed for useful RAW image processing and DNG file support 29 </tag> 30 <tag id="HAL2"> 31 Entry is only used by camera device legacy HAL 2.x 32 </tag> 33 <tag id="FULL"> 34 Entry is required for full hardware level devices, and optional for other hardware levels 35 </tag> 36 <tag id="DEPTH"> 37 Entry is required for the depth capability. 38 </tag> 39 <tag id="REPROC"> 40 Entry is required for the YUV or PRIVATE reprocessing capability. 41 </tag> 42 <tag id="LOGICALCAMERA"> 43 Entry is required for logical multi-camera capability. 44 </tag> 45 <tag id="HEIC"> 46 Entry is required for devices with HEIC (High Efficiency Image Format) support. 47 </tag> 48 <tag id="FUTURE"> 49 Entry is under-specified and is not required for now. This is for book-keeping purpose, 50 do not implement or use it, it may be revised for future. 51 </tag> 52 </tags> 53 54 <types> 55 <typedef name="pairFloatFloat"> 56 <language name="java">android.util.Pair<Float,Float></language> 57 </typedef> 58 <typedef name="pairDoubleDouble"> 59 <language name="java">android.util.Pair<Double,Double></language> 60 </typedef> 61 <typedef name="rectangle"> 62 <language name="java">android.graphics.Rect</language> 63 </typedef> 64 <typedef name="size"> 65 <language name="java">android.util.Size</language> 66 </typedef> 67 <typedef name="string"> 68 <language name="java">String</language> 69 </typedef> 70 <typedef name="boolean"> 71 <language name="java">boolean</language> 72 </typedef> 73 <typedef name="imageFormat"> 74 <language name="java">int</language> 75 </typedef> 76 <typedef name="streamConfigurationMap"> 77 <language name="java">android.hardware.camera2.params.StreamConfigurationMap</language> 78 </typedef> 79 <typedef name="streamConfiguration"> 80 <language name="java">android.hardware.camera2.params.StreamConfiguration</language> 81 </typedef> 82 <typedef name="recommendedStreamConfiguration"> 83 <language 84 name="java">android.hardware.camera2.params.RecommendedStreamConfiguration</language> 85 </typedef> 86 <typedef name="streamConfigurationDuration"> 87 <language name="java">android.hardware.camera2.params.StreamConfigurationDuration</language> 88 </typedef> 89 <typedef name="face"> 90 <language name="java">android.hardware.camera2.params.Face</language> 91 </typedef> 92 <typedef name="meteringRectangle"> 93 <language name="java">android.hardware.camera2.params.MeteringRectangle</language> 94 </typedef> 95 <typedef name="rangeFloat"> 96 <language name="java">android.util.Range<Float></language> 97 </typedef> 98 <typedef name="rangeInt"> 99 <language name="java">android.util.Range<Integer></language> 100 </typedef> 101 <typedef name="rangeLong"> 102 <language name="java">android.util.Range<Long></language> 103 </typedef> 104 <typedef name="colorSpaceTransform"> 105 <language name="java">android.hardware.camera2.params.ColorSpaceTransform</language> 106 </typedef> 107 <typedef name="rggbChannelVector"> 108 <language name="java">android.hardware.camera2.params.RggbChannelVector</language> 109 </typedef> 110 <typedef name="blackLevelPattern"> 111 <language name="java">android.hardware.camera2.params.BlackLevelPattern</language> 112 </typedef> 113 <typedef name="enumList"> 114 <language name="java">int</language> 115 </typedef> 116 <typedef name="sizeF"> 117 <language name="java">android.util.SizeF</language> 118 </typedef> 119 <typedef name="point"> 120 <language name="java">android.graphics.Point</language> 121 </typedef> 122 <typedef name="tonemapCurve"> 123 <language name="java">android.hardware.camera2.params.TonemapCurve</language> 124 </typedef> 125 <typedef name="lensShadingMap"> 126 <language name="java">android.hardware.camera2.params.LensShadingMap</language> 127 </typedef> 128 <typedef name="location"> 129 <language name="java">android.location.Location</language> 130 </typedef> 131 <typedef name="highSpeedVideoConfiguration"> 132 <language name="java">android.hardware.camera2.params.HighSpeedVideoConfiguration</language> 133 </typedef> 134 <typedef name="reprocessFormatsMap"> 135 <language name="java">android.hardware.camera2.params.ReprocessFormatsMap</language> 136 </typedef> 137 <typedef name="oisSample"> 138 <language name="java">android.hardware.camera2.params.OisSample</language> 139 </typedef> 140 <typedef name="mandatoryStreamCombination"> 141 <language name="java">android.hardware.camera2.params.MandatoryStreamCombination</language> 142 </typedef> 143 <typedef name="capability"> 144 <language name="java">android.hardware.camera2.params.Capability</language> 145 </typedef> 146 <typedef name="multiResolutionStreamConfigurationMap"> 147 <language name="java">android.hardware.camera2.params.MultiResolutionStreamConfigurationMap</language> 148 </typedef> 149 <typedef name="deviceStateSensorOrientationMap"> 150 <language name="java">android.hardware.camera2.params.DeviceStateSensorOrientationMap</language> 151 </typedef> 152 </types> 153 154 <namespace name="android"> 155 <section name="colorCorrection"> 156 <controls> 157 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 158 <enum> 159 <value>TRANSFORM_MATRIX 160 <notes>Use the android.colorCorrection.transform matrix 161 and android.colorCorrection.gains to do color conversion. 162 163 All advanced white balance adjustments (not specified 164 by our white balance pipeline) must be disabled. 165 166 If AWB is enabled with `android.control.awbMode != OFF`, then 167 TRANSFORM_MATRIX is ignored. The camera device will override 168 this value to either FAST or HIGH_QUALITY. 169 </notes> 170 </value> 171 <value>FAST 172 <notes>Color correction processing must not slow down 173 capture rate relative to sensor raw output. 174 175 Advanced white balance adjustments above and beyond 176 the specified white balance pipeline may be applied. 177 178 If AWB is enabled with `android.control.awbMode != OFF`, then 179 the camera device uses the last frame's AWB values 180 (or defaults if AWB has never been run). 181 </notes> 182 </value> 183 <value>HIGH_QUALITY 184 <notes>Color correction processing operates at improved 185 quality but the capture rate might be reduced (relative to sensor 186 raw output rate) 187 188 Advanced white balance adjustments above and beyond 189 the specified white balance pipeline may be applied. 190 191 If AWB is enabled with `android.control.awbMode != OFF`, then 192 the camera device uses the last frame's AWB values 193 (or defaults if AWB has never been run). 194 </notes> 195 </value> 196 </enum> 197 198 <description> 199 The mode control selects how the image data is converted from the 200 sensor's native color into linear sRGB color. 201 </description> 202 <details> 203 When auto-white balance (AWB) is enabled with android.control.awbMode, this 204 control is overridden by the AWB routine. When AWB is disabled, the 205 application controls how the color mapping is performed. 206 207 We define the expected processing pipeline below. For consistency 208 across devices, this is always the case with TRANSFORM_MATRIX. 209 210 When either FAST or HIGH_QUALITY is used, the camera device may 211 do additional processing but android.colorCorrection.gains and 212 android.colorCorrection.transform will still be provided by the 213 camera device (in the results) and be roughly correct. 214 215 Switching to TRANSFORM_MATRIX and using the data provided from 216 FAST or HIGH_QUALITY will yield a picture with the same white point 217 as what was produced by the camera device in the earlier frame. 218 219 The expected processing pipeline is as follows: 220 221  222 223 The white balance is encoded by two values, a 4-channel white-balance 224 gain vector (applied in the Bayer domain), and a 3x3 color transform 225 matrix (applied after demosaic). 226 227 The 4-channel white-balance gains are defined as: 228 229 android.colorCorrection.gains = [ R G_even G_odd B ] 230 231 where `G_even` is the gain for green pixels on even rows of the 232 output, and `G_odd` is the gain for green pixels on the odd rows. 233 These may be identical for a given camera device implementation; if 234 the camera device does not support a separate gain for even/odd green 235 channels, it will use the `G_even` value, and write `G_odd` equal to 236 `G_even` in the output result metadata. 237 238 The matrices for color transforms are defined as a 9-entry vector: 239 240 android.colorCorrection.transform = [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ] 241 242 which define a transform from input sensor colors, `P_in = [ r g b ]`, 243 to output linear sRGB, `P_out = [ r' g' b' ]`, 244 245 with colors as follows: 246 247 r' = I0r + I1g + I2b 248 g' = I3r + I4g + I5b 249 b' = I6r + I7g + I8b 250 251 Both the input and output value ranges must match. Overflow/underflow 252 values are clipped to fit within the range. 253 </details> 254 <hal_details> 255 HAL must support both FAST and HIGH_QUALITY if color correction control is available 256 on the camera device, but the underlying implementation can be the same for both modes. 257 That is, if the highest quality implementation on the camera device does not slow down 258 capture rate, then FAST and HIGH_QUALITY should generate the same output. 259 </hal_details> 260 </entry> 261 <entry name="transform" type="rational" visibility="public" 262 type_notes="3x3 rational matrix in row-major order" 263 container="array" typedef="colorSpaceTransform" hwlevel="full"> 264 <array> 265 <size>3</size> 266 <size>3</size> 267 </array> 268 <description>A color transform matrix to use to transform 269 from sensor RGB color space to output linear sRGB color space. 270 </description> 271 <units>Unitless scale factors</units> 272 <details>This matrix is either set by the camera device when the request 273 android.colorCorrection.mode is not TRANSFORM_MATRIX, or 274 directly by the application in the request when the 275 android.colorCorrection.mode is TRANSFORM_MATRIX. 276 277 In the latter case, the camera device may round the matrix to account 278 for precision issues; the final rounded matrix should be reported back 279 in this matrix result metadata. The transform should keep the magnitude 280 of the output color values within `[0, 1.0]` (assuming input color 281 values is within the normalized range `[0, 1.0]`), or clipping may occur. 282 283 The valid range of each matrix element varies on different devices, but 284 values within [-1.5, 3.0] are guaranteed not to be clipped. 285 </details> 286 </entry> 287 <entry name="gains" type="float" visibility="public" 288 type_notes="A 1D array of floats for 4 color channel gains" 289 container="array" typedef="rggbChannelVector" hwlevel="full"> 290 <array> 291 <size>4</size> 292 </array> 293 <description>Gains applying to Bayer raw color channels for 294 white-balance.</description> 295 <units>Unitless gain factors</units> 296 <details> 297 These per-channel gains are either set by the camera device 298 when the request android.colorCorrection.mode is not 299 TRANSFORM_MATRIX, or directly by the application in the 300 request when the android.colorCorrection.mode is 301 TRANSFORM_MATRIX. 302 303 The gains in the result metadata are the gains actually 304 applied by the camera device to the current frame. 305 306 The valid range of gains varies on different devices, but gains 307 between [1.0, 3.0] are guaranteed not to be clipped. Even if a given 308 device allows gains below 1.0, this is usually not recommended because 309 this can create color artifacts. 310 </details> 311 <hal_details> 312 The 4-channel white-balance gains are defined in 313 the order of `[R G_even G_odd B]`, where `G_even` is the gain 314 for green pixels on even rows of the output, and `G_odd` 315 is the gain for green pixels on the odd rows. 316 317 If a HAL does not support a separate gain for even/odd green 318 channels, it must use the `G_even` value, and write 319 `G_odd` equal to `G_even` in the output result metadata. 320 </hal_details> 321 </entry> 322 <entry name="aberrationMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 323 <enum> 324 <value>OFF 325 <notes> 326 No aberration correction is applied. 327 </notes> 328 </value> 329 <value>FAST 330 <notes> 331 Aberration correction will not slow down capture rate 332 relative to sensor raw output. 333 </notes> 334 </value> 335 <value>HIGH_QUALITY 336 <notes> 337 Aberration correction operates at improved quality but the capture rate might be 338 reduced (relative to sensor raw output rate) 339 </notes> 340 </value> 341 </enum> 342 <description> 343 Mode of operation for the chromatic aberration correction algorithm. 344 </description> 345 <range>android.colorCorrection.availableAberrationModes</range> 346 <details> 347 Chromatic (color) aberration is caused by the fact that different wavelengths of light 348 can not focus on the same point after exiting from the lens. This metadata defines 349 the high level control of chromatic aberration correction algorithm, which aims to 350 minimize the chromatic artifacts that may occur along the object boundaries in an 351 image. 352 353 FAST/HIGH_QUALITY both mean that camera device determined aberration 354 correction will be applied. HIGH_QUALITY mode indicates that the camera device will 355 use the highest-quality aberration correction algorithms, even if it slows down 356 capture rate. FAST means the camera device will not slow down capture rate when 357 applying aberration correction. 358 359 LEGACY devices will always be in FAST mode. 360 </details> 361 </entry> 362 </controls> 363 <dynamic> 364 <clone entry="android.colorCorrection.mode" kind="controls"> 365 </clone> 366 <clone entry="android.colorCorrection.transform" kind="controls"> 367 </clone> 368 <clone entry="android.colorCorrection.gains" kind="controls"> 369 </clone> 370 <clone entry="android.colorCorrection.aberrationMode" kind="controls"> 371 </clone> 372 </dynamic> 373 <static> 374 <entry name="availableAberrationModes" type="byte" visibility="public" 375 type_notes="list of enums" container="array" typedef="enumList" hwlevel="legacy"> 376 <array> 377 <size>n</size> 378 </array> 379 <description> 380 List of aberration correction modes for android.colorCorrection.aberrationMode that are 381 supported by this camera device. 382 </description> 383 <range>Any value listed in android.colorCorrection.aberrationMode</range> 384 <details> 385 This key lists the valid modes for android.colorCorrection.aberrationMode. If no 386 aberration correction modes are available for a device, this list will solely include 387 OFF mode. All camera devices will support either OFF or FAST mode. 388 389 Camera devices that support the MANUAL_POST_PROCESSING capability will always list 390 OFF mode. This includes all FULL level devices. 391 392 LEGACY devices will always only support FAST mode. 393 </details> 394 <hal_details> 395 HAL must support both FAST and HIGH_QUALITY if chromatic aberration control is available 396 on the camera device, but the underlying implementation can be the same for both modes. 397 That is, if the highest quality implementation on the camera device does not slow down 398 capture rate, then FAST and HIGH_QUALITY will generate the same output. 399 </hal_details> 400 <tag id="V1" /> 401 </entry> 402 </static> 403 </section> 404 <section name="control"> 405 <controls> 406 <entry name="aeAntibandingMode" type="byte" visibility="public" 407 enum="true" hwlevel="legacy"> 408 <enum> 409 <value>OFF 410 <notes> 411 The camera device will not adjust exposure duration to 412 avoid banding problems. 413 </notes> 414 </value> 415 <value>50HZ 416 <notes> 417 The camera device will adjust exposure duration to 418 avoid banding problems with 50Hz illumination sources. 419 </notes> 420 </value> 421 <value>60HZ 422 <notes> 423 The camera device will adjust exposure duration to 424 avoid banding problems with 60Hz illumination 425 sources. 426 </notes> 427 </value> 428 <value>AUTO 429 <notes> 430 The camera device will automatically adapt its 431 antibanding routine to the current illumination 432 condition. This is the default mode if AUTO is 433 available on given camera device. 434 </notes> 435 </value> 436 </enum> 437 <description> 438 The desired setting for the camera device's auto-exposure 439 algorithm's antibanding compensation. 440 </description> 441 <range> 442 android.control.aeAvailableAntibandingModes 443 </range> 444 <details> 445 Some kinds of lighting fixtures, such as some fluorescent 446 lights, flicker at the rate of the power supply frequency 447 (60Hz or 50Hz, depending on country). While this is 448 typically not noticeable to a person, it can be visible to 449 a camera device. If a camera sets its exposure time to the 450 wrong value, the flicker may become visible in the 451 viewfinder as flicker or in a final captured image, as a 452 set of variable-brightness bands across the image. 453 454 Therefore, the auto-exposure routines of camera devices 455 include antibanding routines that ensure that the chosen 456 exposure value will not cause such banding. The choice of 457 exposure time depends on the rate of flicker, which the 458 camera device can detect automatically, or the expected 459 rate can be selected by the application using this 460 control. 461 462 A given camera device may not support all of the possible 463 options for the antibanding mode. The 464 android.control.aeAvailableAntibandingModes key contains 465 the available modes for a given camera device. 466 467 AUTO mode is the default if it is available on given 468 camera device. When AUTO mode is not available, the 469 default will be either 50HZ or 60HZ, and both 50HZ 470 and 60HZ will be available. 471 472 If manual exposure control is enabled (by setting 473 android.control.aeMode or android.control.mode to OFF), 474 then this setting has no effect, and the application must 475 ensure it selects exposure times that do not cause banding 476 issues. The android.statistics.sceneFlicker key can assist 477 the application in this. 478 </details> 479 <hal_details> 480 For all capture request templates, this field must be set 481 to AUTO if AUTO mode is available. If AUTO is not available, 482 the default must be either 50HZ or 60HZ, and both 50HZ and 483 60HZ must be available. 484 485 If manual exposure control is enabled (by setting 486 android.control.aeMode or android.control.mode to OFF), 487 then the exposure values provided by the application must not be 488 adjusted for antibanding. 489 </hal_details> 490 <tag id="BC" /> 491 </entry> 492 <entry name="aeExposureCompensation" type="int32" visibility="public" hwlevel="legacy"> 493 <description>Adjustment to auto-exposure (AE) target image 494 brightness.</description> 495 <units>Compensation steps</units> 496 <range>android.control.aeCompensationRange</range> 497 <details> 498 The adjustment is measured as a count of steps, with the 499 step size defined by android.control.aeCompensationStep and the 500 allowed range by android.control.aeCompensationRange. 501 502 For example, if the exposure value (EV) step is 0.333, '6' 503 will mean an exposure compensation of +2 EV; -3 will mean an 504 exposure compensation of -1 EV. One EV represents a doubling 505 of image brightness. Note that this control will only be 506 effective if android.control.aeMode `!=` OFF. This control 507 will take effect even when android.control.aeLock `== true`. 508 509 In the event of exposure compensation value being changed, camera device 510 may take several frames to reach the newly requested exposure target. 511 During that time, android.control.aeState field will be in the SEARCHING 512 state. Once the new exposure target is reached, android.control.aeState will 513 change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or 514 FLASH_REQUIRED (if the scene is too dark for still capture). 515 </details> 516 <tag id="BC" /> 517 </entry> 518 <entry name="aeLock" type="byte" visibility="public" enum="true" 519 typedef="boolean" hwlevel="legacy"> 520 <enum> 521 <value>OFF 522 <notes>Auto-exposure lock is disabled; the AE algorithm 523 is free to update its parameters.</notes></value> 524 <value>ON 525 <notes>Auto-exposure lock is enabled; the AE algorithm 526 must not update the exposure and sensitivity parameters 527 while the lock is active. 528 529 android.control.aeExposureCompensation setting changes 530 will still take effect while auto-exposure is locked. 531 532 Some rare LEGACY devices may not support 533 this, in which case the value will always be overridden to OFF. 534 </notes></value> 535 </enum> 536 <description>Whether auto-exposure (AE) is currently locked to its latest 537 calculated values.</description> 538 <details> 539 When set to `true` (ON), the AE algorithm is locked to its latest parameters, 540 and will not change exposure settings until the lock is set to `false` (OFF). 541 542 Note that even when AE is locked, the flash may be fired if 543 the android.control.aeMode is ON_AUTO_FLASH / 544 ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE. 545 546 When android.control.aeExposureCompensation is changed, even if the AE lock 547 is ON, the camera device will still adjust its exposure value. 548 549 If AE precapture is triggered (see android.control.aePrecaptureTrigger) 550 when AE is already locked, the camera device will not change the exposure time 551 (android.sensor.exposureTime) and sensitivity (android.sensor.sensitivity) 552 parameters. The flash may be fired if the android.control.aeMode 553 is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the 554 android.control.aeMode is ON_ALWAYS_FLASH, the scene may become overexposed. 555 Similarly, AE precapture trigger CANCEL has no effect when AE is already locked. 556 557 When an AE precapture sequence is triggered, AE unlock will not be able to unlock 558 the AE if AE is locked by the camera device internally during precapture metering 559 sequence In other words, submitting requests with AE unlock has no effect for an 560 ongoing precapture metering sequence. Otherwise, the precapture metering sequence 561 will never succeed in a sequence of preview requests where AE lock is always set 562 to `false`. 563 564 Since the camera device has a pipeline of in-flight requests, the settings that 565 get locked do not necessarily correspond to the settings that were present in the 566 latest capture result received from the camera device, since additional captures 567 and AE updates may have occurred even before the result was sent out. If an 568 application is switching between automatic and manual control and wishes to eliminate 569 any flicker during the switch, the following procedure is recommended: 570 571 1. Starting in auto-AE mode: 572 2. Lock AE 573 3. Wait for the first result to be output that has the AE locked 574 4. Copy exposure settings from that result into a request, set the request to manual AE 575 5. Submit the capture request, proceed to run manual AE as desired. 576 577 See android.control.aeState for AE lock related state transition details. 578 </details> 579 <tag id="BC" /> 580 </entry> 581 <entry name="aeMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 582 <enum> 583 <value>OFF 584 <notes> 585 The camera device's autoexposure routine is disabled. 586 587 The application-selected android.sensor.exposureTime, 588 android.sensor.sensitivity and 589 android.sensor.frameDuration are used by the camera 590 device, along with android.flash.* fields, if there's 591 a flash unit for this camera device. 592 593 Note that auto-white balance (AWB) and auto-focus (AF) 594 behavior is device dependent when AE is in OFF mode. 595 To have consistent behavior across different devices, 596 it is recommended to either set AWB and AF to OFF mode 597 or lock AWB and AF before setting AE to OFF. 598 See android.control.awbMode, android.control.afMode, 599 android.control.awbLock, and android.control.afTrigger 600 for more details. 601 602 LEGACY devices do not support the OFF mode and will 603 override attempts to use this value to ON. 604 </notes> 605 </value> 606 <value>ON 607 <notes> 608 The camera device's autoexposure routine is active, 609 with no flash control. 610 611 The application's values for 612 android.sensor.exposureTime, 613 android.sensor.sensitivity, and 614 android.sensor.frameDuration are ignored. The 615 application has control over the various 616 android.flash.* fields. 617 </notes> 618 </value> 619 <value>ON_AUTO_FLASH 620 <notes> 621 Like ON, except that the camera device also controls 622 the camera's flash unit, firing it in low-light 623 conditions. 624 625 The flash may be fired during a precapture sequence 626 (triggered by android.control.aePrecaptureTrigger) and 627 may be fired for captures for which the 628 android.control.captureIntent field is set to 629 STILL_CAPTURE 630 </notes> 631 </value> 632 <value>ON_ALWAYS_FLASH 633 <notes> 634 Like ON, except that the camera device also controls 635 the camera's flash unit, always firing it for still 636 captures. 637 638 The flash may be fired during a precapture sequence 639 (triggered by android.control.aePrecaptureTrigger) and 640 will always be fired for captures for which the 641 android.control.captureIntent field is set to 642 STILL_CAPTURE 643 </notes> 644 </value> 645 <value>ON_AUTO_FLASH_REDEYE 646 <notes> 647 Like ON_AUTO_FLASH, but with automatic red eye 648 reduction. 649 650 If deemed necessary by the camera device, a red eye 651 reduction flash will fire during the precapture 652 sequence. 653 </notes> 654 </value> 655 <value hal_version="3.3">ON_EXTERNAL_FLASH 656 <notes> 657 An external flash has been turned on. 658 659 It informs the camera device that an external flash has been turned on, and that 660 metering (and continuous focus if active) should be quickly recaculated to account 661 for the external flash. Otherwise, this mode acts like ON. 662 663 When the external flash is turned off, AE mode should be changed to one of the 664 other available AE modes. 665 666 If the camera device supports AE external flash mode, android.control.aeState must 667 be FLASH_REQUIRED after the camera device finishes AE scan and it's too dark without 668 flash. 669 </notes> 670 </value> 671 </enum> 672 <description>The desired mode for the camera device's 673 auto-exposure routine.</description> 674 <range>android.control.aeAvailableModes</range> 675 <details> 676 This control is only effective if android.control.mode is 677 AUTO. 678 679 When set to any of the ON modes, the camera device's 680 auto-exposure routine is enabled, overriding the 681 application's selected exposure time, sensor sensitivity, 682 and frame duration (android.sensor.exposureTime, 683 android.sensor.sensitivity, and 684 android.sensor.frameDuration). If one of the FLASH modes 685 is selected, the camera device's flash unit controls are 686 also overridden. 687 688 The FLASH modes are only available if the camera device 689 has a flash unit (android.flash.info.available is `true`). 690 691 If flash TORCH mode is desired, this field must be set to 692 ON or OFF, and android.flash.mode set to TORCH. 693 694 When set to any of the ON modes, the values chosen by the 695 camera device auto-exposure routine for the overridden 696 fields for a given capture will be available in its 697 CaptureResult. 698 </details> 699 <tag id="BC" /> 700 </entry> 701 <entry name="aeRegions" type="int32" visibility="public" 702 optional="true" container="array" typedef="meteringRectangle"> 703 <array> 704 <size>5</size> 705 <size>area_count</size> 706 </array> 707 <description>List of metering areas to use for auto-exposure adjustment.</description> 708 <units>Pixel coordinates within android.sensor.info.activeArraySize or 709 android.sensor.info.preCorrectionActiveArraySize depending on 710 distortion correction capability and mode</units> 711 <range>Coordinates must be between `[(0,0), (width, height))` of 712 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 713 depending on distortion correction capability and mode</range> 714 <details> 715 Not available if android.control.maxRegionsAe is 0. 716 Otherwise will always be present. 717 718 The maximum number of regions supported by the device is determined by the value 719 of android.control.maxRegionsAe. 720 721 For devices not supporting android.distortionCorrection.mode control, the coordinate 722 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 723 the top-left pixel in the active pixel array, and 724 (android.sensor.info.activeArraySize.width - 1, 725 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 726 active pixel array. 727 728 For devices supporting android.distortionCorrection.mode control, the coordinate 729 system depends on the mode being set. 730 When the distortion correction mode is OFF, the coordinate system follows 731 android.sensor.info.preCorrectionActiveArraySize, with 732 `(0, 0)` being the top-left pixel of the pre-correction active array, and 733 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 734 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 735 pixel in the pre-correction active pixel array. 736 When the distortion correction mode is not OFF, the coordinate system follows 737 android.sensor.info.activeArraySize, with 738 `(0, 0)` being the top-left pixel of the active array, and 739 (android.sensor.info.activeArraySize.width - 1, 740 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 741 active pixel array. 742 743 The weight must be within `[0, 1000]`, and represents a weight 744 for every pixel in the area. This means that a large metering area 745 with the same weight as a smaller area will have more effect in 746 the metering result. Metering areas can partially overlap and the 747 camera device will add the weights in the overlap region. 748 749 The weights are relative to weights of other exposure metering regions, so if only one 750 region is used, all non-zero weights will have the same effect. A region with 0 751 weight is ignored. 752 753 If all regions have 0 weight, then no specific metering area needs to be used by the 754 camera device. 755 756 If the metering region is outside the used android.scaler.cropRegion returned in 757 capture result metadata, the camera device will ignore the sections outside the crop 758 region and output only the intersection rectangle as the metering region in the result 759 metadata. If the region is entirely outside the crop region, it will be ignored and 760 not reported in the result metadata. 761 762 Starting from API level 30, the coordinate system of activeArraySize or 763 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 764 pre-zoom field of view. This means that the same aeRegions values at different 765 android.control.zoomRatio represent different parts of the scene. The aeRegions 766 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 767 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 768 aeRegions at different android.scaler.cropRegion still represent the same parts of the 769 scene as they do before. See android.control.zoomRatio for details. Whether to use 770 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 771 mode. 772 773 For camera devices with the 774 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 775 capability, 776 android.sensor.info.activeArraySizeMaximumResolution / 777 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 778 coordinate system for requests where android.sensor.pixelMode is set to 779 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 780 </details> 781 <ndk_details> 782 The data representation is `int[5 * area_count]`. 783 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 784 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 785 ymax. 786 </ndk_details> 787 <hal_details> 788 The HAL level representation of MeteringRectangle[] is a 789 int[5 * area_count]. 790 Every five elements represent a metering region of 791 (xmin, ymin, xmax, ymax, weight). 792 The rectangle is defined to be inclusive on xmin and ymin, but 793 exclusive on xmax and ymax. 794 HAL must always report metering regions in the coordinate system of pre-correction 795 active array. 796 </hal_details> 797 <tag id="BC" /> 798 </entry> 799 <entry name="aeTargetFpsRange" type="int32" visibility="public" 800 container="array" typedef="rangeInt" hwlevel="legacy"> 801 <array> 802 <size>2</size> 803 </array> 804 <description>Range over which the auto-exposure routine can 805 adjust the capture frame rate to maintain good 806 exposure.</description> 807 <units>Frames per second (FPS)</units> 808 <range>Any of the entries in android.control.aeAvailableTargetFpsRanges</range> 809 <details>Only constrains auto-exposure (AE) algorithm, not 810 manual control of android.sensor.exposureTime and 811 android.sensor.frameDuration.</details> 812 <tag id="BC" /> 813 </entry> 814 <entry name="aePrecaptureTrigger" type="byte" visibility="public" 815 enum="true" hwlevel="limited"> 816 <enum> 817 <value>IDLE 818 <notes>The trigger is idle.</notes> 819 </value> 820 <value>START 821 <notes>The precapture metering sequence will be started 822 by the camera device. 823 824 The exact effect of the precapture trigger depends on 825 the current AE mode and state.</notes> 826 </value> 827 <value>CANCEL 828 <notes>The camera device will cancel any currently active or completed 829 precapture metering sequence, the auto-exposure routine will return to its 830 initial state.</notes> 831 </value> 832 </enum> 833 <description>Whether the camera device will trigger a precapture 834 metering sequence when it processes this request.</description> 835 <details>This entry is normally set to IDLE, or is not 836 included at all in the request settings. When included and 837 set to START, the camera device will trigger the auto-exposure (AE) 838 precapture metering sequence. 839 840 When set to CANCEL, the camera device will cancel any active 841 precapture metering trigger, and return to its initial AE state. 842 If a precapture metering sequence is already completed, and the camera 843 device has implicitly locked the AE for subsequent still capture, the 844 CANCEL trigger will unlock the AE and return to its initial AE state. 845 846 The precapture sequence should be triggered before starting a 847 high-quality still capture for final metering decisions to 848 be made, and for firing pre-capture flash pulses to estimate 849 scene brightness and required final capture flash power, when 850 the flash is enabled. 851 852 Normally, this entry should be set to START for only a 853 single request, and the application should wait until the 854 sequence completes before starting a new one. 855 856 When a precapture metering sequence is finished, the camera device 857 may lock the auto-exposure routine internally to be able to accurately expose the 858 subsequent still capture image (`android.control.captureIntent == STILL_CAPTURE`). 859 For this case, the AE may not resume normal scan if no subsequent still capture is 860 submitted. To ensure that the AE routine restarts normal scan, the application should 861 submit a request with `android.control.aeLock == true`, followed by a request 862 with `android.control.aeLock == false`, if the application decides not to submit a 863 still capture request after the precapture sequence completes. Alternatively, for 864 API level 23 or newer devices, the CANCEL can be used to unlock the camera device 865 internally locked AE if the application doesn't submit a still capture request after 866 the AE precapture trigger. Note that, the CANCEL was added in API level 23, and must not 867 be used in devices that have earlier API levels. 868 869 The exact effect of auto-exposure (AE) precapture trigger 870 depends on the current AE mode and state; see 871 android.control.aeState for AE precapture state transition 872 details. 873 874 On LEGACY-level devices, the precapture trigger is not supported; 875 capturing a high-resolution JPEG image will automatically trigger a 876 precapture sequence before the high-resolution capture, including 877 potentially firing a pre-capture flash. 878 879 Using the precapture trigger and the auto-focus trigger android.control.afTrigger 880 simultaneously is allowed. However, since these triggers often require cooperation between 881 the auto-focus and auto-exposure routines (for example, the may need to be enabled for a 882 focus sweep), the camera device may delay acting on a later trigger until the previous 883 trigger has been fully handled. This may lead to longer intervals between the trigger and 884 changes to android.control.aeState indicating the start of the precapture sequence, for 885 example. 886 887 If both the precapture and the auto-focus trigger are activated on the same request, then 888 the camera device will complete them in the optimal order for that device. 889 </details> 890 <hal_details> 891 The HAL must support triggering the AE precapture trigger while an AF trigger is active 892 (and vice versa), or at the same time as the AF trigger. It is acceptable for the HAL to 893 treat these as two consecutive triggers, for example handling the AF trigger and then the 894 AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, 895 to minimize the latency for converging both focus and exposure/flash usage. 896 </hal_details> 897 <tag id="BC" /> 898 </entry> 899 <entry name="afMode" type="byte" visibility="public" enum="true" 900 hwlevel="legacy"> 901 <enum> 902 <value>OFF 903 <notes>The auto-focus routine does not control the lens; 904 android.lens.focusDistance is controlled by the 905 application.</notes></value> 906 <value>AUTO 907 <notes>Basic automatic focus mode. 908 909 In this mode, the lens does not move unless 910 the autofocus trigger action is called. When that trigger 911 is activated, AF will transition to ACTIVE_SCAN, then to 912 the outcome of the scan (FOCUSED or NOT_FOCUSED). 913 914 Always supported if lens is not fixed focus. 915 916 Use android.lens.info.minimumFocusDistance to determine if lens 917 is fixed-focus. 918 919 Triggering AF_CANCEL resets the lens position to default, 920 and sets the AF state to INACTIVE.</notes></value> 921 <value>MACRO 922 <notes>Close-up focusing mode. 923 924 In this mode, the lens does not move unless the 925 autofocus trigger action is called. When that trigger is 926 activated, AF will transition to ACTIVE_SCAN, then to 927 the outcome of the scan (FOCUSED or NOT_FOCUSED). This 928 mode is optimized for focusing on objects very close to 929 the camera. 930 931 When that trigger is activated, AF will transition to 932 ACTIVE_SCAN, then to the outcome of the scan (FOCUSED or 933 NOT_FOCUSED). Triggering cancel AF resets the lens 934 position to default, and sets the AF state to 935 INACTIVE.</notes></value> 936 <value>CONTINUOUS_VIDEO 937 <notes>In this mode, the AF algorithm modifies the lens 938 position continually to attempt to provide a 939 constantly-in-focus image stream. 940 941 The focusing behavior should be suitable for good quality 942 video recording; typically this means slower focus 943 movement and no overshoots. When the AF trigger is not 944 involved, the AF algorithm should start in INACTIVE state, 945 and then transition into PASSIVE_SCAN and PASSIVE_FOCUSED 946 states as appropriate. When the AF trigger is activated, 947 the algorithm should immediately transition into 948 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 949 lens position until a cancel AF trigger is received. 950 951 Once cancel is received, the algorithm should transition 952 back to INACTIVE and resume passive scan. Note that this 953 behavior is not identical to CONTINUOUS_PICTURE, since an 954 ongoing PASSIVE_SCAN must immediately be 955 canceled.</notes></value> 956 <value>CONTINUOUS_PICTURE 957 <notes>In this mode, the AF algorithm modifies the lens 958 position continually to attempt to provide a 959 constantly-in-focus image stream. 960 961 The focusing behavior should be suitable for still image 962 capture; typically this means focusing as fast as 963 possible. When the AF trigger is not involved, the AF 964 algorithm should start in INACTIVE state, and then 965 transition into PASSIVE_SCAN and PASSIVE_FOCUSED states as 966 appropriate as it attempts to maintain focus. When the AF 967 trigger is activated, the algorithm should finish its 968 PASSIVE_SCAN if active, and then transition into 969 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 970 lens position until a cancel AF trigger is received. 971 972 When the AF cancel trigger is activated, the algorithm 973 should transition back to INACTIVE and then act as if it 974 has just been started.</notes></value> 975 <value>EDOF 976 <notes>Extended depth of field (digital focus) mode. 977 978 The camera device will produce images with an extended 979 depth of field automatically; no special focusing 980 operations need to be done before taking a picture. 981 982 AF triggers are ignored, and the AF state will always be 983 INACTIVE.</notes></value> 984 </enum> 985 <description>Whether auto-focus (AF) is currently enabled, and what 986 mode it is set to.</description> 987 <range>android.control.afAvailableModes</range> 988 <details>Only effective if android.control.mode = AUTO and the lens is not fixed focus 989 (i.e. `android.lens.info.minimumFocusDistance > 0`). Also note that 990 when android.control.aeMode is OFF, the behavior of AF is device 991 dependent. It is recommended to lock AF by using android.control.afTrigger before 992 setting android.control.aeMode to OFF, or set AF mode to OFF when AE is OFF. 993 994 If the lens is controlled by the camera device auto-focus algorithm, 995 the camera device will report the current AF status in android.control.afState 996 in result metadata.</details> 997 <hal_details> 998 When afMode is AUTO or MACRO, the lens must not move until an AF trigger is sent in a 999 request (android.control.afTrigger `==` START). After an AF trigger, the afState will end 1000 up with either FOCUSED_LOCKED or NOT_FOCUSED_LOCKED state (see 1001 android.control.afState for detailed state transitions), which indicates that the lens is 1002 locked and will not move. If camera movement (e.g. tilting camera) causes the lens to move 1003 after the lens is locked, the HAL must compensate this movement appropriately such that 1004 the same focal plane remains in focus. 1005 1006 When afMode is one of the continuous auto focus modes, the HAL is free to start a AF 1007 scan whenever it's not locked. When the lens is locked after an AF trigger 1008 (see android.control.afState for detailed state transitions), the HAL should maintain the 1009 same lock behavior as above. 1010 1011 When afMode is OFF, the application controls focus manually. The accuracy of the 1012 focus distance control depends on the android.lens.info.focusDistanceCalibration. 1013 However, the lens must not move regardless of the camera movement for any focus distance 1014 manual control. 1015 1016 To put this in concrete terms, if the camera has lens elements which may move based on 1017 camera orientation or motion (e.g. due to gravity), then the HAL must drive the lens to 1018 remain in a fixed position invariant to the camera's orientation or motion, for example, 1019 by using accelerometer measurements in the lens control logic. This is a typical issue 1020 that will arise on camera modules with open-loop VCMs. 1021 </hal_details> 1022 <tag id="BC" /> 1023 </entry> 1024 <entry name="afRegions" type="int32" visibility="public" 1025 optional="true" container="array" typedef="meteringRectangle"> 1026 <array> 1027 <size>5</size> 1028 <size>area_count</size> 1029 </array> 1030 <description>List of metering areas to use for auto-focus.</description> 1031 <units>Pixel coordinates within android.sensor.info.activeArraySize or 1032 android.sensor.info.preCorrectionActiveArraySize depending on 1033 distortion correction capability and mode</units> 1034 <range>Coordinates must be between `[(0,0), (width, height))` of 1035 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 1036 depending on distortion correction capability and mode</range> 1037 <details> 1038 Not available if android.control.maxRegionsAf is 0. 1039 Otherwise will always be present. 1040 1041 The maximum number of focus areas supported by the device is determined by the value 1042 of android.control.maxRegionsAf. 1043 1044 1045 For devices not supporting android.distortionCorrection.mode control, the coordinate 1046 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 1047 the top-left pixel in the active pixel array, and 1048 (android.sensor.info.activeArraySize.width - 1, 1049 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1050 active pixel array. 1051 1052 For devices supporting android.distortionCorrection.mode control, the coordinate 1053 system depends on the mode being set. 1054 When the distortion correction mode is OFF, the coordinate system follows 1055 android.sensor.info.preCorrectionActiveArraySize, with 1056 `(0, 0)` being the top-left pixel of the pre-correction active array, and 1057 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 1058 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 1059 pixel in the pre-correction active pixel array. 1060 When the distortion correction mode is not OFF, the coordinate system follows 1061 android.sensor.info.activeArraySize, with 1062 `(0, 0)` being the top-left pixel of the active array, and 1063 (android.sensor.info.activeArraySize.width - 1, 1064 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1065 active pixel array. 1066 1067 The weight must be within `[0, 1000]`, and represents a weight 1068 for every pixel in the area. This means that a large metering area 1069 with the same weight as a smaller area will have more effect in 1070 the metering result. Metering areas can partially overlap and the 1071 camera device will add the weights in the overlap region. 1072 1073 The weights are relative to weights of other metering regions, so if only one region 1074 is used, all non-zero weights will have the same effect. A region with 0 weight is 1075 ignored. 1076 1077 If all regions have 0 weight, then no specific metering area needs to be used by the 1078 camera device. The capture result will either be a zero weight region as well, or 1079 the region selected by the camera device as the focus area of interest. 1080 1081 If the metering region is outside the used android.scaler.cropRegion returned in 1082 capture result metadata, the camera device will ignore the sections outside the crop 1083 region and output only the intersection rectangle as the metering region in the result 1084 metadata. If the region is entirely outside the crop region, it will be ignored and 1085 not reported in the result metadata. 1086 1087 Starting from API level 30, the coordinate system of activeArraySize or 1088 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 1089 pre-zoom field of view. This means that the same afRegions values at different 1090 android.control.zoomRatio represent different parts of the scene. The afRegions 1091 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 1092 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 1093 afRegions at different android.scaler.cropRegion still represent the same parts of the 1094 scene as they do before. See android.control.zoomRatio for details. Whether to use 1095 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 1096 mode. 1097 1098 For camera devices with the 1099 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 1100 capability, android.sensor.info.activeArraySizeMaximumResolution / 1101 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 1102 coordinate system for requests where android.sensor.pixelMode is set to 1103 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 1104 </details> 1105 <ndk_details> 1106 The data representation is `int[5 * area_count]`. 1107 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 1108 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 1109 ymax. 1110 </ndk_details> 1111 <hal_details> 1112 The HAL level representation of MeteringRectangle[] is a 1113 int[5 * area_count]. 1114 Every five elements represent a metering region of 1115 (xmin, ymin, xmax, ymax, weight). 1116 The rectangle is defined to be inclusive on xmin and ymin, but 1117 exclusive on xmax and ymax. 1118 HAL must always report metering regions in the coordinate system of pre-correction 1119 active array. 1120 </hal_details> 1121 <tag id="BC" /> 1122 </entry> 1123 <entry name="afTrigger" type="byte" visibility="public" enum="true" 1124 hwlevel="legacy"> 1125 <enum> 1126 <value>IDLE 1127 <notes>The trigger is idle.</notes> 1128 </value> 1129 <value>START 1130 <notes>Autofocus will trigger now.</notes> 1131 </value> 1132 <value>CANCEL 1133 <notes>Autofocus will return to its initial 1134 state, and cancel any currently active trigger.</notes> 1135 </value> 1136 </enum> 1137 <description> 1138 Whether the camera device will trigger autofocus for this request. 1139 </description> 1140 <details>This entry is normally set to IDLE, or is not 1141 included at all in the request settings. 1142 1143 When included and set to START, the camera device will trigger the 1144 autofocus algorithm. If autofocus is disabled, this trigger has no effect. 1145 1146 When set to CANCEL, the camera device will cancel any active trigger, 1147 and return to its initial AF state. 1148 1149 Generally, applications should set this entry to START or CANCEL for only a 1150 single capture, and then return it to IDLE (or not set at all). Specifying 1151 START for multiple captures in a row means restarting the AF operation over 1152 and over again. 1153 1154 See android.control.afState for what the trigger means for each AF mode. 1155 1156 Using the autofocus trigger and the precapture trigger android.control.aePrecaptureTrigger 1157 simultaneously is allowed. However, since these triggers often require cooperation between 1158 the auto-focus and auto-exposure routines (for example, the may need to be enabled for a 1159 focus sweep), the camera device may delay acting on a later trigger until the previous 1160 trigger has been fully handled. This may lead to longer intervals between the trigger and 1161 changes to android.control.afState, for example. 1162 </details> 1163 <hal_details> 1164 The HAL must support triggering the AF trigger while an AE precapture trigger is active 1165 (and vice versa), or at the same time as the AE trigger. It is acceptable for the HAL to 1166 treat these as two consecutive triggers, for example handling the AF trigger and then the 1167 AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, 1168 to minimize the latency for converging both focus and exposure/flash usage. 1169 </hal_details> 1170 <tag id="BC" /> 1171 </entry> 1172 <entry name="awbLock" type="byte" visibility="public" enum="true" 1173 typedef="boolean" hwlevel="legacy"> 1174 <enum> 1175 <value>OFF 1176 <notes>Auto-white balance lock is disabled; the AWB 1177 algorithm is free to update its parameters if in AUTO 1178 mode.</notes></value> 1179 <value>ON 1180 <notes>Auto-white balance lock is enabled; the AWB 1181 algorithm will not update its parameters while the lock 1182 is active.</notes></value> 1183 </enum> 1184 <description>Whether auto-white balance (AWB) is currently locked to its 1185 latest calculated values.</description> 1186 <details> 1187 When set to `true` (ON), the AWB algorithm is locked to its latest parameters, 1188 and will not change color balance settings until the lock is set to `false` (OFF). 1189 1190 Since the camera device has a pipeline of in-flight requests, the settings that 1191 get locked do not necessarily correspond to the settings that were present in the 1192 latest capture result received from the camera device, since additional captures 1193 and AWB updates may have occurred even before the result was sent out. If an 1194 application is switching between automatic and manual control and wishes to eliminate 1195 any flicker during the switch, the following procedure is recommended: 1196 1197 1. Starting in auto-AWB mode: 1198 2. Lock AWB 1199 3. Wait for the first result to be output that has the AWB locked 1200 4. Copy AWB settings from that result into a request, set the request to manual AWB 1201 5. Submit the capture request, proceed to run manual AWB as desired. 1202 1203 Note that AWB lock is only meaningful when 1204 android.control.awbMode is in the AUTO mode; in other modes, 1205 AWB is already fixed to a specific setting. 1206 1207 Some LEGACY devices may not support ON; the value is then overridden to OFF. 1208 </details> 1209 <tag id="BC" /> 1210 </entry> 1211 <entry name="awbMode" type="byte" visibility="public" enum="true" 1212 hwlevel="legacy"> 1213 <enum> 1214 <value>OFF 1215 <notes> 1216 The camera device's auto-white balance routine is disabled. 1217 1218 The application-selected color transform matrix 1219 (android.colorCorrection.transform) and gains 1220 (android.colorCorrection.gains) are used by the camera 1221 device for manual white balance control. 1222 </notes> 1223 </value> 1224 <value>AUTO 1225 <notes> 1226 The camera device's auto-white balance routine is active. 1227 1228 The application's values for android.colorCorrection.transform 1229 and android.colorCorrection.gains are ignored. 1230 For devices that support the MANUAL_POST_PROCESSING capability, the 1231 values used by the camera device for the transform and gains 1232 will be available in the capture result for this request. 1233 </notes> 1234 </value> 1235 <value>INCANDESCENT 1236 <notes> 1237 The camera device's auto-white balance routine is disabled; 1238 the camera device uses incandescent light as the assumed scene 1239 illumination for white balance. 1240 1241 While the exact white balance transforms are up to the 1242 camera device, they will approximately match the CIE 1243 standard illuminant A. 1244 1245 The application's values for android.colorCorrection.transform 1246 and android.colorCorrection.gains are ignored. 1247 For devices that support the MANUAL_POST_PROCESSING capability, the 1248 values used by the camera device for the transform and gains 1249 will be available in the capture result for this request. 1250 </notes> 1251 </value> 1252 <value>FLUORESCENT 1253 <notes> 1254 The camera device's auto-white balance routine is disabled; 1255 the camera device uses fluorescent light as the assumed scene 1256 illumination for white balance. 1257 1258 While the exact white balance transforms are up to the 1259 camera device, they will approximately match the CIE 1260 standard illuminant F2. 1261 1262 The application's values for android.colorCorrection.transform 1263 and android.colorCorrection.gains are ignored. 1264 For devices that support the MANUAL_POST_PROCESSING capability, the 1265 values used by the camera device for the transform and gains 1266 will be available in the capture result for this request. 1267 </notes> 1268 </value> 1269 <value>WARM_FLUORESCENT 1270 <notes> 1271 The camera device's auto-white balance routine is disabled; 1272 the camera device uses warm fluorescent light as the assumed scene 1273 illumination for white balance. 1274 1275 While the exact white balance transforms are up to the 1276 camera device, they will approximately match the CIE 1277 standard illuminant F4. 1278 1279 The application's values for android.colorCorrection.transform 1280 and android.colorCorrection.gains are ignored. 1281 For devices that support the MANUAL_POST_PROCESSING capability, the 1282 values used by the camera device for the transform and gains 1283 will be available in the capture result for this request. 1284 </notes> 1285 </value> 1286 <value>DAYLIGHT 1287 <notes> 1288 The camera device's auto-white balance routine is disabled; 1289 the camera device uses daylight light as the assumed scene 1290 illumination for white balance. 1291 1292 While the exact white balance transforms are up to the 1293 camera device, they will approximately match the CIE 1294 standard illuminant D65. 1295 1296 The application's values for android.colorCorrection.transform 1297 and android.colorCorrection.gains are ignored. 1298 For devices that support the MANUAL_POST_PROCESSING capability, the 1299 values used by the camera device for the transform and gains 1300 will be available in the capture result for this request. 1301 </notes> 1302 </value> 1303 <value>CLOUDY_DAYLIGHT 1304 <notes> 1305 The camera device's auto-white balance routine is disabled; 1306 the camera device uses cloudy daylight light as the assumed scene 1307 illumination for white balance. 1308 1309 The application's values for android.colorCorrection.transform 1310 and android.colorCorrection.gains are ignored. 1311 For devices that support the MANUAL_POST_PROCESSING capability, the 1312 values used by the camera device for the transform and gains 1313 will be available in the capture result for this request. 1314 </notes> 1315 </value> 1316 <value>TWILIGHT 1317 <notes> 1318 The camera device's auto-white balance routine is disabled; 1319 the camera device uses twilight light as the assumed scene 1320 illumination for white balance. 1321 1322 The application's values for android.colorCorrection.transform 1323 and android.colorCorrection.gains are ignored. 1324 For devices that support the MANUAL_POST_PROCESSING capability, the 1325 values used by the camera device for the transform and gains 1326 will be available in the capture result for this request. 1327 </notes> 1328 </value> 1329 <value>SHADE 1330 <notes> 1331 The camera device's auto-white balance routine is disabled; 1332 the camera device uses shade light as the assumed scene 1333 illumination for white balance. 1334 1335 The application's values for android.colorCorrection.transform 1336 and android.colorCorrection.gains are ignored. 1337 For devices that support the MANUAL_POST_PROCESSING capability, the 1338 values used by the camera device for the transform and gains 1339 will be available in the capture result for this request. 1340 </notes> 1341 </value> 1342 </enum> 1343 <description>Whether auto-white balance (AWB) is currently setting the color 1344 transform fields, and what its illumination target 1345 is.</description> 1346 <range>android.control.awbAvailableModes</range> 1347 <details> 1348 This control is only effective if android.control.mode is AUTO. 1349 1350 When set to the AUTO mode, the camera device's auto-white balance 1351 routine is enabled, overriding the application's selected 1352 android.colorCorrection.transform, android.colorCorrection.gains and 1353 android.colorCorrection.mode. Note that when android.control.aeMode 1354 is OFF, the behavior of AWB is device dependent. It is recommened to 1355 also set AWB mode to OFF or lock AWB by using android.control.awbLock before 1356 setting AE mode to OFF. 1357 1358 When set to the OFF mode, the camera device's auto-white balance 1359 routine is disabled. The application manually controls the white 1360 balance by android.colorCorrection.transform, android.colorCorrection.gains 1361 and android.colorCorrection.mode. 1362 1363 When set to any other modes, the camera device's auto-white 1364 balance routine is disabled. The camera device uses each 1365 particular illumination target for white balance 1366 adjustment. The application's values for 1367 android.colorCorrection.transform, 1368 android.colorCorrection.gains and 1369 android.colorCorrection.mode are ignored. 1370 </details> 1371 <tag id="BC" /> 1372 </entry> 1373 <entry name="awbRegions" type="int32" visibility="public" 1374 optional="true" container="array" typedef="meteringRectangle"> 1375 <array> 1376 <size>5</size> 1377 <size>area_count</size> 1378 </array> 1379 <description>List of metering areas to use for auto-white-balance illuminant 1380 estimation.</description> 1381 <units>Pixel coordinates within android.sensor.info.activeArraySize or 1382 android.sensor.info.preCorrectionActiveArraySize depending on 1383 distortion correction capability and mode</units> 1384 <range>Coordinates must be between `[(0,0), (width, height))` of 1385 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 1386 depending on distortion correction capability and mode</range> 1387 <details> 1388 Not available if android.control.maxRegionsAwb is 0. 1389 Otherwise will always be present. 1390 1391 The maximum number of regions supported by the device is determined by the value 1392 of android.control.maxRegionsAwb. 1393 1394 For devices not supporting android.distortionCorrection.mode control, the coordinate 1395 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 1396 the top-left pixel in the active pixel array, and 1397 (android.sensor.info.activeArraySize.width - 1, 1398 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1399 active pixel array. 1400 1401 For devices supporting android.distortionCorrection.mode control, the coordinate 1402 system depends on the mode being set. 1403 When the distortion correction mode is OFF, the coordinate system follows 1404 android.sensor.info.preCorrectionActiveArraySize, with 1405 `(0, 0)` being the top-left pixel of the pre-correction active array, and 1406 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 1407 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 1408 pixel in the pre-correction active pixel array. 1409 When the distortion correction mode is not OFF, the coordinate system follows 1410 android.sensor.info.activeArraySize, with 1411 `(0, 0)` being the top-left pixel of the active array, and 1412 (android.sensor.info.activeArraySize.width - 1, 1413 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1414 active pixel array. 1415 1416 The weight must range from 0 to 1000, and represents a weight 1417 for every pixel in the area. This means that a large metering area 1418 with the same weight as a smaller area will have more effect in 1419 the metering result. Metering areas can partially overlap and the 1420 camera device will add the weights in the overlap region. 1421 1422 The weights are relative to weights of other white balance metering regions, so if 1423 only one region is used, all non-zero weights will have the same effect. A region with 1424 0 weight is ignored. 1425 1426 If all regions have 0 weight, then no specific metering area needs to be used by the 1427 camera device. 1428 1429 If the metering region is outside the used android.scaler.cropRegion returned in 1430 capture result metadata, the camera device will ignore the sections outside the crop 1431 region and output only the intersection rectangle as the metering region in the result 1432 metadata. If the region is entirely outside the crop region, it will be ignored and 1433 not reported in the result metadata. 1434 1435 Starting from API level 30, the coordinate system of activeArraySize or 1436 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 1437 pre-zoom field of view. This means that the same awbRegions values at different 1438 android.control.zoomRatio represent different parts of the scene. The awbRegions 1439 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 1440 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 1441 awbRegions at different android.scaler.cropRegion still represent the same parts of 1442 the scene as they do before. See android.control.zoomRatio for details. Whether to use 1443 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 1444 mode. 1445 1446 For camera devices with the 1447 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 1448 capability, android.sensor.info.activeArraySizeMaximumResolution / 1449 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 1450 coordinate system for requests where android.sensor.pixelMode is set to 1451 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 1452 </details> 1453 <ndk_details> 1454 The data representation is `int[5 * area_count]`. 1455 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 1456 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 1457 ymax. 1458 </ndk_details> 1459 <hal_details> 1460 The HAL level representation of MeteringRectangle[] is a 1461 int[5 * area_count]. 1462 Every five elements represent a metering region of 1463 (xmin, ymin, xmax, ymax, weight). 1464 The rectangle is defined to be inclusive on xmin and ymin, but 1465 exclusive on xmax and ymax. 1466 HAL must always report metering regions in the coordinate system of pre-correction 1467 active array. 1468 </hal_details> 1469 <tag id="BC" /> 1470 </entry> 1471 <entry name="captureIntent" type="byte" visibility="public" enum="true" 1472 hwlevel="legacy"> 1473 <enum> 1474 <value>CUSTOM 1475 <notes>The goal of this request doesn't fall into the other 1476 categories. The camera device will default to preview-like 1477 behavior.</notes></value> 1478 <value>PREVIEW 1479 <notes>This request is for a preview-like use case. 1480 1481 The precapture trigger may be used to start off a metering 1482 w/flash sequence. 1483 </notes></value> 1484 <value>STILL_CAPTURE 1485 <notes>This request is for a still capture-type 1486 use case. 1487 1488 If the flash unit is under automatic control, it may fire as needed. 1489 </notes></value> 1490 <value>VIDEO_RECORD 1491 <notes>This request is for a video recording 1492 use case.</notes></value> 1493 <value>VIDEO_SNAPSHOT 1494 <notes>This request is for a video snapshot (still 1495 image while recording video) use case. 1496 1497 The camera device should take the highest-quality image 1498 possible (given the other settings) without disrupting the 1499 frame rate of video recording. </notes></value> 1500 <value>ZERO_SHUTTER_LAG 1501 <notes>This request is for a ZSL usecase; the 1502 application will stream full-resolution images and 1503 reprocess one or several later for a final 1504 capture. 1505 </notes></value> 1506 <value>MANUAL 1507 <notes>This request is for manual capture use case where 1508 the applications want to directly control the capture parameters. 1509 1510 For example, the application may wish to manually control 1511 android.sensor.exposureTime, android.sensor.sensitivity, etc. 1512 </notes></value> 1513 <value hal_version="3.3">MOTION_TRACKING 1514 <notes>This request is for a motion tracking use case, where 1515 the application will use camera and inertial sensor data to 1516 locate and track objects in the world. 1517 1518 The camera device auto-exposure routine will limit the exposure time 1519 of the camera to no more than 20 milliseconds, to minimize motion blur. 1520 </notes></value> 1521 </enum> 1522 <description>Information to the camera device 3A (auto-exposure, 1523 auto-focus, auto-white balance) routines about the purpose 1524 of this capture, to help the camera device to decide optimal 3A 1525 strategy.</description> 1526 <details>This control (except for MANUAL) is only effective if 1527 `android.control.mode != OFF` and any 3A routine is active. 1528 1529 All intents are supported by all devices, except that: 1530 * ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities contains 1531 PRIVATE_REPROCESSING or YUV_REPROCESSING. 1532 * MANUAL will be supported if android.request.availableCapabilities contains 1533 MANUAL_SENSOR. 1534 * MOTION_TRACKING will be supported if android.request.availableCapabilities contains 1535 MOTION_TRACKING. 1536 </details> 1537 <tag id="BC" /> 1538 </entry> 1539 <entry name="effectMode" type="byte" visibility="public" enum="true" 1540 hwlevel="legacy"> 1541 <enum> 1542 <value>OFF 1543 <notes> 1544 No color effect will be applied. 1545 </notes> 1546 </value> 1547 <value optional="true">MONO 1548 <notes> 1549 A "monocolor" effect where the image is mapped into 1550 a single color. 1551 1552 This will typically be grayscale. 1553 </notes> 1554 </value> 1555 <value optional="true">NEGATIVE 1556 <notes> 1557 A "photo-negative" effect where the image's colors 1558 are inverted. 1559 </notes> 1560 </value> 1561 <value optional="true">SOLARIZE 1562 <notes> 1563 A "solarisation" effect (Sabattier effect) where the 1564 image is wholly or partially reversed in 1565 tone. 1566 </notes> 1567 </value> 1568 <value optional="true">SEPIA 1569 <notes> 1570 A "sepia" effect where the image is mapped into warm 1571 gray, red, and brown tones. 1572 </notes> 1573 </value> 1574 <value optional="true">POSTERIZE 1575 <notes> 1576 A "posterization" effect where the image uses 1577 discrete regions of tone rather than a continuous 1578 gradient of tones. 1579 </notes> 1580 </value> 1581 <value optional="true">WHITEBOARD 1582 <notes> 1583 A "whiteboard" effect where the image is typically displayed 1584 as regions of white, with black or grey details. 1585 </notes> 1586 </value> 1587 <value optional="true">BLACKBOARD 1588 <notes> 1589 A "blackboard" effect where the image is typically displayed 1590 as regions of black, with white or grey details. 1591 </notes> 1592 </value> 1593 <value optional="true">AQUA 1594 <notes> 1595 An "aqua" effect where a blue hue is added to the image. 1596 </notes> 1597 </value> 1598 </enum> 1599 <description>A special color effect to apply.</description> 1600 <range>android.control.availableEffects</range> 1601 <details> 1602 When this mode is set, a color effect will be applied 1603 to images produced by the camera device. The interpretation 1604 and implementation of these color effects is left to the 1605 implementor of the camera device, and should not be 1606 depended on to be consistent (or present) across all 1607 devices. 1608 </details> 1609 <tag id="BC" /> 1610 </entry> 1611 <entry name="mode" type="byte" visibility="public" enum="true" 1612 hwlevel="legacy"> 1613 <enum> 1614 <value>OFF 1615 <notes>Full application control of pipeline. 1616 1617 All control by the device's metering and focusing (3A) 1618 routines is disabled, and no other settings in 1619 android.control.* have any effect, except that 1620 android.control.captureIntent may be used by the camera 1621 device to select post-processing values for processing 1622 blocks that do not allow for manual control, or are not 1623 exposed by the camera API. 1624 1625 However, the camera device's 3A routines may continue to 1626 collect statistics and update their internal state so that 1627 when control is switched to AUTO mode, good control values 1628 can be immediately applied. 1629 </notes></value> 1630 <value>AUTO 1631 <notes>Use settings for each individual 3A routine. 1632 1633 Manual control of capture parameters is disabled. All 1634 controls in android.control.* besides sceneMode take 1635 effect.</notes></value> 1636 <value optional="true">USE_SCENE_MODE 1637 <notes>Use a specific scene mode. 1638 1639 Enabling this disables control.aeMode, control.awbMode and 1640 control.afMode controls; the camera device will ignore 1641 those settings while USE_SCENE_MODE is active (except for 1642 FACE_PRIORITY scene mode). Other control entries are still active. 1643 This setting can only be used if scene mode is supported (i.e. 1644 android.control.availableSceneModes 1645 contain some modes other than DISABLED). 1646 1647 For extended scene modes such as BOKEH, please use USE_EXTENDED_SCENE_MODE instead. 1648 </notes></value> 1649 <value optional="true">OFF_KEEP_STATE 1650 <notes>Same as OFF mode, except that this capture will not be 1651 used by camera device background auto-exposure, auto-white balance and 1652 auto-focus algorithms (3A) to update their statistics. 1653 1654 Specifically, the 3A routines are locked to the last 1655 values set from a request with AUTO, OFF, or 1656 USE_SCENE_MODE, and any statistics or state updates 1657 collected from manual captures with OFF_KEEP_STATE will be 1658 discarded by the camera device. 1659 </notes></value> 1660 <value optional="true" hal_version="3.5">USE_EXTENDED_SCENE_MODE 1661 <notes>Use a specific extended scene mode. 1662 1663 When extended scene mode is on, the camera device may override certain control 1664 parameters, such as targetFpsRange, AE, AWB, and AF modes, to achieve best power and 1665 quality tradeoffs. Only the mandatory stream combinations of LIMITED hardware level 1666 are guaranteed. 1667 1668 This setting can only be used if extended scene mode is supported (i.e. 1669 android.control.availableExtendedSceneModes 1670 contains some modes other than DISABLED).</notes></value> 1671 </enum> 1672 <description>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control 1673 routines.</description> 1674 <range>android.control.availableModes</range> 1675 <details> 1676 This is a top-level 3A control switch. When set to OFF, all 3A control 1677 by the camera device is disabled. The application must set the fields for 1678 capture parameters itself. 1679 1680 When set to AUTO, the individual algorithm controls in 1681 android.control.* are in effect, such as android.control.afMode. 1682 1683 When set to USE_SCENE_MODE or USE_EXTENDED_SCENE_MODE, the individual controls in 1684 android.control.* are mostly disabled, and the camera device 1685 implements one of the scene mode or extended scene mode settings (such as ACTION, 1686 SUNSET, PARTY, or BOKEH) as it wishes. The camera device scene mode 1687 3A settings are provided by {@link 1688 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result 1689 capture results}. 1690 1691 When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference 1692 is that this frame will not be used by camera device background 3A statistics 1693 update, as if this frame is never captured. This mode can be used in the scenario 1694 where the application doesn't want a 3A manual control capture to affect 1695 the subsequent auto 3A capture results. 1696 </details> 1697 <tag id="BC" /> 1698 </entry> 1699 <entry name="sceneMode" type="byte" visibility="public" enum="true" 1700 hwlevel="legacy"> 1701 <enum> 1702 <value id="0">DISABLED 1703 <notes> 1704 Indicates that no scene modes are set for a given capture request. 1705 </notes> 1706 </value> 1707 <value>FACE_PRIORITY 1708 <notes>If face detection support exists, use face 1709 detection data for auto-focus, auto-white balance, and 1710 auto-exposure routines. 1711 1712 If face detection statistics are disabled 1713 (i.e. android.statistics.faceDetectMode is set to OFF), 1714 this should still operate correctly (but will not return 1715 face detection statistics to the framework). 1716 1717 Unlike the other scene modes, android.control.aeMode, 1718 android.control.awbMode, and android.control.afMode 1719 remain active when FACE_PRIORITY is set. 1720 </notes> 1721 </value> 1722 <value optional="true">ACTION 1723 <notes> 1724 Optimized for photos of quickly moving objects. 1725 1726 Similar to SPORTS. 1727 </notes> 1728 </value> 1729 <value optional="true">PORTRAIT 1730 <notes> 1731 Optimized for still photos of people. 1732 </notes> 1733 </value> 1734 <value optional="true">LANDSCAPE 1735 <notes> 1736 Optimized for photos of distant macroscopic objects. 1737 </notes> 1738 </value> 1739 <value optional="true">NIGHT 1740 <notes> 1741 Optimized for low-light settings. 1742 </notes> 1743 </value> 1744 <value optional="true">NIGHT_PORTRAIT 1745 <notes> 1746 Optimized for still photos of people in low-light 1747 settings. 1748 </notes> 1749 </value> 1750 <value optional="true">THEATRE 1751 <notes> 1752 Optimized for dim, indoor settings where flash must 1753 remain off. 1754 </notes> 1755 </value> 1756 <value optional="true">BEACH 1757 <notes> 1758 Optimized for bright, outdoor beach settings. 1759 </notes> 1760 </value> 1761 <value optional="true">SNOW 1762 <notes> 1763 Optimized for bright, outdoor settings containing snow. 1764 </notes> 1765 </value> 1766 <value optional="true">SUNSET 1767 <notes> 1768 Optimized for scenes of the setting sun. 1769 </notes> 1770 </value> 1771 <value optional="true">STEADYPHOTO 1772 <notes> 1773 Optimized to avoid blurry photos due to small amounts of 1774 device motion (for example: due to hand shake). 1775 </notes> 1776 </value> 1777 <value optional="true">FIREWORKS 1778 <notes> 1779 Optimized for nighttime photos of fireworks. 1780 </notes> 1781 </value> 1782 <value optional="true">SPORTS 1783 <notes> 1784 Optimized for photos of quickly moving people. 1785 1786 Similar to ACTION. 1787 </notes> 1788 </value> 1789 <value optional="true">PARTY 1790 <notes> 1791 Optimized for dim, indoor settings with multiple moving 1792 people. 1793 </notes> 1794 </value> 1795 <value optional="true">CANDLELIGHT 1796 <notes> 1797 Optimized for dim settings where the main light source 1798 is a candle. 1799 </notes> 1800 </value> 1801 <value optional="true">BARCODE 1802 <notes> 1803 Optimized for accurately capturing a photo of barcode 1804 for use by camera applications that wish to read the 1805 barcode value. 1806 </notes> 1807 </value> 1808 <value deprecated="true" optional="true" visibility="java_public">HIGH_SPEED_VIDEO 1809 <notes> 1810 This is deprecated, please use {@link 1811 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession} 1812 and {@link 1813 android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList} 1814 for high speed video recording. 1815 1816 Optimized for high speed video recording (frame rate >=60fps) use case. 1817 1818 The supported high speed video sizes and fps ranges are specified in 1819 android.control.availableHighSpeedVideoConfigurations. To get desired 1820 output frame rates, the application is only allowed to select video size 1821 and fps range combinations listed in this static metadata. The fps range 1822 can be control via android.control.aeTargetFpsRange. 1823 1824 In this mode, the camera device will override aeMode, awbMode, and afMode to 1825 ON, ON, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 1826 controls will be overridden to be FAST. Therefore, no manual control of capture 1827 and post-processing parameters is possible. All other controls operate the 1828 same as when android.control.mode == AUTO. This means that all other 1829 android.control.* fields continue to work, such as 1830 1831 * android.control.aeTargetFpsRange 1832 * android.control.aeExposureCompensation 1833 * android.control.aeLock 1834 * android.control.awbLock 1835 * android.control.effectMode 1836 * android.control.aeRegions 1837 * android.control.afRegions 1838 * android.control.awbRegions 1839 * android.control.afTrigger 1840 * android.control.aePrecaptureTrigger 1841 * android.control.zoomRatio 1842 1843 Outside of android.control.*, the following controls will work: 1844 1845 * android.flash.mode (automatic flash for still capture will not work since aeMode is ON) 1846 * android.lens.opticalStabilizationMode (if it is supported) 1847 * android.scaler.cropRegion 1848 * android.statistics.faceDetectMode 1849 1850 For high speed recording use case, the actual maximum supported frame rate may 1851 be lower than what camera can output, depending on the destination Surfaces for 1852 the image data. For example, if the destination surface is from video encoder, 1853 the application need check if the video encoder is capable of supporting the 1854 high frame rate for a given video size, or it will end up with lower recording 1855 frame rate. If the destination surface is from preview window, the preview frame 1856 rate will be bounded by the screen refresh rate. 1857 1858 The camera device will only support up to 2 output high speed streams 1859 (processed non-stalling format defined in android.request.maxNumOutputStreams) 1860 in this mode. This control will be effective only if all of below conditions are true: 1861 1862 * The application created no more than maxNumHighSpeedStreams processed non-stalling 1863 format output streams, where maxNumHighSpeedStreams is calculated as 1864 min(2, android.request.maxNumOutputStreams[Processed (but not-stalling)]). 1865 * The stream sizes are selected from the sizes reported by 1866 android.control.availableHighSpeedVideoConfigurations. 1867 * No processed non-stalling or raw streams are configured. 1868 1869 When above conditions are NOT satistied, the controls of this mode and 1870 android.control.aeTargetFpsRange will be ignored by the camera device, 1871 the camera device will fall back to android.control.mode `==` AUTO, 1872 and the returned capture result metadata will give the fps range choosen 1873 by the camera device. 1874 1875 Switching into or out of this mode may trigger some camera ISP/sensor 1876 reconfigurations, which may introduce extra latency. It is recommended that 1877 the application avoids unnecessary scene mode switch as much as possible. 1878 </notes> 1879 </value> 1880 <value optional="true">HDR 1881 <notes> 1882 Turn on a device-specific high dynamic range (HDR) mode. 1883 1884 In this scene mode, the camera device captures images 1885 that keep a larger range of scene illumination levels 1886 visible in the final image. For example, when taking a 1887 picture of a object in front of a bright window, both 1888 the object and the scene through the window may be 1889 visible when using HDR mode, while in normal AUTO mode, 1890 one or the other may be poorly exposed. As a tradeoff, 1891 HDR mode generally takes much longer to capture a single 1892 image, has no user control, and may have other artifacts 1893 depending on the HDR method used. 1894 1895 Therefore, HDR captures operate at a much slower rate 1896 than regular captures. 1897 1898 In this mode, on LIMITED or FULL devices, when a request 1899 is made with a android.control.captureIntent of 1900 STILL_CAPTURE, the camera device will capture an image 1901 using a high dynamic range capture technique. On LEGACY 1902 devices, captures that target a JPEG-format output will 1903 be captured with HDR, and the capture intent is not 1904 relevant. 1905 1906 The HDR capture may involve the device capturing a burst 1907 of images internally and combining them into one, or it 1908 may involve the device using specialized high dynamic 1909 range capture hardware. In all cases, a single image is 1910 produced in response to a capture request submitted 1911 while in HDR mode. 1912 1913 Since substantial post-processing is generally needed to 1914 produce an HDR image, only YUV, PRIVATE, and JPEG 1915 outputs are supported for LIMITED/FULL device HDR 1916 captures, and only JPEG outputs are supported for LEGACY 1917 HDR captures. Using a RAW output for HDR capture is not 1918 supported. 1919 1920 Some devices may also support always-on HDR, which 1921 applies HDR processing at full frame rate. For these 1922 devices, intents other than STILL_CAPTURE will also 1923 produce an HDR output with no frame rate impact compared 1924 to normal operation, though the quality may be lower 1925 than for STILL_CAPTURE intents. 1926 1927 If SCENE_MODE_HDR is used with unsupported output types 1928 or capture intents, the images captured will be as if 1929 the SCENE_MODE was not enabled at all. 1930 </notes> 1931 </value> 1932 <value optional="true" visibility="hidden">FACE_PRIORITY_LOW_LIGHT 1933 <notes>Same as FACE_PRIORITY scene mode, except that the camera 1934 device will choose higher sensitivity values (android.sensor.sensitivity) 1935 under low light conditions. 1936 1937 The camera device may be tuned to expose the images in a reduced 1938 sensitivity range to produce the best quality images. For example, 1939 if the android.sensor.info.sensitivityRange gives range of [100, 1600], 1940 the camera device auto-exposure routine tuning process may limit the actual 1941 exposure sensitivity range to [100, 1200] to ensure that the noise level isn't 1942 exessive in order to preserve the image quality. Under this situation, the image under 1943 low light may be under-exposed when the sensor max exposure time (bounded by the 1944 android.control.aeTargetFpsRange when android.control.aeMode is one of the 1945 ON_* modes) and effective max sensitivity are reached. This scene mode allows the 1946 camera device auto-exposure routine to increase the sensitivity up to the max 1947 sensitivity specified by android.sensor.info.sensitivityRange when the scene is too 1948 dark and the max exposure time is reached. The captured images may be noisier 1949 compared with the images captured in normal FACE_PRIORITY mode; therefore, it is 1950 recommended that the application only use this scene mode when it is capable of 1951 reducing the noise level of the captured images. 1952 1953 Unlike the other scene modes, android.control.aeMode, 1954 android.control.awbMode, and android.control.afMode 1955 remain active when FACE_PRIORITY_LOW_LIGHT is set. 1956 </notes> 1957 </value> 1958 <value optional="true" visibility="hidden" id="100">DEVICE_CUSTOM_START 1959 <notes> 1960 Scene mode values within the range of 1961 `[DEVICE_CUSTOM_START, DEVICE_CUSTOM_END]` are reserved for device specific 1962 customized scene modes. 1963 </notes> 1964 </value> 1965 <value optional="true" visibility="hidden" id="127">DEVICE_CUSTOM_END 1966 <notes> 1967 Scene mode values within the range of 1968 `[DEVICE_CUSTOM_START, DEVICE_CUSTOM_END]` are reserved for device specific 1969 customized scene modes. 1970 </notes> 1971 </value> 1972 </enum> 1973 <description> 1974 Control for which scene mode is currently active. 1975 </description> 1976 <range>android.control.availableSceneModes</range> 1977 <details> 1978 Scene modes are custom camera modes optimized for a certain set of conditions and 1979 capture settings. 1980 1981 This is the mode that that is active when 1982 `android.control.mode == USE_SCENE_MODE`. Aside from FACE_PRIORITY, these modes will 1983 disable android.control.aeMode, android.control.awbMode, and android.control.afMode 1984 while in use. 1985 1986 The interpretation and implementation of these scene modes is left 1987 to the implementor of the camera device. Their behavior will not be 1988 consistent across all devices, and any given device may only implement 1989 a subset of these modes. 1990 </details> 1991 <hal_details> 1992 HAL implementations that include scene modes are expected to provide 1993 the per-scene settings to use for android.control.aeMode, 1994 android.control.awbMode, and android.control.afMode in 1995 android.control.sceneModeOverrides. 1996 1997 For HIGH_SPEED_VIDEO mode, if it is included in android.control.availableSceneModes, the 1998 HAL must list supported video size and fps range in 1999 android.control.availableHighSpeedVideoConfigurations. For a given size, e.g. 1280x720, 2000 if the HAL has two different sensor configurations for normal streaming mode and high 2001 speed streaming, when this scene mode is set/reset in a sequence of capture requests, the 2002 HAL may have to switch between different sensor modes. This mode is deprecated in legacy 2003 HAL3.3, to support high speed video recording, please implement 2004 android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO 2005 capbility defined in android.request.availableCapabilities. 2006 </hal_details> 2007 <tag id="BC" /> 2008 </entry> 2009 <entry name="videoStabilizationMode" type="byte" visibility="public" 2010 enum="true" hwlevel="legacy"> 2011 <enum> 2012 <value>OFF 2013 <notes> 2014 Video stabilization is disabled. 2015 </notes></value> 2016 <value>ON 2017 <notes> 2018 Video stabilization is enabled. 2019 </notes></value> 2020 </enum> 2021 <description>Whether video stabilization is 2022 active.</description> 2023 <details> 2024 Video stabilization automatically warps images from 2025 the camera in order to stabilize motion between consecutive frames. 2026 2027 If enabled, video stabilization can modify the 2028 android.scaler.cropRegion to keep the video stream stabilized. 2029 2030 Switching between different video stabilization modes may take several 2031 frames to initialize, the camera device will report the current mode 2032 in capture result metadata. For example, When "ON" mode is requested, 2033 the video stabilization modes in the first several capture results may 2034 still be "OFF", and it will become "ON" when the initialization is 2035 done. 2036 2037 In addition, not all recording sizes or frame rates may be supported for 2038 stabilization by a device that reports stabilization support. It is guaranteed 2039 that an output targeting a MediaRecorder or MediaCodec will be stabilized if 2040 the recording resolution is less than or equal to 1920 x 1080 (width less than 2041 or equal to 1920, height less than or equal to 1080), and the recording 2042 frame rate is less than or equal to 30fps. At other sizes, the CaptureResult 2043 android.control.videoStabilizationMode field will return 2044 OFF if the recording output is not stabilized, or if there are no output 2045 Surface types that can be stabilized. 2046 2047 If a camera device supports both this mode and OIS 2048 (android.lens.opticalStabilizationMode), turning both modes on may 2049 produce undesirable interaction, so it is recommended not to enable 2050 both at the same time. 2051 </details> 2052 <tag id="BC" /> 2053 </entry> 2054 </controls> 2055 <static> 2056 <entry name="aeAvailableAntibandingModes" type="byte" visibility="public" 2057 type_notes="list of enums" container="array" typedef="enumList" 2058 hwlevel="legacy"> 2059 <array> 2060 <size>n</size> 2061 </array> 2062 <description> 2063 List of auto-exposure antibanding modes for android.control.aeAntibandingMode that are 2064 supported by this camera device. 2065 </description> 2066 <range>Any value listed in android.control.aeAntibandingMode</range> 2067 <details> 2068 Not all of the auto-exposure anti-banding modes may be 2069 supported by a given camera device. This field lists the 2070 valid anti-banding modes that the application may request 2071 for this camera device with the 2072 android.control.aeAntibandingMode control. 2073 </details> 2074 <tag id="BC" /> 2075 </entry> 2076 <entry name="aeAvailableModes" type="byte" visibility="public" 2077 type_notes="list of enums" container="array" typedef="enumList" 2078 hwlevel="legacy"> 2079 <array> 2080 <size>n</size> 2081 </array> 2082 <description> 2083 List of auto-exposure modes for android.control.aeMode that are supported by this camera 2084 device. 2085 </description> 2086 <range>Any value listed in android.control.aeMode</range> 2087 <details> 2088 Not all the auto-exposure modes may be supported by a 2089 given camera device, especially if no flash unit is 2090 available. This entry lists the valid modes for 2091 android.control.aeMode for this camera device. 2092 2093 All camera devices support ON, and all camera devices with flash 2094 units support ON_AUTO_FLASH and ON_ALWAYS_FLASH. 2095 2096 FULL mode camera devices always support OFF mode, 2097 which enables application control of camera exposure time, 2098 sensitivity, and frame duration. 2099 2100 LEGACY mode camera devices never support OFF mode. 2101 LIMITED mode devices support OFF if they support the MANUAL_SENSOR 2102 capability. 2103 </details> 2104 <tag id="BC" /> 2105 </entry> 2106 <entry name="aeAvailableTargetFpsRanges" type="int32" visibility="public" 2107 type_notes="list of pairs of frame rates" 2108 container="array" typedef="rangeInt" 2109 hwlevel="legacy"> 2110 <array> 2111 <size>2</size> 2112 <size>n</size> 2113 </array> 2114 <description>List of frame rate ranges for android.control.aeTargetFpsRange supported by 2115 this camera device.</description> 2116 <units>Frames per second (FPS)</units> 2117 <details> 2118 For devices at the LEGACY level or above: 2119 2120 * For constant-framerate recording, for each normal 2121 {@link android.media.CamcorderProfile CamcorderProfile}, that is, a 2122 {@link android.media.CamcorderProfile CamcorderProfile} that has 2123 {@link android.media.CamcorderProfile#quality quality} in 2124 the range [{@link android.media.CamcorderProfile#QUALITY_LOW QUALITY_LOW}, 2125 {@link android.media.CamcorderProfile#QUALITY_2160P QUALITY_2160P}], if the profile is 2126 supported by the device and has 2127 {@link android.media.CamcorderProfile#videoFrameRate videoFrameRate} `x`, this list will 2128 always include (`x`,`x`). 2129 2130 * Also, a camera device must either not support any 2131 {@link android.media.CamcorderProfile CamcorderProfile}, 2132 or support at least one 2133 normal {@link android.media.CamcorderProfile CamcorderProfile} that has 2134 {@link android.media.CamcorderProfile#videoFrameRate videoFrameRate} `x` >= 24. 2135 2136 For devices at the LIMITED level or above: 2137 2138 * For devices that advertise NIR color filter arrangement in 2139 android.sensor.info.colorFilterArrangement, this list will always include 2140 (`max`, `max`) where `max` = the maximum output frame rate of the maximum YUV_420_888 2141 output size. 2142 * For devices advertising any color filter arrangement other than NIR, or devices not 2143 advertising color filter arrangement, this list will always include (`min`, `max`) and 2144 (`max`, `max`) where `min` <= 15 and `max` = the maximum output frame rate of the 2145 maximum YUV_420_888 output size. 2146 2147 </details> 2148 <tag id="BC" /> 2149 </entry> 2150 <entry name="aeCompensationRange" type="int32" visibility="public" 2151 container="array" typedef="rangeInt" 2152 hwlevel="legacy"> 2153 <array> 2154 <size>2</size> 2155 </array> 2156 <description>Maximum and minimum exposure compensation values for 2157 android.control.aeExposureCompensation, in counts of android.control.aeCompensationStep, 2158 that are supported by this camera device.</description> 2159 <range> 2160 Range [0,0] indicates that exposure compensation is not supported. 2161 2162 For LIMITED and FULL devices, range must follow below requirements if exposure 2163 compensation is supported (`range != [0, 0]`): 2164 2165 `Min.exposure compensation * android.control.aeCompensationStep <= -2 EV` 2166 2167 `Max.exposure compensation * android.control.aeCompensationStep >= 2 EV` 2168 2169 LEGACY devices may support a smaller range than this. 2170 </range> 2171 <tag id="BC" /> 2172 </entry> 2173 <entry name="aeCompensationStep" type="rational" visibility="public" 2174 hwlevel="legacy"> 2175 <description>Smallest step by which the exposure compensation 2176 can be changed.</description> 2177 <units>Exposure Value (EV)</units> 2178 <details> 2179 This is the unit for android.control.aeExposureCompensation. For example, if this key has 2180 a value of `1/2`, then a setting of `-2` for android.control.aeExposureCompensation means 2181 that the target EV offset for the auto-exposure routine is -1 EV. 2182 2183 One unit of EV compensation changes the brightness of the captured image by a factor 2184 of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness. 2185 </details> 2186 <hal_details> 2187 This must be less than or equal to 1/2. 2188 </hal_details> 2189 <tag id="BC" /> 2190 </entry> 2191 <entry name="afAvailableModes" type="byte" visibility="public" 2192 type_notes="List of enums" container="array" typedef="enumList" 2193 hwlevel="legacy"> 2194 <array> 2195 <size>n</size> 2196 </array> 2197 <description> 2198 List of auto-focus (AF) modes for android.control.afMode that are 2199 supported by this camera device. 2200 </description> 2201 <range>Any value listed in android.control.afMode</range> 2202 <details> 2203 Not all the auto-focus modes may be supported by a 2204 given camera device. This entry lists the valid modes for 2205 android.control.afMode for this camera device. 2206 2207 All LIMITED and FULL mode camera devices will support OFF mode, and all 2208 camera devices with adjustable focuser units 2209 (`android.lens.info.minimumFocusDistance > 0`) will support AUTO mode. 2210 2211 LEGACY devices will support OFF mode only if they support 2212 focusing to infinity (by also setting android.lens.focusDistance to 2213 `0.0f`). 2214 </details> 2215 <tag id="BC" /> 2216 </entry> 2217 <entry name="availableEffects" type="byte" visibility="public" 2218 type_notes="List of enums (android.control.effectMode)." container="array" 2219 typedef="enumList" hwlevel="legacy"> 2220 <array> 2221 <size>n</size> 2222 </array> 2223 <description> 2224 List of color effects for android.control.effectMode that are supported by this camera 2225 device. 2226 </description> 2227 <range>Any value listed in android.control.effectMode</range> 2228 <details> 2229 This list contains the color effect modes that can be applied to 2230 images produced by the camera device. 2231 Implementations are not expected to be consistent across all devices. 2232 If no color effect modes are available for a device, this will only list 2233 OFF. 2234 2235 A color effect will only be applied if 2236 android.control.mode != OFF. OFF is always included in this list. 2237 2238 This control has no effect on the operation of other control routines such 2239 as auto-exposure, white balance, or focus. 2240 </details> 2241 <tag id="BC" /> 2242 </entry> 2243 <entry name="availableSceneModes" type="byte" visibility="public" 2244 type_notes="List of enums (android.control.sceneMode)." 2245 container="array" typedef="enumList" hwlevel="legacy"> 2246 <array> 2247 <size>n</size> 2248 </array> 2249 <description> 2250 List of scene modes for android.control.sceneMode that are supported by this camera 2251 device. 2252 </description> 2253 <range>Any value listed in android.control.sceneMode</range> 2254 <details> 2255 This list contains scene modes that can be set for the camera device. 2256 Only scene modes that have been fully implemented for the 2257 camera device may be included here. Implementations are not expected 2258 to be consistent across all devices. 2259 2260 If no scene modes are supported by the camera device, this 2261 will be set to DISABLED. Otherwise DISABLED will not be listed. 2262 2263 FACE_PRIORITY is always listed if face detection is 2264 supported (i.e.`android.statistics.info.maxFaceCount > 2265 0`). 2266 </details> 2267 <tag id="BC" /> 2268 </entry> 2269 <entry name="availableVideoStabilizationModes" type="byte" 2270 visibility="public" type_notes="List of enums." container="array" 2271 typedef="enumList" hwlevel="legacy"> 2272 <array> 2273 <size>n</size> 2274 </array> 2275 <description> 2276 List of video stabilization modes for android.control.videoStabilizationMode 2277 that are supported by this camera device. 2278 </description> 2279 <range>Any value listed in android.control.videoStabilizationMode</range> 2280 <details> 2281 OFF will always be listed. 2282 </details> 2283 <tag id="BC" /> 2284 </entry> 2285 <entry name="awbAvailableModes" type="byte" visibility="public" 2286 type_notes="List of enums" 2287 container="array" typedef="enumList" hwlevel="legacy"> 2288 <array> 2289 <size>n</size> 2290 </array> 2291 <description> 2292 List of auto-white-balance modes for android.control.awbMode that are supported by this 2293 camera device. 2294 </description> 2295 <range>Any value listed in android.control.awbMode</range> 2296 <details> 2297 Not all the auto-white-balance modes may be supported by a 2298 given camera device. This entry lists the valid modes for 2299 android.control.awbMode for this camera device. 2300 2301 All camera devices will support ON mode. 2302 2303 Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF 2304 mode, which enables application control of white balance, by using 2305 android.colorCorrection.transform and android.colorCorrection.gains 2306 (android.colorCorrection.mode must be set to TRANSFORM_MATRIX). This includes all FULL 2307 mode camera devices. 2308 </details> 2309 <tag id="BC" /> 2310 </entry> 2311 <entry name="maxRegions" type="int32" visibility="ndk_public" 2312 container="array" hwlevel="legacy"> 2313 <array> 2314 <size>3</size> 2315 </array> 2316 <description> 2317 List of the maximum number of regions that can be used for metering in 2318 auto-exposure (AE), auto-white balance (AWB), and auto-focus (AF); 2319 this corresponds to the maximum number of elements in 2320 android.control.aeRegions, android.control.awbRegions, 2321 and android.control.afRegions. 2322 </description> 2323 <range> 2324 Value must be &gt;= 0 for each element. For full-capability devices 2325 this value must be &gt;= 1 for AE and AF. The order of the elements is: 2326 `(AE, AWB, AF)`.</range> 2327 <tag id="BC" /> 2328 </entry> 2329 <entry name="maxRegionsAe" type="int32" visibility="java_public" 2330 synthetic="true" hwlevel="legacy"> 2331 <description> 2332 The maximum number of metering regions that can be used by the auto-exposure (AE) 2333 routine. 2334 </description> 2335 <range>Value will be &gt;= 0. For FULL-capability devices, this 2336 value will be &gt;= 1. 2337 </range> 2338 <details> 2339 This corresponds to the maximum allowed number of elements in 2340 android.control.aeRegions. 2341 </details> 2342 <hal_details>This entry is private to the framework. Fill in 2343 maxRegions to have this entry be automatically populated. 2344 </hal_details> 2345 </entry> 2346 <entry name="maxRegionsAwb" type="int32" visibility="java_public" 2347 synthetic="true" hwlevel="legacy"> 2348 <description> 2349 The maximum number of metering regions that can be used by the auto-white balance (AWB) 2350 routine. 2351 </description> 2352 <range>Value will be &gt;= 0. 2353 </range> 2354 <details> 2355 This corresponds to the maximum allowed number of elements in 2356 android.control.awbRegions. 2357 </details> 2358 <hal_details>This entry is private to the framework. Fill in 2359 maxRegions to have this entry be automatically populated. 2360 </hal_details> 2361 </entry> 2362 <entry name="maxRegionsAf" type="int32" visibility="java_public" 2363 synthetic="true" hwlevel="legacy"> 2364 <description> 2365 The maximum number of metering regions that can be used by the auto-focus (AF) routine. 2366 </description> 2367 <range>Value will be &gt;= 0. For FULL-capability devices, this 2368 value will be &gt;= 1. 2369 </range> 2370 <details> 2371 This corresponds to the maximum allowed number of elements in 2372 android.control.afRegions. 2373 </details> 2374 <hal_details>This entry is private to the framework. Fill in 2375 maxRegions to have this entry be automatically populated. 2376 </hal_details> 2377 </entry> 2378 <entry name="sceneModeOverrides" type="byte" visibility="system" 2379 container="array" hwlevel="limited"> 2380 <array> 2381 <size>3</size> 2382 <size>length(availableSceneModes)</size> 2383 </array> 2384 <description> 2385 Ordered list of auto-exposure, auto-white balance, and auto-focus 2386 settings to use with each available scene mode. 2387 </description> 2388 <range> 2389 For each available scene mode, the list must contain three 2390 entries containing the android.control.aeMode, 2391 android.control.awbMode, and android.control.afMode values used 2392 by the camera device. The entry order is `(aeMode, awbMode, afMode)` 2393 where aeMode has the lowest index position. 2394 </range> 2395 <details> 2396 When a scene mode is enabled, the camera device is expected 2397 to override android.control.aeMode, android.control.awbMode, 2398 and android.control.afMode with its preferred settings for 2399 that scene mode. 2400 2401 The order of this list matches that of availableSceneModes, 2402 with 3 entries for each mode. The overrides listed 2403 for FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported) are ignored, 2404 since for that mode the application-set android.control.aeMode, 2405 android.control.awbMode, and android.control.afMode values are 2406 used instead, matching the behavior when android.control.mode 2407 is set to AUTO. It is recommended that the FACE_PRIORITY and 2408 FACE_PRIORITY_LOW_LIGHT (if supported) overrides should be set to 0. 2409 2410 For example, if availableSceneModes contains 2411 `(FACE_PRIORITY, ACTION, NIGHT)`, then the camera framework 2412 expects sceneModeOverrides to have 9 entries formatted like: 2413 `(0, 0, 0, ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE, 2414 ON_AUTO_FLASH, INCANDESCENT, AUTO)`. 2415 </details> 2416 <hal_details> 2417 To maintain backward compatibility, this list will be made available 2418 in the static metadata of the camera service. The camera service will 2419 use these values to set android.control.aeMode, 2420 android.control.awbMode, and android.control.afMode when using a scene 2421 mode other than FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported). 2422 </hal_details> 2423 <tag id="BC" /> 2424 </entry> 2425 </static> 2426 <dynamic> 2427 <entry name="aePrecaptureId" type="int32" visibility="system" deprecated="true"> 2428 <description>The ID sent with the latest 2429 CAMERA2_TRIGGER_PRECAPTURE_METERING call</description> 2430 <deprecation_description> 2431 Removed in camera HAL v3 2432 </deprecation_description> 2433 <details>Must be 0 if no 2434 CAMERA2_TRIGGER_PRECAPTURE_METERING trigger received yet 2435 by HAL. Always updated even if AE algorithm ignores the 2436 trigger</details> 2437 </entry> 2438 <clone entry="android.control.aeAntibandingMode" kind="controls"> 2439 </clone> 2440 <clone entry="android.control.aeExposureCompensation" kind="controls"> 2441 </clone> 2442 <clone entry="android.control.aeLock" kind="controls"> 2443 </clone> 2444 <clone entry="android.control.aeMode" kind="controls"> 2445 </clone> 2446 <clone entry="android.control.aeRegions" kind="controls"> 2447 </clone> 2448 <clone entry="android.control.aeTargetFpsRange" kind="controls"> 2449 </clone> 2450 <clone entry="android.control.aePrecaptureTrigger" kind="controls"> 2451 </clone> 2452 <entry name="aeState" type="byte" visibility="public" enum="true" 2453 hwlevel="limited"> 2454 <enum> 2455 <value>INACTIVE 2456 <notes>AE is off or recently reset. 2457 2458 When a camera device is opened, it starts in 2459 this state. This is a transient state, the camera device may skip reporting 2460 this state in capture result.</notes></value> 2461 <value>SEARCHING 2462 <notes>AE doesn't yet have a good set of control values 2463 for the current scene. 2464 2465 This is a transient state, the camera device may skip 2466 reporting this state in capture result.</notes></value> 2467 <value>CONVERGED 2468 <notes>AE has a good set of control values for the 2469 current scene.</notes></value> 2470 <value>LOCKED 2471 <notes>AE has been locked.</notes></value> 2472 <value>FLASH_REQUIRED 2473 <notes>AE has a good set of control values, but flash 2474 needs to be fired for good quality still 2475 capture.</notes></value> 2476 <value>PRECAPTURE 2477 <notes>AE has been asked to do a precapture sequence 2478 and is currently executing it. 2479 2480 Precapture can be triggered through setting 2481 android.control.aePrecaptureTrigger to START. Currently 2482 active and completed (if it causes camera device internal AE lock) precapture 2483 metering sequence can be canceled through setting 2484 android.control.aePrecaptureTrigger to CANCEL. 2485 2486 Once PRECAPTURE completes, AE will transition to CONVERGED 2487 or FLASH_REQUIRED as appropriate. This is a transient 2488 state, the camera device may skip reporting this state in 2489 capture result.</notes></value> 2490 </enum> 2491 <description>Current state of the auto-exposure (AE) algorithm.</description> 2492 <details>Switching between or enabling AE modes (android.control.aeMode) always 2493 resets the AE state to INACTIVE. Similarly, switching between android.control.mode, 2494 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2495 the algorithm states to INACTIVE. 2496 2497 The camera device can do several state transitions between two results, if it is 2498 allowed by the state transition table. For example: INACTIVE may never actually be 2499 seen in a result. 2500 2501 The state in the result is the state for this image (in sync with this image): if 2502 AE state becomes CONVERGED, then the image data associated with this result should 2503 be good to use. 2504 2505 Below are state transition tables for different AE modes. 2506 2507 State | Transition Cause | New State | Notes 2508 :------------:|:----------------:|:---------:|:-----------------------: 2509 INACTIVE | | INACTIVE | Camera device auto exposure algorithm is disabled 2510 2511 When android.control.aeMode is AE_MODE_ON*: 2512 2513 State | Transition Cause | New State | Notes 2514 :-------------:|:--------------------------------------------:|:--------------:|:-----------------: 2515 INACTIVE | Camera device initiates AE scan | SEARCHING | Values changing 2516 INACTIVE | android.control.aeLock is ON | LOCKED | Values locked 2517 SEARCHING | Camera device finishes AE scan | CONVERGED | Good values, not changing 2518 SEARCHING | Camera device finishes AE scan | FLASH_REQUIRED | Converged but too dark w/o flash 2519 SEARCHING | android.control.aeLock is ON | LOCKED | Values locked 2520 CONVERGED | Camera device initiates AE scan | SEARCHING | Values changing 2521 CONVERGED | android.control.aeLock is ON | LOCKED | Values locked 2522 FLASH_REQUIRED | Camera device initiates AE scan | SEARCHING | Values changing 2523 FLASH_REQUIRED | android.control.aeLock is ON | LOCKED | Values locked 2524 LOCKED | android.control.aeLock is OFF | SEARCHING | Values not good after unlock 2525 LOCKED | android.control.aeLock is OFF | CONVERGED | Values good after unlock 2526 LOCKED | android.control.aeLock is OFF | FLASH_REQUIRED | Exposure good, but too dark 2527 PRECAPTURE | Sequence done. android.control.aeLock is OFF | CONVERGED | Ready for high-quality capture 2528 PRECAPTURE | Sequence done. android.control.aeLock is ON | LOCKED | Ready for high-quality capture 2529 LOCKED | aeLock is ON and aePrecaptureTrigger is START | LOCKED | Precapture trigger is ignored when AE is already locked 2530 LOCKED | aeLock is ON and aePrecaptureTrigger is CANCEL| LOCKED | Precapture trigger is ignored when AE is already locked 2531 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START | PRECAPTURE | Start AE precapture metering sequence 2532 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL| INACTIVE | Currently active precapture metering sequence is canceled 2533 2534 If the camera device supports AE external flash mode (ON_EXTERNAL_FLASH is included in 2535 android.control.aeAvailableModes), android.control.aeState must be FLASH_REQUIRED after 2536 the camera device finishes AE scan and it's too dark without flash. 2537 2538 For the above table, the camera device may skip reporting any state changes that happen 2539 without application intervention (i.e. mode switch, trigger, locking). Any state that 2540 can be skipped in that manner is called a transient state. 2541 2542 For example, for above AE modes (AE_MODE_ON*), in addition to the state transitions 2543 listed in above table, it is also legal for the camera device to skip one or more 2544 transient states between two results. See below table for examples: 2545 2546 State | Transition Cause | New State | Notes 2547 :-------------:|:-----------------------------------------------------------:|:--------------:|:-----------------: 2548 INACTIVE | Camera device finished AE scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2549 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START, sequence done | FLASH_REQUIRED | Converged but too dark w/o flash after a precapture sequence, transient states are skipped by camera device. 2550 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START, sequence done | CONVERGED | Converged after a precapture sequence, transient states are skipped by camera device. 2551 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL, converged | FLASH_REQUIRED | Converged but too dark w/o flash after a precapture sequence is canceled, transient states are skipped by camera device. 2552 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL, converged | CONVERGED | Converged after a precapture sequenceis canceled, transient states are skipped by camera device. 2553 CONVERGED | Camera device finished AE scan | FLASH_REQUIRED | Converged but too dark w/o flash after a new scan, transient states are skipped by camera device. 2554 FLASH_REQUIRED | Camera device finished AE scan | CONVERGED | Converged after a new scan, transient states are skipped by camera device. 2555 </details> 2556 </entry> 2557 <clone entry="android.control.afMode" kind="controls"> 2558 </clone> 2559 <clone entry="android.control.afRegions" kind="controls"> 2560 </clone> 2561 <clone entry="android.control.afTrigger" kind="controls"> 2562 </clone> 2563 <entry name="afState" type="byte" visibility="public" enum="true" 2564 hwlevel="legacy"> 2565 <enum> 2566 <value>INACTIVE 2567 <notes>AF is off or has not yet tried to scan/been asked 2568 to scan. 2569 2570 When a camera device is opened, it starts in this 2571 state. This is a transient state, the camera device may 2572 skip reporting this state in capture 2573 result.</notes></value> 2574 <value>PASSIVE_SCAN 2575 <notes>AF is currently performing an AF scan initiated the 2576 camera device in a continuous autofocus mode. 2577 2578 Only used by CONTINUOUS_* AF modes. This is a transient 2579 state, the camera device may skip reporting this state in 2580 capture result.</notes></value> 2581 <value>PASSIVE_FOCUSED 2582 <notes>AF currently believes it is in focus, but may 2583 restart scanning at any time. 2584 2585 Only used by CONTINUOUS_* AF modes. This is a transient 2586 state, the camera device may skip reporting this state in 2587 capture result.</notes></value> 2588 <value>ACTIVE_SCAN 2589 <notes>AF is performing an AF scan because it was 2590 triggered by AF trigger. 2591 2592 Only used by AUTO or MACRO AF modes. This is a transient 2593 state, the camera device may skip reporting this state in 2594 capture result.</notes></value> 2595 <value>FOCUSED_LOCKED 2596 <notes>AF believes it is focused correctly and has locked 2597 focus. 2598 2599 This state is reached only after an explicit START AF trigger has been 2600 sent (android.control.afTrigger), when good focus has been obtained. 2601 2602 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2603 a new AF trigger is sent to the camera device (android.control.afTrigger). 2604 </notes></value> 2605 <value>NOT_FOCUSED_LOCKED 2606 <notes>AF has failed to focus successfully and has locked 2607 focus. 2608 2609 This state is reached only after an explicit START AF trigger has been 2610 sent (android.control.afTrigger), when good focus cannot be obtained. 2611 2612 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2613 a new AF trigger is sent to the camera device (android.control.afTrigger). 2614 </notes></value> 2615 <value>PASSIVE_UNFOCUSED 2616 <notes>AF finished a passive scan without finding focus, 2617 and may restart scanning at any time. 2618 2619 Only used by CONTINUOUS_* AF modes. This is a transient state, the camera 2620 device may skip reporting this state in capture result. 2621 2622 LEGACY camera devices do not support this state. When a passive 2623 scan has finished, it will always go to PASSIVE_FOCUSED. 2624 </notes></value> 2625 </enum> 2626 <description>Current state of auto-focus (AF) algorithm.</description> 2627 <details> 2628 Switching between or enabling AF modes (android.control.afMode) always 2629 resets the AF state to INACTIVE. Similarly, switching between android.control.mode, 2630 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2631 the algorithm states to INACTIVE. 2632 2633 The camera device can do several state transitions between two results, if it is 2634 allowed by the state transition table. For example: INACTIVE may never actually be 2635 seen in a result. 2636 2637 The state in the result is the state for this image (in sync with this image): if 2638 AF state becomes FOCUSED, then the image data associated with this result should 2639 be sharp. 2640 2641 Below are state transition tables for different AF modes. 2642 2643 When android.control.afMode is AF_MODE_OFF or AF_MODE_EDOF: 2644 2645 State | Transition Cause | New State | Notes 2646 :------------:|:----------------:|:---------:|:-----------: 2647 INACTIVE | | INACTIVE | Never changes 2648 2649 When android.control.afMode is AF_MODE_AUTO or AF_MODE_MACRO: 2650 2651 State | Transition Cause | New State | Notes 2652 :-----------------:|:----------------:|:------------------:|:--------------: 2653 INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep, Lens now moving 2654 ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | Focused, Lens now locked 2655 ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | Not focused, Lens now locked 2656 ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF, Lens now locked 2657 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2658 FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2659 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2660 NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2661 Any state | Mode change | INACTIVE | 2662 2663 For the above table, the camera device may skip reporting any state changes that happen 2664 without application intervention (i.e. mode switch, trigger, locking). Any state that 2665 can be skipped in that manner is called a transient state. 2666 2667 For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the 2668 state transitions listed in above table, it is also legal for the camera device to skip 2669 one or more transient states between two results. See below table for examples: 2670 2671 State | Transition Cause | New State | Notes 2672 :-----------------:|:----------------:|:------------------:|:--------------: 2673 INACTIVE | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2674 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | Focus failed after a scan, lens is now locked. 2675 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2676 NOT_FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is good after a scan, lens is not locked. 2677 2678 2679 When android.control.afMode is AF_MODE_CONTINUOUS_VIDEO: 2680 2681 State | Transition Cause | New State | Notes 2682 :-----------------:|:-----------------------------------:|:------------------:|:--------------: 2683 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2684 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2685 PASSIVE_SCAN | Camera device completes current scan| PASSIVE_FOCUSED | End AF scan, Lens now locked 2686 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2687 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, if focus is good. Lens now locked 2688 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, if focus is bad. Lens now locked 2689 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2690 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2691 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2692 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, lens now locked 2693 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, lens now locked 2694 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2695 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2696 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2697 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2698 2699 When android.control.afMode is AF_MODE_CONTINUOUS_PICTURE: 2700 2701 State | Transition Cause | New State | Notes 2702 :-----------------:|:------------------------------------:|:------------------:|:--------------: 2703 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2704 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2705 PASSIVE_SCAN | Camera device completes current scan | PASSIVE_FOCUSED | End AF scan, Lens now locked 2706 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2707 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual transition once the focus is good. Lens now locked 2708 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual transition if cannot find focus. Lens now locked 2709 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2710 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2711 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2712 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. Lens now locked 2713 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. Lens now locked 2714 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2715 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2716 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2717 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2718 2719 When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO 2720 (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the 2721 camera device. When a trigger is included in a mode switch request, the trigger 2722 will be evaluated in the context of the new mode in the request. 2723 See below table for examples: 2724 2725 State | Transition Cause | New State | Notes 2726 :-----------:|:--------------------------------------:|:----------------------------------------:|:--------------: 2727 any state | CAF-->AUTO mode switch | INACTIVE | Mode switch without trigger, initial state must be INACTIVE 2728 any state | CAF-->AUTO mode switch with AF_TRIGGER | trigger-reachable states from INACTIVE | Mode switch with trigger, INACTIVE is skipped 2729 any state | AUTO-->CAF mode switch | passively reachable states from INACTIVE | Mode switch without trigger, passive transient state is skipped 2730 </details> 2731 </entry> 2732 <entry name="afTriggerId" type="int32" visibility="system" deprecated="true"> 2733 <description>The ID sent with the latest 2734 CAMERA2_TRIGGER_AUTOFOCUS call</description> 2735 <deprecation_description> 2736 Removed in camera HAL v3 2737 </deprecation_description> 2738 <details>Must be 0 if no CAMERA2_TRIGGER_AUTOFOCUS trigger 2739 received yet by HAL. Always updated even if AF algorithm 2740 ignores the trigger</details> 2741 </entry> 2742 <clone entry="android.control.awbLock" kind="controls"> 2743 </clone> 2744 <clone entry="android.control.awbMode" kind="controls"> 2745 </clone> 2746 <clone entry="android.control.awbRegions" kind="controls"> 2747 </clone> 2748 <clone entry="android.control.captureIntent" kind="controls"> 2749 </clone> 2750 <entry name="awbState" type="byte" visibility="public" enum="true" 2751 hwlevel="limited"> 2752 <enum> 2753 <value>INACTIVE 2754 <notes>AWB is not in auto mode, or has not yet started metering. 2755 2756 When a camera device is opened, it starts in this 2757 state. This is a transient state, the camera device may 2758 skip reporting this state in capture 2759 result.</notes></value> 2760 <value>SEARCHING 2761 <notes>AWB doesn't yet have a good set of control 2762 values for the current scene. 2763 2764 This is a transient state, the camera device 2765 may skip reporting this state in capture result.</notes></value> 2766 <value>CONVERGED 2767 <notes>AWB has a good set of control values for the 2768 current scene.</notes></value> 2769 <value>LOCKED 2770 <notes>AWB has been locked. 2771 </notes></value> 2772 </enum> 2773 <description>Current state of auto-white balance (AWB) algorithm.</description> 2774 <details>Switching between or enabling AWB modes (android.control.awbMode) always 2775 resets the AWB state to INACTIVE. Similarly, switching between android.control.mode, 2776 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2777 the algorithm states to INACTIVE. 2778 2779 The camera device can do several state transitions between two results, if it is 2780 allowed by the state transition table. So INACTIVE may never actually be seen in 2781 a result. 2782 2783 The state in the result is the state for this image (in sync with this image): if 2784 AWB state becomes CONVERGED, then the image data associated with this result should 2785 be good to use. 2786 2787 Below are state transition tables for different AWB modes. 2788 2789 When `android.control.awbMode != AWB_MODE_AUTO`: 2790 2791 State | Transition Cause | New State | Notes 2792 :------------:|:----------------:|:---------:|:-----------------------: 2793 INACTIVE | |INACTIVE |Camera device auto white balance algorithm is disabled 2794 2795 When android.control.awbMode is AWB_MODE_AUTO: 2796 2797 State | Transition Cause | New State | Notes 2798 :-------------:|:--------------------------------:|:-------------:|:-----------------: 2799 INACTIVE | Camera device initiates AWB scan | SEARCHING | Values changing 2800 INACTIVE | android.control.awbLock is ON | LOCKED | Values locked 2801 SEARCHING | Camera device finishes AWB scan | CONVERGED | Good values, not changing 2802 SEARCHING | android.control.awbLock is ON | LOCKED | Values locked 2803 CONVERGED | Camera device initiates AWB scan | SEARCHING | Values changing 2804 CONVERGED | android.control.awbLock is ON | LOCKED | Values locked 2805 LOCKED | android.control.awbLock is OFF | SEARCHING | Values not good after unlock 2806 2807 For the above table, the camera device may skip reporting any state changes that happen 2808 without application intervention (i.e. mode switch, trigger, locking). Any state that 2809 can be skipped in that manner is called a transient state. 2810 2811 For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions 2812 listed in above table, it is also legal for the camera device to skip one or more 2813 transient states between two results. See below table for examples: 2814 2815 State | Transition Cause | New State | Notes 2816 :-------------:|:--------------------------------:|:-------------:|:-----------------: 2817 INACTIVE | Camera device finished AWB scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2818 LOCKED | android.control.awbLock is OFF | CONVERGED | Values good after unlock, transient states are skipped by camera device. 2819 </details> 2820 </entry> 2821 <clone entry="android.control.effectMode" kind="controls"> 2822 </clone> 2823 <clone entry="android.control.mode" kind="controls"> 2824 </clone> 2825 <clone entry="android.control.sceneMode" kind="controls"> 2826 </clone> 2827 <clone entry="android.control.videoStabilizationMode" kind="controls"> 2828 </clone> 2829 </dynamic> 2830 <static> 2831 <entry name="availableHighSpeedVideoConfigurations" type="int32" visibility="hidden" 2832 container="array" typedef="highSpeedVideoConfiguration" hwlevel="limited"> 2833 <array> 2834 <size>5</size> 2835 <size>n</size> 2836 </array> 2837 <description> 2838 List of available high speed video size, fps range and max batch size configurations 2839 supported by the camera device, in the format of (width, height, fps_min, fps_max, batch_size_max). 2840 </description> 2841 <range> 2842 For each configuration, the fps_max &gt;= 120fps. 2843 </range> 2844 <details> 2845 When CONSTRAINED_HIGH_SPEED_VIDEO is supported in android.request.availableCapabilities, 2846 this metadata will list the supported high speed video size, fps range and max batch size 2847 configurations. All the sizes listed in this configuration will be a subset of the sizes 2848 reported by {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} 2849 for processed non-stalling formats. 2850 2851 For the high speed video use case, the application must 2852 select the video size and fps range from this metadata to configure the recording and 2853 preview streams and setup the recording requests. For example, if the application intends 2854 to do high speed recording, it can select the maximum size reported by this metadata to 2855 configure output streams. Once the size is selected, application can filter this metadata 2856 by selected size and get the supported fps ranges, and use these fps ranges to setup the 2857 recording requests. Note that for the use case of multiple output streams, application 2858 must select one unique size from this metadata to use (e.g., preview and recording streams 2859 must have the same size). Otherwise, the high speed capture session creation will fail. 2860 2861 The min and max fps will be multiple times of 30fps. 2862 2863 High speed video streaming extends significant performance pressue to camera hardware, 2864 to achieve efficient high speed streaming, the camera device may have to aggregate 2865 multiple frames together and send to camera device for processing where the request 2866 controls are same for all the frames in this batch. Max batch size indicates 2867 the max possible number of frames the camera device will group together for this high 2868 speed stream configuration. This max batch size will be used to generate a high speed 2869 recording request list by 2870 {@link android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}. 2871 The max batch size for each configuration will satisfy below conditions: 2872 2873 * Each max batch size will be a divisor of its corresponding fps_max / 30. For example, 2874 if max_fps is 300, max batch size will only be 1, 2, 5, or 10. 2875 * The camera device may choose smaller internal batch size for each configuration, but 2876 the actual batch size will be a divisor of max batch size. For example, if the max batch 2877 size is 8, the actual batch size used by camera device will only be 1, 2, 4, or 8. 2878 * The max batch size in each configuration entry must be no larger than 32. 2879 2880 The camera device doesn't have to support batch mode to achieve high speed video recording, 2881 in such case, batch_size_max will be reported as 1 in each configuration entry. 2882 2883 This fps ranges in this configuration list can only be used to create requests 2884 that are submitted to a high speed camera capture session created by 2885 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. 2886 The fps ranges reported in this metadata must not be used to setup capture requests for 2887 normal capture session, or it will cause request error. 2888 </details> 2889 <hal_details> 2890 All the sizes listed in this configuration will be a subset of the sizes reported by 2891 android.scaler.availableStreamConfigurations for processed non-stalling output formats. 2892 Note that for all high speed video configurations, HAL must be able to support a minimum 2893 of two streams, though the application might choose to configure just one stream. 2894 2895 The HAL may support multiple sensor modes for high speed outputs, for example, 120fps 2896 sensor mode and 120fps recording, 240fps sensor mode for 240fps recording. The application 2897 usually starts preview first, then starts recording. To avoid sensor mode switch caused 2898 stutter when starting recording as much as possible, the application may want to ensure 2899 the same sensor mode is used for preview and recording. Therefore, The HAL must advertise 2900 the variable fps range [30, fps_max] for each fixed fps range in this configuration list. 2901 For example, if the HAL advertises [120, 120] and [240, 240], the HAL must also advertise 2902 [30, 120] and [30, 240] for each configuration. In doing so, if the application intends to 2903 do 120fps recording, it can select [30, 120] to start preview, and [120, 120] to start 2904 recording. For these variable fps ranges, it's up to the HAL to decide the actual fps 2905 values that are suitable for smooth preview streaming. If the HAL sees different max_fps 2906 values that fall into different sensor modes in a sequence of requests, the HAL must 2907 switch the sensor mode as quick as possible to minimize the mode switch caused stutter. 2908 </hal_details> 2909 <tag id="V1" /> 2910 </entry> 2911 <entry name="aeLockAvailable" type="byte" visibility="public" enum="true" 2912 typedef="boolean" hwlevel="legacy"> 2913 <enum> 2914 <value>FALSE</value> 2915 <value>TRUE</value> 2916 </enum> 2917 <description>Whether the camera device supports android.control.aeLock</description> 2918 <details> 2919 Devices with MANUAL_SENSOR capability or BURST_CAPTURE capability will always 2920 list `true`. This includes FULL devices. 2921 </details> 2922 <tag id="BC"/> 2923 </entry> 2924 <entry name="awbLockAvailable" type="byte" visibility="public" enum="true" 2925 typedef="boolean" hwlevel="legacy"> 2926 <enum> 2927 <value>FALSE</value> 2928 <value>TRUE</value> 2929 </enum> 2930 <description>Whether the camera device supports android.control.awbLock</description> 2931 <details> 2932 Devices with MANUAL_POST_PROCESSING capability or BURST_CAPTURE capability will 2933 always list `true`. This includes FULL devices. 2934 </details> 2935 <tag id="BC"/> 2936 </entry> 2937 <entry name="availableModes" type="byte" visibility="public" 2938 type_notes="List of enums (android.control.mode)." container="array" 2939 typedef="enumList" hwlevel="legacy"> 2940 <array> 2941 <size>n</size> 2942 </array> 2943 <description> 2944 List of control modes for android.control.mode that are supported by this camera 2945 device. 2946 </description> 2947 <range>Any value listed in android.control.mode</range> 2948 <details> 2949 This list contains control modes that can be set for the camera device. 2950 LEGACY mode devices will always support AUTO mode. LIMITED and FULL 2951 devices will always support OFF, AUTO modes. 2952 </details> 2953 </entry> 2954 <entry name="postRawSensitivityBoostRange" type="int32" visibility="public" 2955 type_notes="Range of supported post RAW sensitivitiy boosts" 2956 container="array" typedef="rangeInt"> 2957 <array> 2958 <size>2</size> 2959 </array> 2960 <description>Range of boosts for android.control.postRawSensitivityBoost supported 2961 by this camera device. 2962 </description> 2963 <units>ISO arithmetic units, the same as android.sensor.sensitivity</units> 2964 <details> 2965 Devices support post RAW sensitivity boost will advertise 2966 android.control.postRawSensitivityBoost key for controling 2967 post RAW sensitivity boost. 2968 2969 This key will be `null` for devices that do not support any RAW format 2970 outputs. For devices that do support RAW format outputs, this key will always 2971 present, and if a device does not support post RAW sensitivity boost, it will 2972 list `(100, 100)` in this key. 2973 </details> 2974 <hal_details> 2975 This key is added in legacy HAL3.4. For legacy HAL3.3 or earlier devices, camera 2976 framework will generate this key as `(100, 100)` if device supports any of RAW output 2977 formats. All legacy HAL3.4 and above devices should list this key if device supports 2978 any of RAW output formats. 2979 </hal_details> 2980 </entry> 2981 </static> 2982 <controls> 2983 <entry name="postRawSensitivityBoost" type="int32" visibility="public"> 2984 <description>The amount of additional sensitivity boost applied to output images 2985 after RAW sensor data is captured. 2986 </description> 2987 <units>ISO arithmetic units, the same as android.sensor.sensitivity</units> 2988 <range>android.control.postRawSensitivityBoostRange</range> 2989 <details> 2990 Some camera devices support additional digital sensitivity boosting in the 2991 camera processing pipeline after sensor RAW image is captured. 2992 Such a boost will be applied to YUV/JPEG format output images but will not 2993 have effect on RAW output formats like RAW_SENSOR, RAW10, RAW12 or RAW_OPAQUE. 2994 2995 This key will be `null` for devices that do not support any RAW format 2996 outputs. For devices that do support RAW format outputs, this key will always 2997 present, and if a device does not support post RAW sensitivity boost, it will 2998 list `100` in this key. 2999 3000 If the camera device cannot apply the exact boost requested, it will reduce the 3001 boost to the nearest supported value. 3002 The final boost value used will be available in the output capture result. 3003 3004 For devices that support post RAW sensitivity boost, the YUV/JPEG output images 3005 of such device will have the total sensitivity of 3006 `android.sensor.sensitivity * android.control.postRawSensitivityBoost / 100` 3007 The sensitivity of RAW format images will always be `android.sensor.sensitivity` 3008 3009 This control is only effective if android.control.aeMode or android.control.mode is set to 3010 OFF; otherwise the auto-exposure algorithm will override this value. 3011 </details> 3012 </entry> 3013 </controls> 3014 <dynamic> 3015 <clone entry="android.control.postRawSensitivityBoost" kind="controls"> 3016 </clone> 3017 </dynamic> 3018 <controls> 3019 <entry name="enableZsl" type="byte" visibility="public" enum="true" typedef="boolean"> 3020 <enum> 3021 <value>FALSE 3022 <notes>Requests with android.control.captureIntent == STILL_CAPTURE must be captured 3023 after previous requests.</notes></value> 3024 <value>TRUE 3025 <notes>Requests with android.control.captureIntent == STILL_CAPTURE may or may not be 3026 captured before previous requests.</notes></value> 3027 </enum> 3028 <description>Allow camera device to enable zero-shutter-lag mode for requests with 3029 android.control.captureIntent == STILL_CAPTURE. 3030 </description> 3031 <details> 3032 If enableZsl is `true`, the camera device may enable zero-shutter-lag mode for requests with 3033 STILL_CAPTURE capture intent. The camera device may use images captured in the past to 3034 produce output images for a zero-shutter-lag request. The result metadata including the 3035 android.sensor.timestamp reflects the source frames used to produce output images. 3036 Therefore, the contents of the output images and the result metadata may be out of order 3037 compared to previous regular requests. enableZsl does not affect requests with other 3038 capture intents. 3039 3040 For example, when requests are submitted in the following order: 3041 Request A: enableZsl is ON, android.control.captureIntent is PREVIEW 3042 Request B: enableZsl is ON, android.control.captureIntent is STILL_CAPTURE 3043 3044 The output images for request B may have contents captured before the output images for 3045 request A, and the result metadata for request B may be older than the result metadata for 3046 request A. 3047 3048 Note that when enableZsl is `true`, it is not guaranteed to get output images captured in 3049 the past for requests with STILL_CAPTURE capture intent. 3050 3051 For applications targeting SDK versions O and newer, the value of enableZsl in 3052 TEMPLATE_STILL_CAPTURE template may be `true`. The value in other templates is always 3053 `false` if present. 3054 3055 For applications targeting SDK versions older than O, the value of enableZsl in all 3056 capture templates is always `false` if present. 3057 3058 For application-operated ZSL, use CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 3059 </details> 3060 <hal_details> 3061 It is valid for HAL to produce regular output images for requests with STILL_CAPTURE 3062 capture intent. 3063 </hal_details> 3064 </entry> 3065 </controls> 3066 <dynamic> 3067 <clone entry="android.control.enableZsl" kind="controls"> 3068 </clone> 3069 <entry name="afSceneChange" type="byte" visibility="public" enum="true" hal_version="3.3"> 3070 <enum> 3071 <value>NOT_DETECTED 3072 <notes>Scene change is not detected within the AF region(s).</notes></value> 3073 <value>DETECTED 3074 <notes>Scene change is detected within the AF region(s).</notes></value> 3075 </enum> 3076 <description>Whether a significant scene change is detected within the currently-set AF 3077 region(s).</description> 3078 <details>When the camera focus routine detects a change in the scene it is looking at, 3079 such as a large shift in camera viewpoint, significant motion in the scene, or a 3080 significant illumination change, this value will be set to DETECTED for a single capture 3081 result. Otherwise the value will be NOT_DETECTED. The threshold for detection is similar 3082 to what would trigger a new passive focus scan to begin in CONTINUOUS autofocus modes. 3083 3084 This key will be available if the camera device advertises this key via {@link 3085 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 3086 </details> 3087 </entry> 3088 </dynamic> 3089 <static> 3090 <entry name="availableExtendedSceneModeMaxSizes" type="int32" 3091 visibility="ndk_public" optional="true" 3092 type_notes="List of extended scene modes and the corresponding max streaming sizes." 3093 container="array" hwlevel="limited" hal_version="3.5"> 3094 <array> 3095 <size>3</size> 3096 <size>n</size> 3097 </array> 3098 <description> 3099 The list of extended scene modes for android.control.extendedSceneMode that are supported 3100 by this camera device, and each extended scene mode's maximum streaming (non-stall) size 3101 with effect. 3102 </description> 3103 <units>(mode, width, height)</units> 3104 <details> 3105 For DISABLED mode, the camera behaves normally with no extended scene mode enabled. 3106 3107 For BOKEH_STILL_CAPTURE mode, the maximum streaming dimension specifies the limit 3108 under which bokeh is effective when capture intent is PREVIEW. Note that when capture 3109 intent is PREVIEW, the bokeh effect may not be as high in quality compared to 3110 STILL_CAPTURE intent in order to maintain reasonable frame rate. The maximum streaming 3111 dimension must be one of the YUV_420_888 or PRIVATE resolutions in 3112 availableStreamConfigurations, or (0, 0) if preview bokeh is not supported. If the 3113 application configures a stream larger than the maximum streaming dimension, bokeh 3114 effect may not be applied for this stream for PREVIEW intent. 3115 3116 For BOKEH_CONTINUOUS mode, the maximum streaming dimension specifies the limit under 3117 which bokeh is effective. This dimension must be one of the YUV_420_888 or PRIVATE 3118 resolutions in availableStreamConfigurations, and if the sensor maximum resolution is 3119 larger than or equal to 1080p, the maximum streaming dimension must be at least 1080p. 3120 If the application configures a stream with larger dimension, the stream may not have 3121 bokeh effect applied. 3122 </details> 3123 <hal_details> 3124 For available extended scene modes, DISABLED will always be listed. 3125 3126 HAL must support at list one non-OFF extended scene mode if extendedSceneMode control is 3127 available on the camera device. For DISABLED mode, the maximum streaming resolution must 3128 be set to (0, 0). 3129 </hal_details> 3130 </entry> 3131 <entry name="availableExtendedSceneModeZoomRatioRanges" type="float" 3132 visibility="ndk_public" optional="true" 3133 type_notes="Zoom ranges for all supported non-OFF extended scene modes." 3134 container="array" hwlevel="limited" hal_version="3.5"> 3135 <array> 3136 <size>2</size> 3137 <size>n</size> 3138 </array> 3139 <description> 3140 The ranges of supported zoom ratio for non-DISABLED android.control.extendedSceneMode. 3141 </description> 3142 <units>(minZoom, maxZoom)</units> 3143 <details> 3144 When extended scene mode is set, the camera device may have limited range of zoom ratios 3145 compared to when extended scene mode is DISABLED. This tag lists the zoom ratio ranges 3146 for all supported non-DISABLED extended scene modes, in the same order as in 3147 android.control.availableExtended. 3148 3149 Range [1.0, 1.0] means that no zoom (optical or digital) is supported. 3150 </details> 3151 </entry> 3152 <entry name="availableExtendedSceneModeCapabilities" type="int32" visibility="public" 3153 synthetic="true" container="array" typedef="capability" hal_version="3.5"> 3154 <array> 3155 <size>n</size> 3156 </array> 3157 <description>The list of extended scene modes for android.control.extendedSceneMode that 3158 are supported by this camera device, and each extended scene mode's capabilities such 3159 as maximum streaming size, and supported zoom ratio ranges.</description> 3160 <details> 3161 For DISABLED mode, the camera behaves normally with no extended scene mode enabled. 3162 3163 For BOKEH_STILL_CAPTURE mode, the maximum streaming dimension specifies the limit 3164 under which bokeh is effective when capture intent is PREVIEW. Note that when capture 3165 intent is PREVIEW, the bokeh effect may not be as high quality compared to STILL_CAPTURE 3166 intent in order to maintain reasonable frame rate. The maximum streaming dimension must 3167 be one of the YUV_420_888 or PRIVATE resolutions in availableStreamConfigurations, or 3168 (0, 0) if preview bokeh is not supported. If the application configures a stream 3169 larger than the maximum streaming dimension, bokeh effect may not be applied for this 3170 stream for PREVIEW intent. 3171 3172 For BOKEH_CONTINUOUS mode, the maximum streaming dimension specifies the limit under 3173 which bokeh is effective. This dimension must be one of the YUV_420_888 or PRIVATE 3174 resolutions in availableStreamConfigurations, and if the sensor maximum resolution is 3175 larger than or equal to 1080p, the maximum streaming dimension must be at least 1080p. 3176 If the application configures a stream with larger dimension, the stream may not have 3177 bokeh effect applied. 3178 3179 When extended scene mode is set, the camera device may have limited range of zoom ratios 3180 compared to when the mode is DISABLED. availableExtendedSceneModeCapabilities lists the 3181 zoom ranges for all supported extended modes. A range of (1.0, 1.0) means that no zoom 3182 (optical or digital) is supported. 3183 </details> 3184 </entry> 3185 </static> 3186 <controls> 3187 <entry name="extendedSceneMode" type="byte" visibility="public" optional="true" 3188 enum="true" hal_version="3.5"> 3189 <enum> 3190 <value id="0">DISABLED 3191 <notes>Extended scene mode is disabled.</notes></value> 3192 <value>BOKEH_STILL_CAPTURE 3193 <notes>High quality bokeh mode is enabled for all non-raw streams (including YUV, 3194 JPEG, and IMPLEMENTATION_DEFINED) when capture intent is STILL_CAPTURE. Due to the 3195 extra image processing, this mode may introduce additional stall to non-raw streams. 3196 This mode should be used in high quality still capture use case. 3197 </notes> 3198 </value> 3199 <value>BOKEH_CONTINUOUS 3200 <notes>Bokeh effect must not slow down capture rate relative to sensor raw output, 3201 and the effect is applied to all processed streams no larger than the maximum 3202 streaming dimension. This mode should be used if performance and power are a 3203 priority, such as video recording. 3204 </notes> 3205 </value> 3206 <value visibility="hidden" id="0x40">VENDOR_START 3207 <notes> 3208 Vendor defined extended scene modes. These depend on vendor implementation. 3209 </notes> 3210 </value> 3211 </enum> 3212 <description>Whether extended scene mode is enabled for a particular capture request. 3213 </description> 3214 <details> 3215 With bokeh mode, the camera device may blur out the parts of scene that are not in 3216 focus, creating a bokeh (or shallow depth of field) effect for people or objects. 3217 3218 When set to BOKEH_STILL_CAPTURE mode with STILL_CAPTURE capture intent, due to the extra 3219 processing needed for high quality bokeh effect, the stall may be longer than when 3220 capture intent is not STILL_CAPTURE. 3221 3222 When set to BOKEH_STILL_CAPTURE mode with PREVIEW capture intent, 3223 3224 * If the camera device has BURST_CAPTURE capability, the frame rate requirement of 3225 BURST_CAPTURE must still be met. 3226 * All streams not larger than the maximum streaming dimension for BOKEH_STILL_CAPTURE mode 3227 (queried via {@link android.hardware.camera2.CameraCharacteristics#CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_CAPABILITIES|ACAMERA_CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_MAX_SIZES}) 3228 will have preview bokeh effect applied. 3229 3230 When set to BOKEH_CONTINUOUS mode, configured streams dimension should not exceed this mode's 3231 maximum streaming dimension in order to have bokeh effect applied. Bokeh effect may not 3232 be available for streams larger than the maximum streaming dimension. 3233 3234 Switching between different extended scene modes may involve reconfiguration of the camera 3235 pipeline, resulting in long latency. The application should check this key against the 3236 available session keys queried via 3237 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 3238 3239 For a logical multi-camera, bokeh may be implemented by stereo vision from sub-cameras 3240 with different field of view. As a result, when bokeh mode is enabled, the camera device 3241 may override android.scaler.cropRegion or android.control.zoomRatio, and the field of 3242 view may be smaller than when bokeh mode is off. 3243 </details> 3244 </entry> 3245 </controls> 3246 <dynamic> 3247 <clone entry="android.control.extendedSceneMode" kind="controls"> 3248 </clone> 3249 </dynamic> 3250 <static> 3251 <entry name="zoomRatioRange" type="float" visibility="public" 3252 type_notes="The range of zoom ratios that this camera device supports." 3253 container="array" typedef="rangeFloat" hwlevel="limited" hal_version="3.5"> 3254 <array> 3255 <size>2</size> 3256 </array> 3257 <description> 3258 Minimum and maximum zoom ratios supported by this camera device. 3259 </description> 3260 <units>A pair of zoom ratio in floating-points: (minZoom, maxZoom)</units> 3261 <range> 3262 maxZoom >= 1.0 >= minZoom 3263 </range> 3264 <details> 3265 If the camera device supports zoom-out from 1x zoom, minZoom will be less than 1.0, and 3266 setting android.control.zoomRatio to values less than 1.0 increases the camera's field 3267 of view. 3268 </details> 3269 <hal_details> 3270 When the key is reported, the camera device's android.scaler.availableMaxDigitalZoom 3271 must be less than or equal to maxZoom. The camera framework makes sure to always 3272 control zoom via android.control.zoomRatio. The android.scaler.cropRegion tag is only 3273 used to do horizontal or vertical cropping (but not both) to achieve aspect ratio 3274 different than the camera sensor's native aspect ratio. 3275 3276 For a logical multi-camera device, this key must either be reported for both the logical 3277 camera device and all its physical sub-cameras, or none of them. 3278 3279 When the key is not reported, camera framework derives the application-facing 3280 zoomRatioRange to be (1, android.scaler.availableMaxDigitalZoom). 3281 </hal_details> 3282 </entry> 3283 </static> 3284 <controls> 3285 <entry name="zoomRatio" type="float" visibility="public" hwlevel="limited" 3286 hal_version="3.5"> 3287 <description> 3288 The desired zoom ratio 3289 </description> 3290 <range>android.control.zoomRatioRange</range> 3291 <details> 3292 Instead of using android.scaler.cropRegion for zoom, the application can now choose to 3293 use this tag to specify the desired zoom level. 3294 3295 By using this control, the application gains a simpler way to control zoom, which can 3296 be a combination of optical and digital zoom. For example, a multi-camera system may 3297 contain more than one lens with different focal lengths, and the user can use optical 3298 zoom by switching between lenses. Using zoomRatio has benefits in the scenarios below: 3299 3300 * Zooming in from a wide-angle lens to a telephoto lens: A floating-point ratio provides 3301 better precision compared to an integer value of android.scaler.cropRegion. 3302 * Zooming out from a wide lens to an ultrawide lens: zoomRatio supports zoom-out whereas 3303 android.scaler.cropRegion doesn't. 3304 3305 To illustrate, here are several scenarios of different zoom ratios, crop regions, 3306 and output streams, for a hypothetical camera device with an active array of size 3307 `(2000,1500)`. 3308 3309 * Camera Configuration: 3310 * Active array size: `2000x1500` (3 MP, 4:3 aspect ratio) 3311 * Output stream #1: `640x480` (VGA, 4:3 aspect ratio) 3312 * Output stream #2: `1280x720` (720p, 16:9 aspect ratio) 3313 * Case #1: 4:3 crop region with 2.0x zoom ratio 3314 * Zoomed field of view: 1/4 of original field of view 3315 * Crop region: `Rect(0, 0, 2000, 1500) // (left, top, right, bottom)` (post zoom) 3316 *  3317 * `640x480` stream source area: `(0, 0, 2000, 1500)` (equal to crop region) 3318 * `1280x720` stream source area: `(0, 187, 2000, 1312)` (letterboxed) 3319 * Case #2: 16:9 crop region with 2.0x zoom. 3320 * Zoomed field of view: 1/4 of original field of view 3321 * Crop region: `Rect(0, 187, 2000, 1312)` 3322 *  3323 * `640x480` stream source area: `(250, 187, 1750, 1312)` (pillarboxed) 3324 * `1280x720` stream source area: `(0, 187, 2000, 1312)` (equal to crop region) 3325 * Case #3: 1:1 crop region with 0.5x zoom out to ultrawide lens. 3326 * Zoomed field of view: 4x of original field of view (switched from wide lens to ultrawide lens) 3327 * Crop region: `Rect(250, 0, 1750, 1500)` 3328 *  3329 * `640x480` stream source area: `(250, 187, 1750, 1312)` (letterboxed) 3330 * `1280x720` stream source area: `(250, 328, 1750, 1172)` (letterboxed) 3331 3332 As seen from the graphs above, the coordinate system of cropRegion now changes to the 3333 effective after-zoom field-of-view, and is represented by the rectangle of (0, 0, 3334 activeArrayWith, activeArrayHeight). The same applies to AE/AWB/AF regions, and faces. 3335 This coordinate system change isn't applicable to RAW capture and its related 3336 metadata such as intrinsicCalibration and lensShadingMap. 3337 3338 Using the same hypothetical example above, and assuming output stream #1 (640x480) is 3339 the viewfinder stream, the application can achieve 2.0x zoom in one of two ways: 3340 3341 * zoomRatio = 2.0, scaler.cropRegion = (0, 0, 2000, 1500) 3342 * zoomRatio = 1.0 (default), scaler.cropRegion = (500, 375, 1500, 1125) 3343 3344 If the application intends to set aeRegions to be top-left quarter of the viewfinder 3345 field-of-view, the android.control.aeRegions should be set to (0, 0, 1000, 750) with 3346 zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent 3347 region of (500, 375, 1000, 750) for zoomRatio of 1.0. If the application doesn't 3348 explicitly set android.control.zoomRatio, its value defaults to 1.0. 3349 3350 One limitation of controlling zoom using zoomRatio is that the android.scaler.cropRegion 3351 must only be used for letterboxing or pillarboxing of the sensor active array, and no 3352 FREEFORM cropping can be used with android.control.zoomRatio other than 1.0. If 3353 android.control.zoomRatio is not 1.0, and android.scaler.cropRegion is set to be 3354 windowboxing, the camera framework will override the android.scaler.cropRegion to be 3355 the active array. 3356 3357 In the capture request, if the application sets android.control.zoomRatio to a 3358 value != 1.0, the android.control.zoomRatio tag in the capture result reflects the 3359 effective zoom ratio achieved by the camera device, and the android.scaler.cropRegion 3360 adjusts for additional crops that are not zoom related. Otherwise, if the application 3361 sets android.control.zoomRatio to 1.0, or does not set it at all, the 3362 android.control.zoomRatio tag in the result metadata will also be 1.0. 3363 3364 When the application requests a physical stream for a logical multi-camera, the 3365 android.control.zoomRatio in the physical camera result metadata will be 1.0, and 3366 the android.scaler.cropRegion tag reflects the amount of zoom and crop done by the 3367 physical camera device. 3368 </details> 3369 <hal_details> 3370 For all capture request templates, this field must be set to 1.0 in order to have 3371 consistent field of views between different modes. 3372 </hal_details> 3373 </entry> 3374 </controls> 3375 <dynamic> 3376 <clone entry="android.control.zoomRatio" kind="controls"> 3377 </clone> 3378 </dynamic> 3379 <static> 3380 <entry name="availableHighSpeedVideoConfigurationsMaximumResolution" type="int32" 3381 visibility="hidden" container="array" typedef="highSpeedVideoConfiguration" 3382 hal_version="3.6"> 3383 <array> 3384 <size>5</size> 3385 <size>n</size> 3386 </array> 3387 <description> 3388 List of available high speed video size, fps range and max batch size configurations 3389 supported by the camera device, in the format of 3390 (width, height, fps_min, fps_max, batch_size_max), 3391 when android.sensor.pixelMode is set to 3392 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 3393 </description> 3394 <range> 3395 For each configuration, the fps_max &gt;= 120fps. 3396 </range> 3397 <details> 3398 Analogous to android.control.availableHighSpeedVideoConfigurations, for configurations 3399 which are applicable when android.sensor.pixelMode is set to 3400 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 3401 </details> 3402 <hal_details> 3403 Refer to hal details for android.control.availableHighSpeedVideoConfigurations. 3404 </hal_details> 3405 <tag id="V1" /> 3406 </entry> 3407 </static> 3408 <controls> 3409 <entry name="afRegionsSet" type="byte" visibility="fwk_only" 3410 enum="true" typedef="boolean"> 3411 <enum> 3412 <value>FALSE 3413 <notes>AF regions (android.control.afRegions) have not been set by the camera client. 3414 </notes> 3415 </value> 3416 <value>TRUE 3417 <notes> 3418 AF regions (android.control.afRegions) have been set by the camera client. 3419 </notes> 3420 </value> 3421 </enum> 3422 <description> 3423 Framework-only private key which informs camera fwk that the AF regions has been set 3424 by the client and those regions need not be corrected when android.sensor.pixelMode is 3425 set to MAXIMUM_RESOLUTION. 3426 </description> 3427 <details> 3428 This must be set to TRUE by the camera2 java fwk when the camera client sets 3429 android.control.afRegions. 3430 </details> 3431 </entry> 3432 <entry name="aeRegionsSet" type="byte" visibility="fwk_only" 3433 enum="true" typedef="boolean"> 3434 <enum> 3435 <value>FALSE 3436 <notes> AE regions (android.control.aeRegions) have not been set by the camera client. 3437 </notes> 3438 </value> 3439 <value>TRUE 3440 <notes> 3441 AE regions (android.control.aeRegions) have been set by the camera client. 3442 </notes> 3443 </value> 3444 </enum> 3445 <description> 3446 Framework-only private key which informs camera fwk that the AE regions has been set 3447 by the client and those regions need not be corrected when android.sensor.pixelMode is 3448 set to MAXIMUM_RESOLUTION. 3449 </description> 3450 <details> 3451 This must be set to TRUE by the camera2 java fwk when the camera client sets 3452 android.control.aeRegions. 3453 </details> 3454 </entry> 3455 <entry name="awbRegionsSet" type="byte" visibility="fwk_only" 3456 enum="true" typedef="boolean"> 3457 <enum> 3458 <value>FALSE 3459 <notes> AWB regions (android.control.awbRegions) have not been set by the camera client. 3460 </notes> 3461 </value> 3462 <value>TRUE 3463 <notes> 3464 AWB regions (android.control.awbRegions) have been set by the camera client. 3465 </notes> 3466 </value> 3467 </enum> 3468 <description> 3469 Framework-only private key which informs camera fwk that the AF regions has been set 3470 by the client and those regions need not be corrected when android.sensor.pixelMode is 3471 set to MAXIMUM_RESOLUTION. 3472 </description> 3473 <details> 3474 This must be set to TRUE by the camera2 java fwk when the camera client sets 3475 android.control.awbRegions. 3476 </details> 3477 </entry> 3478 </controls> 3479 </section> 3480 <section name="demosaic"> 3481 <controls> 3482 <entry name="mode" type="byte" enum="true"> 3483 <enum> 3484 <value>FAST 3485 <notes>Minimal or no slowdown of frame rate compared to 3486 Bayer RAW output.</notes></value> 3487 <value>HIGH_QUALITY 3488 <notes>Improved processing quality but the frame rate might be slowed down 3489 relative to raw output.</notes></value> 3490 </enum> 3491 <description>Controls the quality of the demosaicing 3492 processing.</description> 3493 <tag id="FUTURE" /> 3494 </entry> 3495 </controls> 3496 </section> 3497 <section name="edge"> 3498 <controls> 3499 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 3500 <enum> 3501 <value>OFF 3502 <notes>No edge enhancement is applied.</notes></value> 3503 <value>FAST 3504 <notes>Apply edge enhancement at a quality level that does not slow down frame rate 3505 relative to sensor output. It may be the same as OFF if edge enhancement will 3506 slow down frame rate relative to sensor.</notes></value> 3507 <value>HIGH_QUALITY 3508 <notes>Apply high-quality edge enhancement, at a cost of possibly reduced output frame rate. 3509 </notes></value> 3510 <value optional="true">ZERO_SHUTTER_LAG <notes>Edge enhancement is applied at different 3511 levels for different output streams, based on resolution. Streams at maximum recording 3512 resolution (see {@link 3513 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession}) 3514 or below have edge enhancement applied, while higher-resolution streams have no edge 3515 enhancement applied. The level of edge enhancement for low-resolution streams is tuned 3516 so that frame rate is not impacted, and the quality is equal to or better than FAST 3517 (since it is only applied to lower-resolution outputs, quality may improve from FAST). 3518 3519 This mode is intended to be used by applications operating in a zero-shutter-lag mode 3520 with YUV or PRIVATE reprocessing, where the application continuously captures 3521 high-resolution intermediate buffers into a circular buffer, from which a final image is 3522 produced via reprocessing when a user takes a picture. For such a use case, the 3523 high-resolution buffers must not have edge enhancement applied to maximize efficiency of 3524 preview and to avoid double-applying enhancement when reprocessed, while low-resolution 3525 buffers (used for recording or preview, generally) need edge enhancement applied for 3526 reasonable preview quality. 3527 3528 This mode is guaranteed to be supported by devices that support either the 3529 YUV_REPROCESSING or PRIVATE_REPROCESSING capabilities 3530 (android.request.availableCapabilities lists either of those capabilities) and it will 3531 be the default mode for CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 3532 </notes></value> 3533 </enum> 3534 <description>Operation mode for edge 3535 enhancement.</description> 3536 <range>android.edge.availableEdgeModes</range> 3537 <details>Edge enhancement improves sharpness and details in the captured image. OFF means 3538 no enhancement will be applied by the camera device. 3539 3540 FAST/HIGH_QUALITY both mean camera device determined enhancement 3541 will be applied. HIGH_QUALITY mode indicates that the 3542 camera device will use the highest-quality enhancement algorithms, 3543 even if it slows down capture rate. FAST means the camera device will 3544 not slow down capture rate when applying edge enhancement. FAST may be the same as OFF if 3545 edge enhancement will slow down capture rate. Every output stream will have a similar 3546 amount of enhancement applied. 3547 3548 ZERO_SHUTTER_LAG is meant to be used by applications that maintain a continuous circular 3549 buffer of high-resolution images during preview and reprocess image(s) from that buffer 3550 into a final capture when triggered by the user. In this mode, the camera device applies 3551 edge enhancement to low-resolution streams (below maximum recording resolution) to 3552 maximize preview quality, but does not apply edge enhancement to high-resolution streams, 3553 since those will be reprocessed later if necessary. 3554 3555 For YUV_REPROCESSING, these FAST/HIGH_QUALITY modes both mean that the camera 3556 device will apply FAST/HIGH_QUALITY YUV-domain edge enhancement, respectively. 3557 The camera device may adjust its internal edge enhancement parameters for best 3558 image quality based on the android.reprocess.effectiveExposureFactor, if it is set. 3559 </details> 3560 <hal_details> 3561 For YUV_REPROCESSING The HAL can use android.reprocess.effectiveExposureFactor to 3562 adjust the internal edge enhancement reduction parameters appropriately to get the best 3563 quality images. 3564 </hal_details> 3565 <tag id="V1" /> 3566 <tag id="REPROC" /> 3567 </entry> 3568 <entry name="strength" type="byte"> 3569 <description>Control the amount of edge enhancement 3570 applied to the images</description> 3571 <units>1-10; 10 is maximum sharpening</units> 3572 <tag id="FUTURE" /> 3573 </entry> 3574 </controls> 3575 <static> 3576 <entry name="availableEdgeModes" type="byte" visibility="public" 3577 type_notes="list of enums" container="array" typedef="enumList" 3578 hwlevel="full"> 3579 <array> 3580 <size>n</size> 3581 </array> 3582 <description> 3583 List of edge enhancement modes for android.edge.mode that are supported by this camera 3584 device. 3585 </description> 3586 <range>Any value listed in android.edge.mode</range> 3587 <details> 3588 Full-capability camera devices must always support OFF; camera devices that support 3589 YUV_REPROCESSING or PRIVATE_REPROCESSING will list ZERO_SHUTTER_LAG; all devices will 3590 list FAST. 3591 </details> 3592 <hal_details> 3593 HAL must support both FAST and HIGH_QUALITY if edge enhancement control is available 3594 on the camera device, but the underlying implementation can be the same for both modes. 3595 That is, if the highest quality implementation on the camera device does not slow down 3596 capture rate, then FAST and HIGH_QUALITY will generate the same output. 3597 </hal_details> 3598 <tag id="V1" /> 3599 <tag id="REPROC" /> 3600 </entry> 3601 </static> 3602 <dynamic> 3603 <clone entry="android.edge.mode" kind="controls"> 3604 <tag id="V1" /> 3605 <tag id="REPROC" /> 3606 </clone> 3607 </dynamic> 3608 </section> 3609 <section name="flash"> 3610 <controls> 3611 <entry name="firingPower" type="byte"> 3612 <description>Power for flash firing/torch</description> 3613 <units>10 is max power; 0 is no flash. Linear</units> 3614 <range>0 - 10</range> 3615 <details>Power for snapshot may use a different scale than 3616 for torch mode. Only one entry for torch mode will be 3617 used</details> 3618 <tag id="FUTURE" /> 3619 </entry> 3620 <entry name="firingTime" type="int64"> 3621 <description>Firing time of flash relative to start of 3622 exposure</description> 3623 <units>nanoseconds</units> 3624 <range>0-(exposure time-flash duration)</range> 3625 <details>Clamped to (0, exposure time - flash 3626 duration).</details> 3627 <tag id="FUTURE" /> 3628 </entry> 3629 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 3630 <enum> 3631 <value>OFF 3632 <notes> 3633 Do not fire the flash for this capture. 3634 </notes> 3635 </value> 3636 <value>SINGLE 3637 <notes> 3638 If the flash is available and charged, fire flash 3639 for this capture. 3640 </notes> 3641 </value> 3642 <value>TORCH 3643 <notes> 3644 Transition flash to continuously on. 3645 </notes> 3646 </value> 3647 </enum> 3648 <description>The desired mode for for the camera device's flash control.</description> 3649 <details> 3650 This control is only effective when flash unit is available 3651 (`android.flash.info.available == true`). 3652 3653 When this control is used, the android.control.aeMode must be set to ON or OFF. 3654 Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH, 3655 ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control. 3656 3657 When set to OFF, the camera device will not fire flash for this capture. 3658 3659 When set to SINGLE, the camera device will fire flash regardless of the camera 3660 device's auto-exposure routine's result. When used in still capture case, this 3661 control should be used along with auto-exposure (AE) precapture metering sequence 3662 (android.control.aePrecaptureTrigger), otherwise, the image may be incorrectly exposed. 3663 3664 When set to TORCH, the flash will be on continuously. This mode can be used 3665 for use cases such as preview, auto-focus assist, still capture, or video recording. 3666 3667 The flash status will be reported by android.flash.state in the capture result metadata. 3668 </details> 3669 <tag id="BC" /> 3670 </entry> 3671 </controls> 3672 <static> 3673 <namespace name="info"> 3674 <entry name="available" type="byte" visibility="public" enum="true" 3675 typedef="boolean" hwlevel="legacy"> 3676 <enum> 3677 <value>FALSE</value> 3678 <value>TRUE</value> 3679 </enum> 3680 <description>Whether this camera device has a 3681 flash unit.</description> 3682 <details> 3683 Will be `false` if no flash is available. 3684 3685 If there is no flash unit, none of the flash controls do 3686 anything.</details> 3687 <tag id="BC" /> 3688 </entry> 3689 <entry name="chargeDuration" type="int64"> 3690 <description>Time taken before flash can fire 3691 again</description> 3692 <units>nanoseconds</units> 3693 <range>0-1e9</range> 3694 <details>1 second too long/too short for recharge? Should 3695 this be power-dependent?</details> 3696 <tag id="FUTURE" /> 3697 </entry> 3698 </namespace> 3699 <entry name="colorTemperature" type="byte"> 3700 <description>The x,y whitepoint of the 3701 flash</description> 3702 <units>pair of floats</units> 3703 <range>0-1 for both</range> 3704 <tag id="FUTURE" /> 3705 </entry> 3706 <entry name="maxEnergy" type="byte"> 3707 <description>Max energy output of the flash for a full 3708 power single flash</description> 3709 <units>lumen-seconds</units> 3710 <range>&gt;= 0</range> 3711 <tag id="FUTURE" /> 3712 </entry> 3713 </static> 3714 <dynamic> 3715 <clone entry="android.flash.firingPower" kind="controls"> 3716 </clone> 3717 <clone entry="android.flash.firingTime" kind="controls"> 3718 </clone> 3719 <clone entry="android.flash.mode" kind="controls"></clone> 3720 <entry name="state" type="byte" visibility="public" enum="true" 3721 hwlevel="limited"> 3722 <enum> 3723 <value>UNAVAILABLE 3724 <notes>No flash on camera.</notes></value> 3725 <value>CHARGING 3726 <notes>Flash is charging and cannot be fired.</notes></value> 3727 <value>READY 3728 <notes>Flash is ready to fire.</notes></value> 3729 <value>FIRED 3730 <notes>Flash fired for this capture.</notes></value> 3731 <value>PARTIAL 3732 <notes>Flash partially illuminated this frame. 3733 3734 This is usually due to the next or previous frame having 3735 the flash fire, and the flash spilling into this capture 3736 due to hardware limitations.</notes></value> 3737 </enum> 3738 <description>Current state of the flash 3739 unit.</description> 3740 <details> 3741 When the camera device doesn't have flash unit 3742 (i.e. `android.flash.info.available == false`), this state will always be UNAVAILABLE. 3743 Other states indicate the current flash status. 3744 3745 In certain conditions, this will be available on LEGACY devices: 3746 3747 * Flash-less cameras always return UNAVAILABLE. 3748 * Using android.control.aeMode `==` ON_ALWAYS_FLASH 3749 will always return FIRED. 3750 * Using android.flash.mode `==` TORCH 3751 will always return FIRED. 3752 3753 In all other conditions the state will not be available on 3754 LEGACY devices (i.e. it will be `null`). 3755 </details> 3756 </entry> 3757 </dynamic> 3758 </section> 3759 <section name="hotPixel"> 3760 <controls> 3761 <entry name="mode" type="byte" visibility="public" enum="true"> 3762 <enum> 3763 <value>OFF 3764 <notes> 3765 No hot pixel correction is applied. 3766 3767 The frame rate must not be reduced relative to sensor raw output 3768 for this option. 3769 3770 The hotpixel map may be returned in android.statistics.hotPixelMap. 3771 </notes> 3772 </value> 3773 <value>FAST 3774 <notes> 3775 Hot pixel correction is applied, without reducing frame 3776 rate relative to sensor raw output. 3777 3778 The hotpixel map may be returned in android.statistics.hotPixelMap. 3779 </notes> 3780 </value> 3781 <value>HIGH_QUALITY 3782 <notes> 3783 High-quality hot pixel correction is applied, at a cost 3784 of possibly reduced frame rate relative to sensor raw output. 3785 3786 The hotpixel map may be returned in android.statistics.hotPixelMap. 3787 </notes> 3788 </value> 3789 </enum> 3790 <description> 3791 Operational mode for hot pixel correction. 3792 </description> 3793 <range>android.hotPixel.availableHotPixelModes</range> 3794 <details> 3795 Hotpixel correction interpolates out, or otherwise removes, pixels 3796 that do not accurately measure the incoming light (i.e. pixels that 3797 are stuck at an arbitrary value or are oversensitive). 3798 </details> 3799 <tag id="V1" /> 3800 <tag id="RAW" /> 3801 </entry> 3802 </controls> 3803 <static> 3804 <entry name="availableHotPixelModes" type="byte" visibility="public" 3805 type_notes="list of enums" container="array" typedef="enumList"> 3806 <array> 3807 <size>n</size> 3808 </array> 3809 <description> 3810 List of hot pixel correction modes for android.hotPixel.mode that are supported by this 3811 camera device. 3812 </description> 3813 <range>Any value listed in android.hotPixel.mode</range> 3814 <details> 3815 FULL mode camera devices will always support FAST. 3816 </details> 3817 <hal_details> 3818 To avoid performance issues, there will be significantly fewer hot 3819 pixels than actual pixels on the camera sensor. 3820 HAL must support both FAST and HIGH_QUALITY if hot pixel correction control is available 3821 on the camera device, but the underlying implementation can be the same for both modes. 3822 That is, if the highest quality implementation on the camera device does not slow down 3823 capture rate, then FAST and HIGH_QUALITY will generate the same output. 3824 </hal_details> 3825 <tag id="V1" /> 3826 <tag id="RAW" /> 3827 </entry> 3828 </static> 3829 <dynamic> 3830 <clone entry="android.hotPixel.mode" kind="controls"> 3831 <tag id="V1" /> 3832 <tag id="RAW" /> 3833 </clone> 3834 </dynamic> 3835 </section> 3836 <section name="jpeg"> 3837 <controls> 3838 <entry name="gpsLocation" type="byte" visibility="java_public" synthetic="true" 3839 typedef="location" hwlevel="legacy"> 3840 <description> 3841 A location object to use when generating image GPS metadata. 3842 </description> 3843 <details> 3844 Setting a location object in a request will include the GPS coordinates of the location 3845 into any JPEG images captured based on the request. These coordinates can then be 3846 viewed by anyone who receives the JPEG image. 3847 3848 This tag is also used for HEIC image capture. 3849 </details> 3850 </entry> 3851 <entry name="gpsCoordinates" type="double" visibility="ndk_public" 3852 type_notes="latitude, longitude, altitude. First two in degrees, the third in meters" 3853 container="array" hwlevel="legacy"> 3854 <array> 3855 <size>3</size> 3856 </array> 3857 <description>GPS coordinates to include in output JPEG 3858 EXIF.</description> 3859 <range>(-180 - 180], [-90,90], [-inf, inf]</range> 3860 <details>This tag is also used for HEIC image capture.</details> 3861 <tag id="BC" /> 3862 </entry> 3863 <entry name="gpsProcessingMethod" type="byte" visibility="ndk_public" 3864 typedef="string" hwlevel="legacy"> 3865 <description>32 characters describing GPS algorithm to 3866 include in EXIF.</description> 3867 <units>UTF-8 null-terminated string</units> 3868 <details>This tag is also used for HEIC image capture.</details> 3869 <tag id="BC" /> 3870 </entry> 3871 <entry name="gpsTimestamp" type="int64" visibility="ndk_public" hwlevel="legacy"> 3872 <description>Time GPS fix was made to include in 3873 EXIF.</description> 3874 <units>UTC in seconds since January 1, 1970</units> 3875 <details>This tag is also used for HEIC image capture.</details> 3876 <tag id="BC" /> 3877 </entry> 3878 <entry name="orientation" type="int32" visibility="public" hwlevel="legacy"> 3879 <description>The orientation for a JPEG image.</description> 3880 <units>Degrees in multiples of 90</units> 3881 <range>0, 90, 180, 270</range> 3882 <details> 3883 The clockwise rotation angle in degrees, relative to the orientation 3884 to the camera, that the JPEG picture needs to be rotated by, to be viewed 3885 upright. 3886 3887 Camera devices may either encode this value into the JPEG EXIF header, or 3888 rotate the image data to match this orientation. When the image data is rotated, 3889 the thumbnail data will also be rotated. 3890 3891 Note that this orientation is relative to the orientation of the camera sensor, given 3892 by android.sensor.orientation. 3893 3894 To translate from the device orientation given by the Android sensor APIs for camera 3895 sensors which are not EXTERNAL, the following sample code may be used: 3896 3897 private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) { 3898 if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0; 3899 int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION); 3900 3901 // Round device orientation to a multiple of 90 3902 deviceOrientation = (deviceOrientation + 45) / 90 * 90; 3903 3904 // Reverse device orientation for front-facing cameras 3905 boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT; 3906 if (facingFront) deviceOrientation = -deviceOrientation; 3907 3908 // Calculate desired JPEG orientation relative to camera orientation to make 3909 // the image upright relative to the device orientation 3910 int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360; 3911 3912 return jpegOrientation; 3913 } 3914 3915 For EXTERNAL cameras the sensor orientation will always be set to 0 and the facing will 3916 also be set to EXTERNAL. The above code is not relevant in such case. 3917 3918 This tag is also used to describe the orientation of the HEIC image capture, in which 3919 case the rotation is reflected by 3920 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}, and not by 3921 rotating the image data itself. 3922 </details> 3923 <tag id="BC" /> 3924 </entry> 3925 <entry name="quality" type="byte" visibility="public" hwlevel="legacy"> 3926 <description>Compression quality of the final JPEG 3927 image.</description> 3928 <range>1-100; larger is higher quality</range> 3929 <details>85-95 is typical usage range. This tag is also used to describe the quality 3930 of the HEIC image capture.</details> 3931 <tag id="BC" /> 3932 </entry> 3933 <entry name="thumbnailQuality" type="byte" visibility="public" hwlevel="legacy"> 3934 <description>Compression quality of JPEG 3935 thumbnail.</description> 3936 <range>1-100; larger is higher quality</range> 3937 <details>This tag is also used to describe the quality of the HEIC image capture.</details> 3938 <tag id="BC" /> 3939 </entry> 3940 <entry name="thumbnailSize" type="int32" visibility="public" 3941 container="array" typedef="size" hwlevel="legacy"> 3942 <array> 3943 <size>2</size> 3944 </array> 3945 <description>Resolution of embedded JPEG thumbnail.</description> 3946 <range>android.jpeg.availableThumbnailSizes</range> 3947 <details>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, 3948 but the captured JPEG will still be a valid image. 3949 3950 For best results, when issuing a request for a JPEG image, the thumbnail size selected 3951 should have the same aspect ratio as the main JPEG output. 3952 3953 If the thumbnail image aspect ratio differs from the JPEG primary image aspect 3954 ratio, the camera device creates the thumbnail by cropping it from the primary image. 3955 For example, if the primary image has 4:3 aspect ratio, the thumbnail image has 3956 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to 3957 generate the thumbnail image. The thumbnail image will always have a smaller Field 3958 Of View (FOV) than the primary image when aspect ratios differ. 3959 3960 When an android.jpeg.orientation of non-zero degree is requested, 3961 the camera device will handle thumbnail rotation in one of the following ways: 3962 3963 * Set the {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag} 3964 and keep jpeg and thumbnail image data unrotated. 3965 * Rotate the jpeg and thumbnail image data and not set 3966 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}. In this 3967 case, LIMITED or FULL hardware level devices will report rotated thumnail size in 3968 capture result, so the width and height will be interchanged if 90 or 270 degree 3969 orientation is requested. LEGACY device will always report unrotated thumbnail 3970 size. 3971 3972 The tag is also used as thumbnail size for HEIC image format capture, in which case the 3973 the thumbnail rotation is reflected by 3974 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}, and not by 3975 rotating the thumbnail data itself. 3976 </details> 3977 <hal_details> 3978 The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail. 3979 The cropping must be done on the primary jpeg image rather than the sensor pre-correction 3980 active array. The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't 3981 apply to the thumbnail image cropping. 3982 </hal_details> 3983 <tag id="BC" /> 3984 </entry> 3985 </controls> 3986 <static> 3987 <entry name="availableThumbnailSizes" type="int32" visibility="public" 3988 container="array" typedef="size" hwlevel="legacy"> 3989 <array> 3990 <size>2</size> 3991 <size>n</size> 3992 </array> 3993 <description>List of JPEG thumbnail sizes for android.jpeg.thumbnailSize supported by this 3994 camera device.</description> 3995 <details> 3996 This list will include at least one non-zero resolution, plus `(0,0)` for indicating no 3997 thumbnail should be generated. 3998 3999 Below condiditions will be satisfied for this size list: 4000 4001 * The sizes will be sorted by increasing pixel area (width x height). 4002 If several resolutions have the same area, they will be sorted by increasing width. 4003 * The aspect ratio of the largest thumbnail size will be same as the 4004 aspect ratio of largest JPEG output size in android.scaler.availableStreamConfigurations. 4005 The largest size is defined as the size that has the largest pixel area 4006 in a given size list. 4007 * Each output JPEG size in android.scaler.availableStreamConfigurations will have at least 4008 one corresponding size that has the same aspect ratio in availableThumbnailSizes, 4009 and vice versa. 4010 * All non-`(0, 0)` sizes will have non-zero widths and heights. 4011 4012 This list is also used as supported thumbnail sizes for HEIC image format capture. 4013 </details> 4014 <tag id="BC" /> 4015 </entry> 4016 <entry name="maxSize" type="int32" visibility="system"> 4017 <description>Maximum size in bytes for the compressed 4018 JPEG buffer, in default sensor pixel mode (see android.sensor.pixelMode)</description> 4019 <range>Must be large enough to fit any JPEG produced by 4020 the camera</range> 4021 <details>This is used for sizing the gralloc buffers for 4022 JPEG</details> 4023 </entry> 4024 </static> 4025 <dynamic> 4026 <clone entry="android.jpeg.gpsLocation" kind="controls"> 4027 </clone> 4028 <clone entry="android.jpeg.gpsCoordinates" kind="controls"> 4029 </clone> 4030 <clone entry="android.jpeg.gpsProcessingMethod" 4031 kind="controls"></clone> 4032 <clone entry="android.jpeg.gpsTimestamp" kind="controls"> 4033 </clone> 4034 <clone entry="android.jpeg.orientation" kind="controls"> 4035 </clone> 4036 <clone entry="android.jpeg.quality" kind="controls"> 4037 </clone> 4038 <entry name="size" type="int32"> 4039 <description>The size of the compressed JPEG image, in 4040 bytes</description> 4041 <range>&gt;= 0</range> 4042 <details>If no JPEG output is produced for the request, 4043 this must be 0. 4044 4045 Otherwise, this describes the real size of the compressed 4046 JPEG image placed in the output stream. More specifically, 4047 if android.jpeg.maxSize = 1000000, and a specific capture 4048 has android.jpeg.size = 500000, then the output buffer from 4049 the JPEG stream will be 1000000 bytes, of which the first 4050 500000 make up the real data.</details> 4051 <tag id="FUTURE" /> 4052 </entry> 4053 <clone entry="android.jpeg.thumbnailQuality" 4054 kind="controls"></clone> 4055 <clone entry="android.jpeg.thumbnailSize" kind="controls"> 4056 </clone> 4057 </dynamic> 4058 </section> 4059 <section name="lens"> 4060 <controls> 4061 <entry name="aperture" type="float" visibility="public" hwlevel="full"> 4062 <description>The desired lens aperture size, as a ratio of lens focal length to the 4063 effective aperture diameter.</description> 4064 <units>The f-number (f/N)</units> 4065 <range>android.lens.info.availableApertures</range> 4066 <details>Setting this value is only supported on the camera devices that have a variable 4067 aperture lens. 4068 4069 When this is supported and android.control.aeMode is OFF, 4070 this can be set along with android.sensor.exposureTime, 4071 android.sensor.sensitivity, and android.sensor.frameDuration 4072 to achieve manual exposure control. 4073 4074 The requested aperture value may take several frames to reach the 4075 requested value; the camera device will report the current (intermediate) 4076 aperture size in capture result metadata while the aperture is changing. 4077 While the aperture is still changing, android.lens.state will be set to MOVING. 4078 4079 When this is supported and android.control.aeMode is one of 4080 the ON modes, this will be overridden by the camera device 4081 auto-exposure algorithm, the overridden values are then provided 4082 back to the user in the corresponding result.</details> 4083 <tag id="V1" /> 4084 </entry> 4085 <entry name="filterDensity" type="float" visibility="public" hwlevel="full"> 4086 <description> 4087 The desired setting for the lens neutral density filter(s). 4088 </description> 4089 <units>Exposure Value (EV)</units> 4090 <range>android.lens.info.availableFilterDensities</range> 4091 <details> 4092 This control will not be supported on most camera devices. 4093 4094 Lens filters are typically used to lower the amount of light the 4095 sensor is exposed to (measured in steps of EV). As used here, an EV 4096 step is the standard logarithmic representation, which are 4097 non-negative, and inversely proportional to the amount of light 4098 hitting the sensor. For example, setting this to 0 would result 4099 in no reduction of the incoming light, and setting this to 2 would 4100 mean that the filter is set to reduce incoming light by two stops 4101 (allowing 1/4 of the prior amount of light to the sensor). 4102 4103 It may take several frames before the lens filter density changes 4104 to the requested value. While the filter density is still changing, 4105 android.lens.state will be set to MOVING. 4106 </details> 4107 <tag id="V1" /> 4108 </entry> 4109 <entry name="focalLength" type="float" visibility="public" hwlevel="legacy"> 4110 <description> 4111 The desired lens focal length; used for optical zoom. 4112 </description> 4113 <units>Millimeters</units> 4114 <range>android.lens.info.availableFocalLengths</range> 4115 <details> 4116 This setting controls the physical focal length of the camera 4117 device's lens. Changing the focal length changes the field of 4118 view of the camera device, and is usually used for optical zoom. 4119 4120 Like android.lens.focusDistance and android.lens.aperture, this 4121 setting won't be applied instantaneously, and it may take several 4122 frames before the lens can change to the requested focal length. 4123 While the focal length is still changing, android.lens.state will 4124 be set to MOVING. 4125 4126 Optical zoom via this control will not be supported on most devices. Starting from API 4127 level 30, the camera device may combine optical and digital zoom through the 4128 android.control.zoomRatio control. 4129 </details> 4130 <hal_details> 4131 For a logical camera device supporting both optical and digital zoom, if focalLength and 4132 cropRegion change in the same request, the camera device must make sure that the new 4133 focalLength and cropRegion take effect in the same frame. This is to make sure that there 4134 is no visible field-of-view jump during zoom. For example, if cropRegion is applied 4135 immediately, but focalLength takes more than 1 frame to take effect, the camera device 4136 will delay the cropRegion so that it's synchronized with focalLength. 4137 4138 Starting from API level 30, it's strongly recommended for HAL to implement the 4139 combination of optical and digital zoom using the new android.control.zoomRatio API, in 4140 lieu of using android.lens.focalLength and android.scaler.cropRegion. 4141 </hal_details> 4142 <tag id="V1" /> 4143 </entry> 4144 <entry name="focusDistance" type="float" visibility="public" hwlevel="full"> 4145 <description>Desired distance to plane of sharpest focus, 4146 measured from frontmost surface of the lens.</description> 4147 <units>See android.lens.info.focusDistanceCalibration for details</units> 4148 <range>&gt;= 0</range> 4149 <details> 4150 This control can be used for setting manual focus, on devices that support 4151 the MANUAL_SENSOR capability and have a variable-focus lens (see 4152 android.lens.info.minimumFocusDistance). 4153 4154 A value of `0.0f` means infinity focus. The value set will be clamped to 4155 `[0.0f, android.lens.info.minimumFocusDistance]`. 4156 4157 Like android.lens.focalLength, this setting won't be applied 4158 instantaneously, and it may take several frames before the lens 4159 can move to the requested focus distance. While the lens is still moving, 4160 android.lens.state will be set to MOVING. 4161 4162 LEGACY devices support at most setting this to `0.0f` 4163 for infinity focus. 4164 </details> 4165 <tag id="BC" /> 4166 <tag id="V1" /> 4167 </entry> 4168 <entry name="opticalStabilizationMode" type="byte" visibility="public" 4169 enum="true" hwlevel="limited"> 4170 <enum> 4171 <value>OFF 4172 <notes>Optical stabilization is unavailable.</notes> 4173 </value> 4174 <value optional="true">ON 4175 <notes>Optical stabilization is enabled.</notes> 4176 </value> 4177 </enum> 4178 <description> 4179 Sets whether the camera device uses optical image stabilization (OIS) 4180 when capturing images. 4181 </description> 4182 <range>android.lens.info.availableOpticalStabilization</range> 4183 <details> 4184 OIS is used to compensate for motion blur due to small 4185 movements of the camera during capture. Unlike digital image 4186 stabilization (android.control.videoStabilizationMode), OIS 4187 makes use of mechanical elements to stabilize the camera 4188 sensor, and thus allows for longer exposure times before 4189 camera shake becomes apparent. 4190 4191 Switching between different optical stabilization modes may take several 4192 frames to initialize, the camera device will report the current mode in 4193 capture result metadata. For example, When "ON" mode is requested, the 4194 optical stabilization modes in the first several capture results may still 4195 be "OFF", and it will become "ON" when the initialization is done. 4196 4197 If a camera device supports both OIS and digital image stabilization 4198 (android.control.videoStabilizationMode), turning both modes on may produce undesirable 4199 interaction, so it is recommended not to enable both at the same time. 4200 4201 Not all devices will support OIS; see 4202 android.lens.info.availableOpticalStabilization for 4203 available controls. 4204 </details> 4205 <tag id="V1" /> 4206 </entry> 4207 </controls> 4208 <static> 4209 <namespace name="info"> 4210 <entry name="availableApertures" type="float" visibility="public" 4211 container="array" hwlevel="full"> 4212 <array> 4213 <size>n</size> 4214 </array> 4215 <description>List of aperture size values for android.lens.aperture that are 4216 supported by this camera device.</description> 4217 <units>The aperture f-number</units> 4218 <details>If the camera device doesn't support a variable lens aperture, 4219 this list will contain only one value, which is the fixed aperture size. 4220 4221 If the camera device supports a variable aperture, the aperture values 4222 in this list will be sorted in ascending order.</details> 4223 <tag id="V1" /> 4224 </entry> 4225 <entry name="availableFilterDensities" type="float" visibility="public" 4226 container="array" hwlevel="full"> 4227 <array> 4228 <size>n</size> 4229 </array> 4230 <description> 4231 List of neutral density filter values for 4232 android.lens.filterDensity that are supported by this camera device. 4233 </description> 4234 <units>Exposure value (EV)</units> 4235 <range> 4236 Values are &gt;= 0 4237 </range> 4238 <details> 4239 If a neutral density filter is not supported by this camera device, 4240 this list will contain only 0. Otherwise, this list will include every 4241 filter density supported by the camera device, in ascending order. 4242 </details> 4243 <tag id="V1" /> 4244 </entry> 4245 <entry name="availableFocalLengths" type="float" visibility="public" 4246 type_notes="The list of available focal lengths" 4247 container="array" hwlevel="legacy"> 4248 <array> 4249 <size>n</size> 4250 </array> 4251 <description> 4252 List of focal lengths for android.lens.focalLength that are supported by this camera 4253 device. 4254 </description> 4255 <units>Millimeters</units> 4256 <range> 4257 Values are &gt; 0 4258 </range> 4259 <details> 4260 If optical zoom is not supported, this list will only contain 4261 a single value corresponding to the fixed focal length of the 4262 device. Otherwise, this list will include every focal length supported 4263 by the camera device, in ascending order. 4264 </details> 4265 <tag id="BC" /> 4266 <tag id="V1" /> 4267 </entry> 4268 <entry name="availableOpticalStabilization" type="byte" 4269 visibility="public" type_notes="list of enums" container="array" 4270 typedef="enumList" hwlevel="limited"> 4271 <array> 4272 <size>n</size> 4273 </array> 4274 <description> 4275 List of optical image stabilization (OIS) modes for 4276 android.lens.opticalStabilizationMode that are supported by this camera device. 4277 </description> 4278 <range>Any value listed in android.lens.opticalStabilizationMode</range> 4279 <details> 4280 If OIS is not supported by a given camera device, this list will 4281 contain only OFF. 4282 </details> 4283 <tag id="V1" /> 4284 </entry> 4285 <entry name="hyperfocalDistance" type="float" visibility="public" optional="true" 4286 hwlevel="limited" permission_needed="true"> 4287 <description>Hyperfocal distance for this lens.</description> 4288 <units>See android.lens.info.focusDistanceCalibration for details</units> 4289 <range>If lens is fixed focus, &gt;= 0. If lens has focuser unit, the value is 4290 within `(0.0f, android.lens.info.minimumFocusDistance]`</range> 4291 <details> 4292 If the lens is not fixed focus, the camera device will report this 4293 field when android.lens.info.focusDistanceCalibration is APPROXIMATE or CALIBRATED. 4294 </details> 4295 </entry> 4296 <entry name="minimumFocusDistance" type="float" visibility="public" optional="true" 4297 hwlevel="limited" permission_needed="true"> 4298 <description>Shortest distance from frontmost surface 4299 of the lens that can be brought into sharp focus.</description> 4300 <units>See android.lens.info.focusDistanceCalibration for details</units> 4301 <range>&gt;= 0</range> 4302 <details>If the lens is fixed-focus, this will be 4303 0.</details> 4304 <hal_details>Mandatory for FULL devices; LIMITED devices 4305 must always set this value to 0 for fixed-focus; and may omit 4306 the minimum focus distance otherwise. 4307 4308 This field is also mandatory for all devices advertising 4309 the MANUAL_SENSOR capability.</hal_details> 4310 <tag id="V1" /> 4311 </entry> 4312 <entry name="shadingMapSize" type="int32" visibility="ndk_public" 4313 type_notes="width and height (N, M) of lens shading map provided by the camera device." 4314 container="array" typedef="size" hwlevel="full"> 4315 <array> 4316 <size>2</size> 4317 </array> 4318 <description>Dimensions of lens shading map.</description> 4319 <range>Both values &gt;= 1</range> 4320 <details> 4321 The map should be on the order of 30-40 rows and columns, and 4322 must be smaller than 64x64. 4323 </details> 4324 <tag id="V1" /> 4325 </entry> 4326 <entry name="focusDistanceCalibration" type="byte" visibility="public" 4327 enum="true" hwlevel="limited"> 4328 <enum> 4329 <value>UNCALIBRATED 4330 <notes> 4331 The lens focus distance is not accurate, and the units used for 4332 android.lens.focusDistance do not correspond to any physical units. 4333 4334 Setting the lens to the same focus distance on separate occasions may 4335 result in a different real focus distance, depending on factors such 4336 as the orientation of the device, the age of the focusing mechanism, 4337 and the device temperature. The focus distance value will still be 4338 in the range of `[0, android.lens.info.minimumFocusDistance]`, where 0 4339 represents the farthest focus. 4340 </notes> 4341 </value> 4342 <value>APPROXIMATE 4343 <notes> 4344 The lens focus distance is measured in diopters. 4345 4346 However, setting the lens to the same focus distance 4347 on separate occasions may result in a different real 4348 focus distance, depending on factors such as the 4349 orientation of the device, the age of the focusing 4350 mechanism, and the device temperature. 4351 </notes> 4352 </value> 4353 <value>CALIBRATED 4354 <notes> 4355 The lens focus distance is measured in diopters, and 4356 is calibrated. 4357 4358 The lens mechanism is calibrated so that setting the 4359 same focus distance is repeatable on multiple 4360 occasions with good accuracy, and the focus distance 4361 corresponds to the real physical distance to the plane 4362 of best focus. 4363 </notes> 4364 </value> 4365 </enum> 4366 <description>The lens focus distance calibration quality.</description> 4367 <details> 4368 The lens focus distance calibration quality determines the reliability of 4369 focus related metadata entries, i.e. android.lens.focusDistance, 4370 android.lens.focusRange, android.lens.info.hyperfocalDistance, and 4371 android.lens.info.minimumFocusDistance. 4372 4373 APPROXIMATE and CALIBRATED devices report the focus metadata in 4374 units of diopters (1/meter), so `0.0f` represents focusing at infinity, 4375 and increasing positive numbers represent focusing closer and closer 4376 to the camera device. The focus distance control also uses diopters 4377 on these devices. 4378 4379 UNCALIBRATED devices do not use units that are directly comparable 4380 to any real physical measurement, but `0.0f` still represents farthest 4381 focus, and android.lens.info.minimumFocusDistance represents the 4382 nearest focus the device can achieve. 4383 </details> 4384 <hal_details> 4385 For devices advertise APPROXIMATE quality or higher, diopters 0 (infinity 4386 focus) must work. When autofocus is disabled (android.control.afMode == OFF) 4387 and the lens focus distance is set to 0 diopters 4388 (android.lens.focusDistance == 0), the lens will move to focus at infinity 4389 and is stably focused at infinity even if the device tilts. It may take the 4390 lens some time to move; during the move the lens state should be MOVING and 4391 the output diopter value should be changing toward 0. 4392 </hal_details> 4393 <tag id="V1" /> 4394 </entry> 4395 </namespace> 4396 <entry name="facing" type="byte" visibility="public" enum="true" hwlevel="legacy"> 4397 <enum> 4398 <value>FRONT 4399 <notes> 4400 The camera device faces the same direction as the device's screen. 4401 </notes></value> 4402 <value>BACK 4403 <notes> 4404 The camera device faces the opposite direction as the device's screen. 4405 </notes></value> 4406 <value>EXTERNAL 4407 <notes> 4408 The camera device is an external camera, and has no fixed facing relative to the 4409 device's screen. 4410 </notes></value> 4411 </enum> 4412 <description>Direction the camera faces relative to 4413 device screen.</description> 4414 </entry> 4415 <entry name="poseRotation" type="float" visibility="public" 4416 container="array" permission_needed="true"> 4417 <array> 4418 <size>4</size> 4419 </array> 4420 <description> 4421 The orientation of the camera relative to the sensor 4422 coordinate system. 4423 </description> 4424 <units> 4425 Quaternion coefficients 4426 </units> 4427 <details> 4428 The four coefficients that describe the quaternion 4429 rotation from the Android sensor coordinate system to a 4430 camera-aligned coordinate system where the X-axis is 4431 aligned with the long side of the image sensor, the Y-axis 4432 is aligned with the short side of the image sensor, and 4433 the Z-axis is aligned with the optical axis of the sensor. 4434 4435 To convert from the quaternion coefficients `(x,y,z,w)` 4436 to the axis of rotation `(a_x, a_y, a_z)` and rotation 4437 amount `theta`, the following formulas can be used: 4438 4439 theta = 2 * acos(w) 4440 a_x = x / sin(theta/2) 4441 a_y = y / sin(theta/2) 4442 a_z = z / sin(theta/2) 4443 4444 To create a 3x3 rotation matrix that applies the rotation 4445 defined by this quaternion, the following matrix can be 4446 used: 4447 4448 R = [ 1 - 2y^2 - 2z^2, 2xy - 2zw, 2xz + 2yw, 4449 2xy + 2zw, 1 - 2x^2 - 2z^2, 2yz - 2xw, 4450 2xz - 2yw, 2yz + 2xw, 1 - 2x^2 - 2y^2 ] 4451 4452 This matrix can then be used to apply the rotation to a 4453 column vector point with 4454 4455 `p' = Rp` 4456 4457 where `p` is in the device sensor coordinate system, and 4458 `p'` is in the camera-oriented coordinate system. 4459 4460 If android.lens.poseReference is UNDEFINED, the quaternion rotation cannot 4461 be accurately represented by the camera device, and will be represented by 4462 default values matching its default facing. 4463 </details> 4464 <tag id="DEPTH" /> 4465 </entry> 4466 <entry name="poseTranslation" type="float" visibility="public" 4467 container="array" permission_needed="true"> 4468 <array> 4469 <size>3</size> 4470 </array> 4471 <description>Position of the camera optical center.</description> 4472 <units>Meters</units> 4473 <details> 4474 The position of the camera device's lens optical center, 4475 as a three-dimensional vector `(x,y,z)`. 4476 4477 Prior to Android P, or when android.lens.poseReference is PRIMARY_CAMERA, this position 4478 is relative to the optical center of the largest camera device facing in the same 4479 direction as this camera, in the {@link android.hardware.SensorEvent Android sensor 4480 coordinate axes}. Note that only the axis definitions are shared with the sensor 4481 coordinate system, but not the origin. 4482 4483 If this device is the largest or only camera device with a given facing, then this 4484 position will be `(0, 0, 0)`; a camera device with a lens optical center located 3 cm 4485 from the main sensor along the +X axis (to the right from the user's perspective) will 4486 report `(0.03, 0, 0)`. Note that this means that, for many computer vision 4487 applications, the position needs to be negated to convert it to a translation from the 4488 camera to the origin. 4489 4490 To transform a pixel coordinates between two cameras facing the same direction, first 4491 the source camera android.lens.distortion must be corrected for. Then the source 4492 camera android.lens.intrinsicCalibration needs to be applied, followed by the 4493 android.lens.poseRotation of the source camera, the translation of the source camera 4494 relative to the destination camera, the android.lens.poseRotation of the destination 4495 camera, and finally the inverse of android.lens.intrinsicCalibration of the destination 4496 camera. This obtains a radial-distortion-free coordinate in the destination camera pixel 4497 coordinates. 4498 4499 To compare this against a real image from the destination camera, the destination camera 4500 image then needs to be corrected for radial distortion before comparison or sampling. 4501 4502 When android.lens.poseReference is GYROSCOPE, then this position is relative to 4503 the center of the primary gyroscope on the device. The axis definitions are the same as 4504 with PRIMARY_CAMERA. 4505 4506 When android.lens.poseReference is UNDEFINED, this position cannot be accurately 4507 represented by the camera device, and will be represented as `(0, 0, 0)`. 4508 </details> 4509 <tag id="DEPTH" /> 4510 </entry> 4511 </static> 4512 <dynamic> 4513 <clone entry="android.lens.aperture" kind="controls"> 4514 <tag id="V1" /> 4515 </clone> 4516 <clone entry="android.lens.filterDensity" kind="controls"> 4517 <tag id="V1" /> 4518 </clone> 4519 <clone entry="android.lens.focalLength" kind="controls"> 4520 <tag id="BC" /> 4521 </clone> 4522 <clone entry="android.lens.focusDistance" kind="controls"> 4523 <details>Should be zero for fixed-focus cameras</details> 4524 <tag id="BC" /> 4525 </clone> 4526 <entry name="focusRange" type="float" visibility="public" 4527 type_notes="Range of scene distances that are in focus" 4528 container="array" typedef="pairFloatFloat" hwlevel="limited"> 4529 <array> 4530 <size>2</size> 4531 </array> 4532 <description>The range of scene distances that are in 4533 sharp focus (depth of field).</description> 4534 <units>A pair of focus distances in diopters: (near, 4535 far); see android.lens.info.focusDistanceCalibration for details.</units> 4536 <range>&gt;=0</range> 4537 <details>If variable focus not supported, can still report 4538 fixed depth of field range</details> 4539 <tag id="BC" /> 4540 </entry> 4541 <clone entry="android.lens.opticalStabilizationMode" 4542 kind="controls"> 4543 <tag id="V1" /> 4544 </clone> 4545 <entry name="state" type="byte" visibility="public" enum="true" hwlevel="limited"> 4546 <enum> 4547 <value>STATIONARY 4548 <notes> 4549 The lens parameters (android.lens.focalLength, android.lens.focusDistance, 4550 android.lens.filterDensity and android.lens.aperture) are not changing. 4551 </notes> 4552 </value> 4553 <value>MOVING 4554 <notes> 4555 One or several of the lens parameters 4556 (android.lens.focalLength, android.lens.focusDistance, 4557 android.lens.filterDensity or android.lens.aperture) is 4558 currently changing. 4559 </notes> 4560 </value> 4561 </enum> 4562 <description>Current lens status.</description> 4563 <details> 4564 For lens parameters android.lens.focalLength, android.lens.focusDistance, 4565 android.lens.filterDensity and android.lens.aperture, when changes are requested, 4566 they may take several frames to reach the requested values. This state indicates 4567 the current status of the lens parameters. 4568 4569 When the state is STATIONARY, the lens parameters are not changing. This could be 4570 either because the parameters are all fixed, or because the lens has had enough 4571 time to reach the most recently-requested values. 4572 If all these lens parameters are not changable for a camera device, as listed below: 4573 4574 * Fixed focus (`android.lens.info.minimumFocusDistance == 0`), which means 4575 android.lens.focusDistance parameter will always be 0. 4576 * Fixed focal length (android.lens.info.availableFocalLengths contains single value), 4577 which means the optical zoom is not supported. 4578 * No ND filter (android.lens.info.availableFilterDensities contains only 0). 4579 * Fixed aperture (android.lens.info.availableApertures contains single value). 4580 4581 Then this state will always be STATIONARY. 4582 4583 When the state is MOVING, it indicates that at least one of the lens parameters 4584 is changing. 4585 </details> 4586 <tag id="V1" /> 4587 </entry> 4588 <clone entry="android.lens.poseRotation" kind="static"> 4589 </clone> 4590 <clone entry="android.lens.poseTranslation" kind="static"> 4591 </clone> 4592 </dynamic> 4593 <static> 4594 <entry name="intrinsicCalibration" type="float" visibility="public" 4595 container="array" permission_needed="true"> 4596 <array> 4597 <size>5</size> 4598 </array> 4599 <description> 4600 The parameters for this camera device's intrinsic 4601 calibration. 4602 </description> 4603 <units> 4604 Pixels in the 4605 android.sensor.info.preCorrectionActiveArraySize 4606 coordinate system. 4607 </units> 4608 <details> 4609 The five calibration parameters that describe the 4610 transform from camera-centric 3D coordinates to sensor 4611 pixel coordinates: 4612 4613 [f_x, f_y, c_x, c_y, s] 4614 4615 Where `f_x` and `f_y` are the horizontal and vertical 4616 focal lengths, `[c_x, c_y]` is the position of the optical 4617 axis, and `s` is a skew parameter for the sensor plane not 4618 being aligned with the lens plane. 4619 4620 These are typically used within a transformation matrix K: 4621 4622 K = [ f_x, s, c_x, 4623 0, f_y, c_y, 4624 0 0, 1 ] 4625 4626 which can then be combined with the camera pose rotation 4627 `R` and translation `t` (android.lens.poseRotation and 4628 android.lens.poseTranslation, respectively) to calculate the 4629 complete transform from world coordinates to pixel 4630 coordinates: 4631 4632 P = [ K 0 * [ R -Rt 4633 0 1 ] 0 1 ] 4634 4635 (Note the negation of poseTranslation when mapping from camera 4636 to world coordinates, and multiplication by the rotation). 4637 4638 With `p_w` being a point in the world coordinate system 4639 and `p_s` being a point in the camera active pixel array 4640 coordinate system, and with the mapping including the 4641 homogeneous division by z: 4642 4643 p_h = (x_h, y_h, z_h) = P p_w 4644 p_s = p_h / z_h 4645 4646 so `[x_s, y_s]` is the pixel coordinates of the world 4647 point, `z_s = 1`, and `w_s` is a measurement of disparity 4648 (depth) in pixel coordinates. 4649 4650 Note that the coordinate system for this transform is the 4651 android.sensor.info.preCorrectionActiveArraySize system, 4652 where `(0,0)` is the top-left of the 4653 preCorrectionActiveArraySize rectangle. Once the pose and 4654 intrinsic calibration transforms have been applied to a 4655 world point, then the android.lens.distortion 4656 transform needs to be applied, and the result adjusted to 4657 be in the android.sensor.info.activeArraySize coordinate 4658 system (where `(0, 0)` is the top-left of the 4659 activeArraySize rectangle), to determine the final pixel 4660 coordinate of the world point for processed (non-RAW) 4661 output buffers. 4662 4663 For camera devices, the center of pixel `(x,y)` is located at 4664 coordinate `(x + 0.5, y + 0.5)`. So on a device with a 4665 precorrection active array of size `(10,10)`, the valid pixel 4666 indices go from `(0,0)-(9,9)`, and an perfectly-built camera would 4667 have an optical center at the exact center of the pixel grid, at 4668 coordinates `(5.0, 5.0)`, which is the top-left corner of pixel 4669 `(5,5)`. 4670 </details> 4671 <tag id="DEPTH" /> 4672 </entry> 4673 <entry name="radialDistortion" type="float" visibility="public" 4674 deprecated="true" container="array" permission_needed="true"> 4675 <array> 4676 <size>6</size> 4677 </array> 4678 <description> 4679 The correction coefficients to correct for this camera device's 4680 radial and tangential lens distortion. 4681 </description> 4682 <deprecation_description> 4683 This field was inconsistently defined in terms of its 4684 normalization. Use android.lens.distortion instead. 4685 </deprecation_description> 4686 <units> 4687 Unitless coefficients. 4688 </units> 4689 <details> 4690 Four radial distortion coefficients `[kappa_0, kappa_1, kappa_2, 4691 kappa_3]` and two tangential distortion coefficients 4692 `[kappa_4, kappa_5]` that can be used to correct the 4693 lens's geometric distortion with the mapping equations: 4694 4695 x_c = x_i * ( kappa_0 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 4696 kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 ) 4697 y_c = y_i * ( kappa_0 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 4698 kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 ) 4699 4700 Here, `[x_c, y_c]` are the coordinates to sample in the 4701 input image that correspond to the pixel values in the 4702 corrected image at the coordinate `[x_i, y_i]`: 4703 4704 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage) 4705 4706 The pixel coordinates are defined in a normalized 4707 coordinate system related to the 4708 android.lens.intrinsicCalibration calibration fields. 4709 Both `[x_i, y_i]` and `[x_c, y_c]` have `(0,0)` at the 4710 lens optical center `[c_x, c_y]`. The maximum magnitudes 4711 of both x and y coordinates are normalized to be 1 at the 4712 edge further from the optical center, so the range 4713 for both dimensions is `-1 <= x <= 1`. 4714 4715 Finally, `r` represents the radial distance from the 4716 optical center, `r^2 = x_i^2 + y_i^2`, and its magnitude 4717 is therefore no larger than `|r| <= sqrt(2)`. 4718 4719 The distortion model used is the Brown-Conrady model. 4720 </details> 4721 <tag id="DEPTH" /> 4722 </entry> 4723 </static> 4724 <dynamic> 4725 <clone entry="android.lens.intrinsicCalibration" kind="static"> 4726 </clone> 4727 <clone entry="android.lens.radialDistortion" kind="static"> 4728 </clone> 4729 </dynamic> 4730 <static> 4731 <entry name="poseReference" type="byte" visibility="public" enum="true" 4732 permission_needed="true" hal_version="3.3" > 4733 <enum> 4734 <value>PRIMARY_CAMERA 4735 <notes>The value of android.lens.poseTranslation is relative to the optical center of 4736 the largest camera device facing the same direction as this camera. 4737 4738 This is the default value for API levels before Android P. 4739 </notes> 4740 </value> 4741 <value>GYROSCOPE 4742 <notes>The value of android.lens.poseTranslation is relative to the position of the 4743 primary gyroscope of this Android device. 4744 </notes> 4745 </value> 4746 <value hal_version="3.5">UNDEFINED 4747 <notes>The camera device cannot represent the values of android.lens.poseTranslation 4748 and android.lens.poseRotation accurately enough. One such example is a camera device 4749 on the cover of a foldable phone: in order to measure the pose translation and rotation, 4750 some kind of hinge position sensor would be needed. 4751 4752 The value of android.lens.poseTranslation must be all zeros, and 4753 android.lens.poseRotation must be values matching its default facing. 4754 </notes> 4755 </value> 4756 </enum> 4757 <description> 4758 The origin for android.lens.poseTranslation, and the accuracy of 4759 android.lens.poseTranslation and android.lens.poseRotation. 4760 </description> 4761 <details> 4762 Different calibration methods and use cases can produce better or worse results 4763 depending on the selected coordinate origin. 4764 </details> 4765 </entry> 4766 <entry name="distortion" type="float" visibility="public" container="array" 4767 permission_needed="true" hal_version="3.3" > 4768 <array> 4769 <size>5</size> 4770 </array> 4771 <description> 4772 The correction coefficients to correct for this camera device's 4773 radial and tangential lens distortion. 4774 4775 Replaces the deprecated android.lens.radialDistortion field, which was 4776 inconsistently defined. 4777 </description> 4778 <units> 4779 Unitless coefficients. 4780 </units> 4781 <details> 4782 Three radial distortion coefficients `[kappa_1, kappa_2, 4783 kappa_3]` and two tangential distortion coefficients 4784 `[kappa_4, kappa_5]` that can be used to correct the 4785 lens's geometric distortion with the mapping equations: 4786 4787 x_c = x_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 4788 kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 ) 4789 y_c = y_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 4790 kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 ) 4791 4792 Here, `[x_c, y_c]` are the coordinates to sample in the 4793 input image that correspond to the pixel values in the 4794 corrected image at the coordinate `[x_i, y_i]`: 4795 4796 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage) 4797 4798 The pixel coordinates are defined in a coordinate system 4799 related to the android.lens.intrinsicCalibration 4800 calibration fields; see that entry for details of the mapping stages. 4801 Both `[x_i, y_i]` and `[x_c, y_c]` 4802 have `(0,0)` at the lens optical center `[c_x, c_y]`, and 4803 the range of the coordinates depends on the focal length 4804 terms of the intrinsic calibration. 4805 4806 Finally, `r` represents the radial distance from the 4807 optical center, `r^2 = x_i^2 + y_i^2`. 4808 4809 The distortion model used is the Brown-Conrady model. 4810 </details> 4811 <tag id="DEPTH" /> 4812 </entry> 4813 <entry name="distortionMaximumResolution" type="float" visibility="public" container="array" 4814 permission_needed="true" hal_version="3.6" > 4815 <array> 4816 <size>5</size> 4817 </array> 4818 <description> 4819 The correction coefficients to correct for this camera device's 4820 radial and tangential lens distortion for a 4821 CaptureRequest with android.sensor.pixelMode set to 4822 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 4823 </description> 4824 <units> 4825 Unitless coefficients. 4826 </units> 4827 <details> 4828 Analogous to android.lens.distortion, when android.sensor.pixelMode is set to 4829 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 4830 </details> 4831 <tag id="DEPTH" /> 4832 </entry> 4833 <entry name="intrinsicCalibrationMaximumResolution" type="float" visibility="public" 4834 container="array" permission_needed="true" hal_version="3.6"> 4835 <array> 4836 <size>5</size> 4837 </array> 4838 <description> 4839 The parameters for this camera device's intrinsic 4840 calibration when android.sensor.pixelMode is set to 4841 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 4842 </description> 4843 <units> 4844 Pixels in the 4845 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution 4846 coordinate system. 4847 </units> 4848 <details> 4849 Analogous to android.lens.intrinsicCalibration, when android.sensor.pixelMode is set to 4850 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 4851 </details> 4852 <tag id="DEPTH" /> 4853 </entry> 4854 </static> 4855 <dynamic> 4856 <clone entry="android.lens.distortion" kind="static"> 4857 </clone> 4858 </dynamic> 4859 </section> 4860 <section name="noiseReduction"> 4861 <controls> 4862 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 4863 <enum> 4864 <value>OFF 4865 <notes>No noise reduction is applied.</notes></value> 4866 <value>FAST 4867 <notes>Noise reduction is applied without reducing frame rate relative to sensor 4868 output. It may be the same as OFF if noise reduction will reduce frame rate 4869 relative to sensor.</notes></value> 4870 <value>HIGH_QUALITY 4871 <notes>High-quality noise reduction is applied, at the cost of possibly reduced frame 4872 rate relative to sensor output.</notes></value> 4873 <value optional="true">MINIMAL 4874 <notes>MINIMAL noise reduction is applied without reducing frame rate relative to 4875 sensor output. </notes></value> 4876 <value optional="true">ZERO_SHUTTER_LAG 4877 4878 <notes>Noise reduction is applied at different levels for different output streams, 4879 based on resolution. Streams at maximum recording resolution (see {@link 4880 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession}) 4881 or below have noise reduction applied, while higher-resolution streams have MINIMAL (if 4882 supported) or no noise reduction applied (if MINIMAL is not supported.) The degree of 4883 noise reduction for low-resolution streams is tuned so that frame rate is not impacted, 4884 and the quality is equal to or better than FAST (since it is only applied to 4885 lower-resolution outputs, quality may improve from FAST). 4886 4887 This mode is intended to be used by applications operating in a zero-shutter-lag mode 4888 with YUV or PRIVATE reprocessing, where the application continuously captures 4889 high-resolution intermediate buffers into a circular buffer, from which a final image is 4890 produced via reprocessing when a user takes a picture. For such a use case, the 4891 high-resolution buffers must not have noise reduction applied to maximize efficiency of 4892 preview and to avoid over-applying noise filtering when reprocessing, while 4893 low-resolution buffers (used for recording or preview, generally) need noise reduction 4894 applied for reasonable preview quality. 4895 4896 This mode is guaranteed to be supported by devices that support either the 4897 YUV_REPROCESSING or PRIVATE_REPROCESSING capabilities 4898 (android.request.availableCapabilities lists either of those capabilities) and it will 4899 be the default mode for CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 4900 </notes></value> 4901 </enum> 4902 <description>Mode of operation for the noise reduction algorithm.</description> 4903 <range>android.noiseReduction.availableNoiseReductionModes</range> 4904 <details>The noise reduction algorithm attempts to improve image quality by removing 4905 excessive noise added by the capture process, especially in dark conditions. 4906 4907 OFF means no noise reduction will be applied by the camera device, for both raw and 4908 YUV domain. 4909 4910 MINIMAL means that only sensor raw domain basic noise reduction is enabled ,to remove 4911 demosaicing or other processing artifacts. For YUV_REPROCESSING, MINIMAL is same as OFF. 4912 This mode is optional, may not be support by all devices. The application should check 4913 android.noiseReduction.availableNoiseReductionModes before using it. 4914 4915 FAST/HIGH_QUALITY both mean camera device determined noise filtering 4916 will be applied. HIGH_QUALITY mode indicates that the camera device 4917 will use the highest-quality noise filtering algorithms, 4918 even if it slows down capture rate. FAST means the camera device will not 4919 slow down capture rate when applying noise filtering. FAST may be the same as MINIMAL if 4920 MINIMAL is listed, or the same as OFF if any noise filtering will slow down capture rate. 4921 Every output stream will have a similar amount of enhancement applied. 4922 4923 ZERO_SHUTTER_LAG is meant to be used by applications that maintain a continuous circular 4924 buffer of high-resolution images during preview and reprocess image(s) from that buffer 4925 into a final capture when triggered by the user. In this mode, the camera device applies 4926 noise reduction to low-resolution streams (below maximum recording resolution) to maximize 4927 preview quality, but does not apply noise reduction to high-resolution streams, since 4928 those will be reprocessed later if necessary. 4929 4930 For YUV_REPROCESSING, these FAST/HIGH_QUALITY modes both mean that the camera device 4931 will apply FAST/HIGH_QUALITY YUV domain noise reduction, respectively. The camera device 4932 may adjust the noise reduction parameters for best image quality based on the 4933 android.reprocess.effectiveExposureFactor if it is set. 4934 </details> 4935 <hal_details> 4936 For YUV_REPROCESSING The HAL can use android.reprocess.effectiveExposureFactor to 4937 adjust the internal noise reduction parameters appropriately to get the best quality 4938 images. 4939 </hal_details> 4940 <tag id="V1" /> 4941 <tag id="REPROC" /> 4942 </entry> 4943 <entry name="strength" type="byte"> 4944 <description>Control the amount of noise reduction 4945 applied to the images</description> 4946 <units>1-10; 10 is max noise reduction</units> 4947 <range>1 - 10</range> 4948 <tag id="FUTURE" /> 4949 </entry> 4950 </controls> 4951 <static> 4952 <entry name="availableNoiseReductionModes" type="byte" visibility="public" 4953 type_notes="list of enums" container="array" typedef="enumList" hwlevel="limited"> 4954 <array> 4955 <size>n</size> 4956 </array> 4957 <description> 4958 List of noise reduction modes for android.noiseReduction.mode that are supported 4959 by this camera device. 4960 </description> 4961 <range>Any value listed in android.noiseReduction.mode</range> 4962 <details> 4963 Full-capability camera devices will always support OFF and FAST. 4964 4965 Camera devices that support YUV_REPROCESSING or PRIVATE_REPROCESSING will support 4966 ZERO_SHUTTER_LAG. 4967 4968 Legacy-capability camera devices will only support FAST mode. 4969 </details> 4970 <hal_details> 4971 HAL must support both FAST and HIGH_QUALITY if noise reduction control is available 4972 on the camera device, but the underlying implementation can be the same for both modes. 4973 That is, if the highest quality implementation on the camera device does not slow down 4974 capture rate, then FAST and HIGH_QUALITY will generate the same output. 4975 </hal_details> 4976 <tag id="V1" /> 4977 <tag id="REPROC" /> 4978 </entry> 4979 </static> 4980 <dynamic> 4981 <clone entry="android.noiseReduction.mode" kind="controls"> 4982 <tag id="V1" /> 4983 <tag id="REPROC" /> 4984 </clone> 4985 </dynamic> 4986 </section> 4987 <section name="quirks"> 4988 <static> 4989 <entry name="meteringCropRegion" type="byte" visibility="system" deprecated="true" optional="true"> 4990 <description>If set to 1, the camera service does not 4991 scale 'normalized' coordinates with respect to the crop 4992 region. This applies to metering input (a{e,f,wb}Region 4993 and output (face rectangles).</description> 4994 <deprecation_description> 4995 Not used in HALv3 or newer 4996 </deprecation_description> 4997 <details>Normalized coordinates refer to those in the 4998 (-1000,1000) range mentioned in the 4999 android.hardware.Camera API. 5000 5001 HAL implementations should instead always use and emit 5002 sensor array-relative coordinates for all region data. Does 5003 not need to be listed in static metadata. Support will be 5004 removed in future versions of camera service.</details> 5005 </entry> 5006 <entry name="triggerAfWithAuto" type="byte" visibility="system" deprecated="true" optional="true"> 5007 <description>If set to 1, then the camera service always 5008 switches to FOCUS_MODE_AUTO before issuing a AF 5009 trigger.</description> 5010 <deprecation_description> 5011 Not used in HALv3 or newer 5012 </deprecation_description> 5013 <details>HAL implementations should implement AF trigger 5014 modes for AUTO, MACRO, CONTINUOUS_FOCUS, and 5015 CONTINUOUS_PICTURE modes instead of using this flag. Does 5016 not need to be listed in static metadata. Support will be 5017 removed in future versions of camera service</details> 5018 </entry> 5019 <entry name="useZslFormat" type="byte" visibility="system" deprecated="true" optional="true"> 5020 <description>If set to 1, the camera service uses 5021 CAMERA2_PIXEL_FORMAT_ZSL instead of 5022 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED for the zero 5023 shutter lag stream</description> 5024 <deprecation_description> 5025 Not used in HALv3 or newer 5026 </deprecation_description> 5027 <details>HAL implementations should use gralloc usage flags 5028 to determine that a stream will be used for 5029 zero-shutter-lag, instead of relying on an explicit 5030 format setting. Does not need to be listed in static 5031 metadata. Support will be removed in future versions of 5032 camera service.</details> 5033 </entry> 5034 <entry name="usePartialResult" type="byte" visibility="hidden" deprecated="true" optional="true"> 5035 <description> 5036 If set to 1, the HAL will always split result 5037 metadata for a single capture into multiple buffers, 5038 returned using multiple process_capture_result calls. 5039 </description> 5040 <deprecation_description> 5041 Not used in HALv3 or newer; replaced by better partials mechanism 5042 </deprecation_description> 5043 <details> 5044 Does not need to be listed in static 5045 metadata. Support for partial results will be reworked in 5046 future versions of camera service. This quirk will stop 5047 working at that point; DO NOT USE without careful 5048 consideration of future support. 5049 </details> 5050 <hal_details> 5051 Refer to `camera3_capture_result::partial_result` 5052 for information on how to implement partial results. 5053 </hal_details> 5054 </entry> 5055 </static> 5056 <dynamic> 5057 <entry name="partialResult" type="byte" visibility="hidden" deprecated="true" optional="true" enum="true" typedef="boolean"> 5058 <enum> 5059 <value>FINAL 5060 <notes>The last or only metadata result buffer 5061 for this capture.</notes> 5062 </value> 5063 <value>PARTIAL 5064 <notes>A partial buffer of result metadata for this 5065 capture. More result buffers for this capture will be sent 5066 by the camera device, the last of which will be marked 5067 FINAL.</notes> 5068 </value> 5069 </enum> 5070 <description> 5071 Whether a result given to the framework is the 5072 final one for the capture, or only a partial that contains a 5073 subset of the full set of dynamic metadata 5074 values.</description> 5075 <deprecation_description> 5076 Not used in HALv3 or newer 5077 </deprecation_description> 5078 <range>Optional. Default value is FINAL.</range> 5079 <details> 5080 The entries in the result metadata buffers for a 5081 single capture may not overlap, except for this entry. The 5082 FINAL buffers must retain FIFO ordering relative to the 5083 requests that generate them, so the FINAL buffer for frame 3 must 5084 always be sent to the framework after the FINAL buffer for frame 2, and 5085 before the FINAL buffer for frame 4. PARTIAL buffers may be returned 5086 in any order relative to other frames, but all PARTIAL buffers for a given 5087 capture must arrive before the FINAL buffer for that capture. This entry may 5088 only be used by the camera device if quirks.usePartialResult is set to 1. 5089 </details> 5090 <hal_details> 5091 Refer to `camera3_capture_result::partial_result` 5092 for information on how to implement partial results. 5093 </hal_details> 5094 </entry> 5095 </dynamic> 5096 </section> 5097 <section name="request"> 5098 <controls> 5099 <entry name="frameCount" type="int32" visibility="system" deprecated="true"> 5100 <description>A frame counter set by the framework. Must 5101 be maintained unchanged in output frame. This value monotonically 5102 increases with every new result (that is, each new result has a unique 5103 frameCount value). 5104 </description> 5105 <deprecation_description> 5106 Not used in HALv3 or newer 5107 </deprecation_description> 5108 <units>incrementing integer</units> 5109 <range>Any int.</range> 5110 </entry> 5111 <entry name="id" type="int32" visibility="hidden"> 5112 <description>An application-specified ID for the current 5113 request. Must be maintained unchanged in output 5114 frame</description> 5115 <units>arbitrary integer assigned by application</units> 5116 <range>Any int</range> 5117 <tag id="V1" /> 5118 </entry> 5119 <entry name="inputStreams" type="int32" visibility="system" deprecated="true" 5120 container="array"> 5121 <array> 5122 <size>n</size> 5123 </array> 5124 <description>List which camera reprocess stream is used 5125 for the source of reprocessing data.</description> 5126 <deprecation_description> 5127 Not used in HALv3 or newer 5128 </deprecation_description> 5129 <units>List of camera reprocess stream IDs</units> 5130 <range> 5131 Typically, only one entry allowed, must be a valid reprocess stream ID. 5132 </range> 5133 <details>Only meaningful when android.request.type == 5134 REPROCESS. Ignored otherwise</details> 5135 <tag id="HAL2" /> 5136 </entry> 5137 <entry name="metadataMode" type="byte" visibility="system" 5138 enum="true"> 5139 <enum> 5140 <value>NONE 5141 <notes>No metadata should be produced on output, except 5142 for application-bound buffer data. If no 5143 application-bound streams exist, no frame should be 5144 placed in the output frame queue. If such streams 5145 exist, a frame should be placed on the output queue 5146 with null metadata but with the necessary output buffer 5147 information. Timestamp information should still be 5148 included with any output stream buffers</notes></value> 5149 <value>FULL 5150 <notes>All metadata should be produced. Statistics will 5151 only be produced if they are separately 5152 enabled</notes></value> 5153 </enum> 5154 <description>How much metadata to produce on 5155 output</description> 5156 <tag id="FUTURE" /> 5157 </entry> 5158 <entry name="outputStreams" type="int32" visibility="system" deprecated="true" 5159 container="array"> 5160 <array> 5161 <size>n</size> 5162 </array> 5163 <description>Lists which camera output streams image data 5164 from this capture must be sent to</description> 5165 <deprecation_description> 5166 Not used in HALv3 or newer 5167 </deprecation_description> 5168 <units>List of camera stream IDs</units> 5169 <range>List must only include streams that have been 5170 created</range> 5171 <details>If no output streams are listed, then the image 5172 data should simply be discarded. The image data must 5173 still be captured for metadata and statistics production, 5174 and the lens and flash must operate as requested.</details> 5175 <tag id="HAL2" /> 5176 </entry> 5177 <entry name="type" type="byte" visibility="system" deprecated="true" enum="true"> 5178 <enum> 5179 <value>CAPTURE 5180 <notes>Capture a new image from the imaging hardware, 5181 and process it according to the 5182 settings</notes></value> 5183 <value>REPROCESS 5184 <notes>Process previously captured data; the 5185 android.request.inputStreams parameter determines the 5186 source reprocessing stream. TODO: Mark dynamic metadata 5187 needed for reprocessing with [RP]</notes></value> 5188 </enum> 5189 <description>The type of the request; either CAPTURE or 5190 REPROCESS. For legacy HAL3, this tag is redundant. 5191 </description> 5192 <deprecation_description> 5193 Not used in HALv3 or newer 5194 </deprecation_description> 5195 <tag id="HAL2" /> 5196 </entry> 5197 </controls> 5198 <static> 5199 <entry name="maxNumOutputStreams" type="int32" visibility="ndk_public" 5200 container="array" hwlevel="legacy"> 5201 <array> 5202 <size>3</size> 5203 </array> 5204 <description>The maximum numbers of different types of output streams 5205 that can be configured and used simultaneously by a camera device. 5206 </description> 5207 <range> 5208 For processed (and stalling) format streams, &gt;= 1. 5209 5210 For Raw format (either stalling or non-stalling) streams, &gt;= 0. 5211 5212 For processed (but not stalling) format streams, &gt;= 3 5213 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 5214 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 5215 </range> 5216 <details> 5217 This is a 3 element tuple that contains the max number of output simultaneous 5218 streams for raw sensor, processed (but not stalling), and processed (and stalling) 5219 formats respectively. For example, assuming that JPEG is typically a processed and 5220 stalling stream, if max raw sensor format output stream number is 1, max YUV streams 5221 number is 3, and max JPEG stream number is 2, then this tuple should be `(1, 3, 2)`. 5222 5223 This lists the upper bound of the number of output streams supported by 5224 the camera device. Using more streams simultaneously may require more hardware and 5225 CPU resources that will consume more power. The image format for an output stream can 5226 be any supported format provided by android.scaler.availableStreamConfigurations. 5227 The formats defined in android.scaler.availableStreamConfigurations can be catergorized 5228 into the 3 stream types as below: 5229 5230 * Processed (but stalling): any non-RAW format with a stallDurations &gt; 0. 5231 Typically {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG format}. 5232 * Raw formats: {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 5233 RAW_SENSOR}, {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10}, or 5234 {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12}. 5235 * Processed (but not-stalling): any non-RAW format without a stall duration. Typically 5236 {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888}, 5237 {@link android.graphics.ImageFormat#NV21 NV21}, {@link 5238 android.graphics.ImageFormat#YV12 YV12}, or {@link 5239 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} . 5240 </details> 5241 <tag id="BC" /> 5242 </entry> 5243 <entry name="maxNumOutputRaw" type="int32" visibility="java_public" synthetic="true" 5244 hwlevel="legacy"> 5245 <description>The maximum numbers of different types of output streams 5246 that can be configured and used simultaneously by a camera device 5247 for any `RAW` formats. 5248 </description> 5249 <range> 5250 &gt;= 0 5251 </range> 5252 <details> 5253 This value contains the max number of output simultaneous 5254 streams from the raw sensor. 5255 5256 This lists the upper bound of the number of output streams supported by 5257 the camera device. Using more streams simultaneously may require more hardware and 5258 CPU resources that will consume more power. The image format for this kind of an output stream can 5259 be any `RAW` and supported format provided by android.scaler.streamConfigurationMap. 5260 5261 In particular, a `RAW` format is typically one of: 5262 5263 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 RAW_SENSOR} 5264 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10} 5265 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12} 5266 5267 LEGACY mode devices (android.info.supportedHardwareLevel `==` LEGACY) 5268 never support raw streams. 5269 </details> 5270 </entry> 5271 <entry name="maxNumOutputProc" type="int32" visibility="java_public" synthetic="true" 5272 hwlevel="legacy"> 5273 <description>The maximum numbers of different types of output streams 5274 that can be configured and used simultaneously by a camera device 5275 for any processed (but not-stalling) formats. 5276 </description> 5277 <range> 5278 &gt;= 3 5279 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 5280 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 5281 </range> 5282 <details> 5283 This value contains the max number of output simultaneous 5284 streams for any processed (but not-stalling) formats. 5285 5286 This lists the upper bound of the number of output streams supported by 5287 the camera device. Using more streams simultaneously may require more hardware and 5288 CPU resources that will consume more power. The image format for this kind of an output stream can 5289 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 5290 5291 Processed (but not-stalling) is defined as any non-RAW format without a stall duration. 5292 Typically: 5293 5294 * {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888} 5295 * {@link android.graphics.ImageFormat#NV21 NV21} 5296 * {@link android.graphics.ImageFormat#YV12 YV12} 5297 * Implementation-defined formats, i.e. {@link 5298 android.hardware.camera2.params.StreamConfigurationMap#isOutputSupportedFor(Class)} 5299 * {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} 5300 5301 For full guarantees, query {@link 5302 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration} with a 5303 processed format -- it will return 0 for a non-stalling stream. 5304 5305 LEGACY devices will support at least 2 processing/non-stalling streams. 5306 </details> 5307 </entry> 5308 <entry name="maxNumOutputProcStalling" type="int32" visibility="java_public" synthetic="true" 5309 hwlevel="legacy"> 5310 <description>The maximum numbers of different types of output streams 5311 that can be configured and used simultaneously by a camera device 5312 for any processed (and stalling) formats. 5313 </description> 5314 <range> 5315 &gt;= 1 5316 </range> 5317 <details> 5318 This value contains the max number of output simultaneous 5319 streams for any processed (but not-stalling) formats. 5320 5321 This lists the upper bound of the number of output streams supported by 5322 the camera device. Using more streams simultaneously may require more hardware and 5323 CPU resources that will consume more power. The image format for this kind of an output stream can 5324 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 5325 5326 A processed and stalling format is defined as any non-RAW format with a stallDurations 5327 &gt; 0. Typically only the {@link 5328 android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG format} is a stalling format. 5329 5330 For full guarantees, query {@link 5331 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration} with a 5332 processed format -- it will return a non-0 value for a stalling stream. 5333 5334 LEGACY devices will support up to 1 processing/stalling stream. 5335 </details> 5336 </entry> 5337 <entry name="maxNumReprocessStreams" type="int32" visibility="system" 5338 deprecated="true" container="array"> 5339 <array> 5340 <size>1</size> 5341 </array> 5342 <description>How many reprocessing streams of any type 5343 can be allocated at the same time.</description> 5344 <deprecation_description> 5345 Not used in HALv3 or newer 5346 </deprecation_description> 5347 <range>&gt;= 0</range> 5348 <details> 5349 Only used by HAL2.x. 5350 5351 When set to 0, it means no reprocess stream is supported. 5352 </details> 5353 <tag id="HAL2" /> 5354 </entry> 5355 <entry name="maxNumInputStreams" type="int32" visibility="java_public" hwlevel="full"> 5356 <description> 5357 The maximum numbers of any type of input streams 5358 that can be configured and used simultaneously by a camera device. 5359 </description> 5360 <range> 5361 0 or 1. 5362 </range> 5363 <details>When set to 0, it means no input stream is supported. 5364 5365 The image format for a input stream can be any supported format returned by {@link 5366 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. When using an 5367 input stream, there must be at least one output stream configured to to receive the 5368 reprocessed images. 5369 5370 When an input stream and some output streams are used in a reprocessing request, 5371 only the input buffer will be used to produce these output stream buffers, and a 5372 new sensor image will not be captured. 5373 5374 For example, for Zero Shutter Lag (ZSL) still capture use case, the input 5375 stream image format will be PRIVATE, the associated output stream image format 5376 should be JPEG. 5377 </details> 5378 <hal_details> 5379 For the reprocessing flow and controls, see 5380 hardware/libhardware/include/hardware/camera3.h Section 10 for more details. 5381 </hal_details> 5382 <tag id="REPROC" /> 5383 </entry> 5384 </static> 5385 <dynamic> 5386 <entry name="frameCount" type="int32" visibility="hidden" deprecated="true"> 5387 <description>A frame counter set by the framework. This value monotonically 5388 increases with every new result (that is, each new result has a unique 5389 frameCount value).</description> 5390 <deprecation_description> 5391 Not used in HALv3 or newer 5392 </deprecation_description> 5393 <units>count of frames</units> 5394 <range>&gt; 0</range> 5395 <details>Reset on release()</details> 5396 </entry> 5397 <clone entry="android.request.id" kind="controls"></clone> 5398 <clone entry="android.request.metadataMode" 5399 kind="controls"></clone> 5400 <clone entry="android.request.outputStreams" 5401 kind="controls"></clone> 5402 <entry name="pipelineDepth" type="byte" visibility="public" hwlevel="legacy"> 5403 <description>Specifies the number of pipeline stages the frame went 5404 through from when it was exposed to when the final completed result 5405 was available to the framework.</description> 5406 <range>&lt;= android.request.pipelineMaxDepth</range> 5407 <details>Depending on what settings are used in the request, and 5408 what streams are configured, the data may undergo less processing, 5409 and some pipeline stages skipped. 5410 5411 See android.request.pipelineMaxDepth for more details. 5412 </details> 5413 <hal_details> 5414 This value must always represent the accurate count of how many 5415 pipeline stages were actually used. 5416 </hal_details> 5417 </entry> 5418 </dynamic> 5419 <static> 5420 <entry name="pipelineMaxDepth" type="byte" visibility="public" hwlevel="legacy"> 5421 <description>Specifies the number of maximum pipeline stages a frame 5422 has to go through from when it's exposed to when it's available 5423 to the framework.</description> 5424 <details>A typical minimum value for this is 2 (one stage to expose, 5425 one stage to readout) from the sensor. The ISP then usually adds 5426 its own stages to do custom HW processing. Further stages may be 5427 added by SW processing. 5428 5429 Depending on what settings are used (e.g. YUV, JPEG) and what 5430 processing is enabled (e.g. face detection), the actual pipeline 5431 depth (specified by android.request.pipelineDepth) may be less than 5432 the max pipeline depth. 5433 5434 A pipeline depth of X stages is equivalent to a pipeline latency of 5435 X frame intervals. 5436 5437 This value will normally be 8 or less, however, for high speed capture session, 5438 the max pipeline depth will be up to 8 x size of high speed capture request list. 5439 </details> 5440 <hal_details> 5441 This value should be 4 or less, expect for the high speed recording session, where the 5442 max batch sizes may be larger than 1. 5443 </hal_details> 5444 </entry> 5445 <entry name="partialResultCount" type="int32" visibility="public" optional="true"> 5446 <description>Defines how many sub-components 5447 a result will be composed of. 5448 </description> 5449 <range>&gt;= 1</range> 5450 <details>In order to combat the pipeline latency, partial results 5451 may be delivered to the application layer from the camera device as 5452 soon as they are available. 5453 5454 Optional; defaults to 1. A value of 1 means that partial 5455 results are not supported, and only the final TotalCaptureResult will 5456 be produced by the camera device. 5457 5458 A typical use case for this might be: after requesting an 5459 auto-focus (AF) lock the new AF state might be available 50% 5460 of the way through the pipeline. The camera device could 5461 then immediately dispatch this state via a partial result to 5462 the application, and the rest of the metadata via later 5463 partial results. 5464 </details> 5465 </entry> 5466 <entry name="availableCapabilities" type="byte" visibility="public" 5467 enum="true" container="array" hwlevel="legacy"> 5468 <array> 5469 <size>n</size> 5470 </array> 5471 <enum> 5472 <value>BACKWARD_COMPATIBLE 5473 <notes>The minimal set of capabilities that every camera 5474 device (regardless of android.info.supportedHardwareLevel) 5475 supports. 5476 5477 This capability is listed by all normal devices, and 5478 indicates that the camera device has a feature set 5479 that's comparable to the baseline requirements for the 5480 older android.hardware.Camera API. 5481 5482 Devices with the DEPTH_OUTPUT capability might not list this 5483 capability, indicating that they support only depth measurement, 5484 not standard color output. 5485 </notes> 5486 </value> 5487 <value optional="true">MANUAL_SENSOR 5488 <notes> 5489 The camera device can be manually controlled (3A algorithms such 5490 as auto-exposure, and auto-focus can be bypassed). 5491 The camera device supports basic manual control of the sensor image 5492 acquisition related stages. This means the following controls are 5493 guaranteed to be supported: 5494 5495 * Manual frame duration control 5496 * android.sensor.frameDuration 5497 * android.sensor.info.maxFrameDuration 5498 * Manual exposure control 5499 * android.sensor.exposureTime 5500 * android.sensor.info.exposureTimeRange 5501 * Manual sensitivity control 5502 * android.sensor.sensitivity 5503 * android.sensor.info.sensitivityRange 5504 * Manual lens control (if the lens is adjustable) 5505 * android.lens.* 5506 * Manual flash control (if a flash unit is present) 5507 * android.flash.* 5508 * Manual black level locking 5509 * android.blackLevel.lock 5510 * Auto exposure lock 5511 * android.control.aeLock 5512 5513 If any of the above 3A algorithms are enabled, then the camera 5514 device will accurately report the values applied by 3A in the 5515 result. 5516 5517 A given camera device may also support additional manual sensor controls, 5518 but this capability only covers the above list of controls. 5519 5520 If this is supported, android.scaler.streamConfigurationMap will 5521 additionally return a min frame duration that is greater than 5522 zero for each supported size-format combination. 5523 5524 For camera devices with LOGICAL_MULTI_CAMERA capability, when the underlying active 5525 physical camera switches, exposureTime, sensitivity, and lens properties may change 5526 even if AE/AF is locked. However, the overall auto exposure and auto focus experience 5527 for users will be consistent. Refer to LOGICAL_MULTI_CAMERA capability for details. 5528 </notes> 5529 </value> 5530 <value optional="true">MANUAL_POST_PROCESSING 5531 <notes> 5532 The camera device post-processing stages can be manually controlled. 5533 The camera device supports basic manual control of the image post-processing 5534 stages. This means the following controls are guaranteed to be supported: 5535 5536 * Manual tonemap control 5537 * android.tonemap.curve 5538 * android.tonemap.mode 5539 * android.tonemap.maxCurvePoints 5540 * android.tonemap.gamma 5541 * android.tonemap.presetCurve 5542 5543 * Manual white balance control 5544 * android.colorCorrection.transform 5545 * android.colorCorrection.gains 5546 * Manual lens shading map control 5547 * android.shading.mode 5548 * android.statistics.lensShadingMapMode 5549 * android.statistics.lensShadingMap 5550 * android.lens.info.shadingMapSize 5551 * Manual aberration correction control (if aberration correction is supported) 5552 * android.colorCorrection.aberrationMode 5553 * android.colorCorrection.availableAberrationModes 5554 * Auto white balance lock 5555 * android.control.awbLock 5556 5557 If auto white balance is enabled, then the camera device 5558 will accurately report the values applied by AWB in the result. 5559 5560 A given camera device may also support additional post-processing 5561 controls, but this capability only covers the above list of controls. 5562 5563 For camera devices with LOGICAL_MULTI_CAMERA capability, when underlying active 5564 physical camera switches, tonemap, white balance, and shading map may change even if 5565 awb is locked. However, the overall post-processing experience for users will be 5566 consistent. Refer to LOGICAL_MULTI_CAMERA capability for details. 5567 </notes> 5568 </value> 5569 <value optional="true">RAW 5570 <notes> 5571 The camera device supports outputting RAW buffers and 5572 metadata for interpreting them. 5573 5574 Devices supporting the RAW capability allow both for 5575 saving DNG files, and for direct application processing of 5576 raw sensor images. 5577 5578 * RAW_SENSOR is supported as an output format. 5579 * The maximum available resolution for RAW_SENSOR streams 5580 will match either the value in 5581 android.sensor.info.pixelArraySize or 5582 android.sensor.info.preCorrectionActiveArraySize. 5583 * All DNG-related optional metadata entries are provided 5584 by the camera device. 5585 </notes> 5586 </value> 5587 <value optional="true" visibility="java_public">PRIVATE_REPROCESSING 5588 <notes> 5589 The camera device supports the Zero Shutter Lag reprocessing use case. 5590 5591 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 5592 * {@link android.graphics.ImageFormat#PRIVATE} is supported as an output/input format, 5593 that is, {@link android.graphics.ImageFormat#PRIVATE} is included in the lists of 5594 formats returned by {@link 5595 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 5596 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 5597 * {@link android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 5598 returns non-empty int[] for each supported input format returned by {@link 5599 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 5600 * Each size returned by {@link 5601 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 5602 getInputSizes(ImageFormat.PRIVATE)} is also included in {@link 5603 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 5604 getOutputSizes(ImageFormat.PRIVATE)} 5605 * Using {@link android.graphics.ImageFormat#PRIVATE} does not cause a frame rate drop 5606 relative to the sensor's maximum capture rate (at that resolution). 5607 * {@link android.graphics.ImageFormat#PRIVATE} will be reprocessable into both 5608 {@link android.graphics.ImageFormat#YUV_420_888} and 5609 {@link android.graphics.ImageFormat#JPEG} formats. 5610 * For a MONOCHROME camera supporting Y8 format, {@link 5611 android.graphics.ImageFormat#PRIVATE} will be reprocessable into 5612 {@link android.graphics.ImageFormat#Y8}. 5613 * The maximum available resolution for PRIVATE streams 5614 (both input/output) will match the maximum available 5615 resolution of JPEG streams. 5616 * Static metadata android.reprocess.maxCaptureStall. 5617 * Only below controls are effective for reprocessing requests and 5618 will be present in capture results, other controls in reprocess 5619 requests will be ignored by the camera device. 5620 * android.jpeg.* 5621 * android.noiseReduction.mode 5622 * android.edge.mode 5623 * android.noiseReduction.availableNoiseReductionModes and 5624 android.edge.availableEdgeModes will both list ZERO_SHUTTER_LAG as a supported mode. 5625 </notes> 5626 </value> 5627 <value optional="true">READ_SENSOR_SETTINGS 5628 <notes> 5629 The camera device supports accurately reporting the sensor settings for many of 5630 the sensor controls while the built-in 3A algorithm is running. This allows 5631 reporting of sensor settings even when these settings cannot be manually changed. 5632 5633 The values reported for the following controls are guaranteed to be available 5634 in the CaptureResult, including when 3A is enabled: 5635 5636 * Exposure control 5637 * android.sensor.exposureTime 5638 * Sensitivity control 5639 * android.sensor.sensitivity 5640 * Lens controls (if the lens is adjustable) 5641 * android.lens.focusDistance 5642 * android.lens.aperture 5643 5644 This capability is a subset of the MANUAL_SENSOR control capability, and will 5645 always be included if the MANUAL_SENSOR capability is available. 5646 </notes> 5647 </value> 5648 <value optional="true">BURST_CAPTURE 5649 <notes> 5650 The camera device supports capturing high-resolution images at >= 20 frames per 5651 second, in at least the uncompressed YUV format, when post-processing settings are 5652 set to FAST. Additionally, all image resolutions less than 24 megapixels can be 5653 captured at >= 10 frames per second. Here, 'high resolution' means at least 8 5654 megapixels, or the maximum resolution of the device, whichever is smaller. 5655 </notes> 5656 <sdk_notes> 5657 More specifically, this means that a size matching the camera device's active array 5658 size is listed as a supported size for the {@link 5659 android.graphics.ImageFormat#YUV_420_888} format in either {@link 5660 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} or {@link 5661 android.hardware.camera2.params.StreamConfigurationMap#getHighResolutionOutputSizes}, 5662 with a minimum frame duration for that format and size of either <= 1/20 s, or 5663 <= 1/10 s if the image size is less than 24 megapixels, respectively; and 5664 the android.control.aeAvailableTargetFpsRanges entry lists at least one FPS range 5665 where the minimum FPS is >= 1 / minimumFrameDuration for the maximum-size 5666 YUV_420_888 format. If that maximum size is listed in {@link 5667 android.hardware.camera2.params.StreamConfigurationMap#getHighResolutionOutputSizes}, 5668 then the list of resolutions for YUV_420_888 from {@link 5669 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} contains at 5670 least one resolution >= 8 megapixels, with a minimum frame duration of <= 1/20 5671 s. 5672 5673 If the device supports the {@link 5674 android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10}, {@link 5675 android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12}, {@link 5676 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8}, then those can also be 5677 captured at the same rate as the maximum-size YUV_420_888 resolution is. 5678 5679 If the device supports the PRIVATE_REPROCESSING capability, then the same guarantees 5680 as for the YUV_420_888 format also apply to the {@link 5681 android.graphics.ImageFormat#PRIVATE} format. 5682 5683 In addition, the android.sync.maxLatency field is guaranted to have a value between 0 5684 and 4, inclusive. android.control.aeLockAvailable and android.control.awbLockAvailable 5685 are also guaranteed to be `true` so burst capture with these two locks ON yields 5686 consistent image output. 5687 </sdk_notes> 5688 <ndk_notes> 5689 More specifically, this means that at least one output {@link 5690 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} size listed in 5691 {@link 5692 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 5693 is larger or equal to the 'high resolution' defined above, and can be captured at at 5694 least 20 fps. For the largest {@link 5695 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} size listed in 5696 {@link 5697 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, 5698 camera device can capture this size for at least 10 frames per second if the size is 5699 less than 24 megapixels. Also the android.control.aeAvailableTargetFpsRanges entry 5700 lists at least one FPS range where the minimum FPS is >= 1 / minimumFrameDuration 5701 for the largest YUV_420_888 size. 5702 5703 If the device supports the {@link 5704 android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10}, {@link 5705 android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12}, {@link 5706 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8}, then those can also be 5707 captured at the same rate as the maximum-size YUV_420_888 resolution is. 5708 5709 In addition, the android.sync.maxLatency field is guaranted to have a value between 0 5710 and 4, inclusive. android.control.aeLockAvailable and android.control.awbLockAvailable 5711 are also guaranteed to be `true` so burst capture with these two locks ON yields 5712 consistent image output. 5713 </ndk_notes> 5714 </value> 5715 <value optional="true" visibility="java_public">YUV_REPROCESSING 5716 <notes> 5717 The camera device supports the YUV_420_888 reprocessing use case, similar as 5718 PRIVATE_REPROCESSING, This capability requires the camera device to support the 5719 following: 5720 5721 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 5722 * {@link android.graphics.ImageFormat#YUV_420_888} is supported as an output/input 5723 format, that is, YUV_420_888 is included in the lists of formats returned by {@link 5724 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 5725 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 5726 * {@link 5727 android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 5728 returns non-empty int[] for each supported input format returned by {@link 5729 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 5730 * Each size returned by {@link 5731 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 5732 getInputSizes(YUV_420_888)} is also included in {@link 5733 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 5734 getOutputSizes(YUV_420_888)} 5735 * Using {@link android.graphics.ImageFormat#YUV_420_888} does not cause a frame rate 5736 drop relative to the sensor's maximum capture rate (at that resolution). 5737 * {@link android.graphics.ImageFormat#YUV_420_888} will be reprocessable into both 5738 {@link android.graphics.ImageFormat#YUV_420_888} and {@link 5739 android.graphics.ImageFormat#JPEG} formats. 5740 * The maximum available resolution for {@link 5741 android.graphics.ImageFormat#YUV_420_888} streams (both input/output) will match the 5742 maximum available resolution of {@link android.graphics.ImageFormat#JPEG} streams. 5743 * For a MONOCHROME camera with Y8 format support, all the requirements mentioned 5744 above for YUV_420_888 apply for Y8 format as well. 5745 * Static metadata android.reprocess.maxCaptureStall. 5746 * Only the below controls are effective for reprocessing requests and will be present 5747 in capture results. The reprocess requests are from the original capture results 5748 that are associated with the intermediate {@link 5749 android.graphics.ImageFormat#YUV_420_888} output buffers. All other controls in the 5750 reprocess requests will be ignored by the camera device. 5751 * android.jpeg.* 5752 * android.noiseReduction.mode 5753 * android.edge.mode 5754 * android.reprocess.effectiveExposureFactor 5755 * android.noiseReduction.availableNoiseReductionModes and 5756 android.edge.availableEdgeModes will both list ZERO_SHUTTER_LAG as a supported mode. 5757 </notes> 5758 </value> 5759 <value optional="true">DEPTH_OUTPUT 5760 <notes> 5761 The camera device can produce depth measurements from its field of view. 5762 5763 This capability requires the camera device to support the following: 5764 5765 * {@link android.graphics.ImageFormat#DEPTH16|AIMAGE_FORMAT_DEPTH16} is supported as 5766 an output format. 5767 * {@link 5768 android.graphics.ImageFormat#DEPTH_POINT_CLOUD|AIMAGE_FORMAT_DEPTH_POINT_CLOUD} is 5769 optionally supported as an output format. 5770 * This camera device, and all camera devices with the same android.lens.facing, will 5771 list the following calibration metadata entries in both {@link 5772 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics} 5773 and {@link 5774 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result}: 5775 - android.lens.poseTranslation 5776 - android.lens.poseRotation 5777 - android.lens.intrinsicCalibration 5778 - android.lens.distortion 5779 * The android.depth.depthIsExclusive entry is listed by this device. 5780 * As of Android P, the android.lens.poseReference entry is listed by this device. 5781 * A LIMITED camera with only the DEPTH_OUTPUT capability does not have to support 5782 normal YUV_420_888, Y8, JPEG, and PRIV-format outputs. It only has to support the 5783 DEPTH16 format. 5784 5785 Generally, depth output operates at a slower frame rate than standard color capture, 5786 so the DEPTH16 and DEPTH_POINT_CLOUD formats will commonly have a stall duration that 5787 should be accounted for (see {@link 5788 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_DEPTH_AVAILABLE_DEPTH_STALL_DURATIONS}). 5789 On a device that supports both depth and color-based output, to enable smooth preview, 5790 using a repeating burst is recommended, where a depth-output target is only included 5791 once every N frames, where N is the ratio between preview output rate and depth output 5792 rate, including depth stall time. 5793 </notes> 5794 </value> 5795 <value optional="true" visibility="java_public">CONSTRAINED_HIGH_SPEED_VIDEO 5796 <notes> 5797 The device supports constrained high speed video recording (frame rate >=120fps) use 5798 case. The camera device will support high speed capture session created by {@link 5799 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}, which 5800 only accepts high speed request lists created by {@link 5801 android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}. 5802 5803 A camera device can still support high speed video streaming by advertising the high 5804 speed FPS ranges in android.control.aeAvailableTargetFpsRanges. For this case, all 5805 normal capture request per frame control and synchronization requirements will apply 5806 to the high speed fps ranges, the same as all other fps ranges. This capability 5807 describes the capability of a specialized operating mode with many limitations (see 5808 below), which is only targeted at high speed video recording. 5809 5810 The supported high speed video sizes and fps ranges are specified in {@link 5811 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRanges}. 5812 To get desired output frame rates, the application is only allowed to select video 5813 size and FPS range combinations provided by {@link 5814 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes}. The 5815 fps range can be controlled via android.control.aeTargetFpsRange. 5816 5817 In this capability, the camera device will override aeMode, awbMode, and afMode to 5818 ON, AUTO, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 5819 controls will be overridden to be FAST. Therefore, no manual control of capture 5820 and post-processing parameters is possible. All other controls operate the 5821 same as when android.control.mode == AUTO. This means that all other 5822 android.control.* fields continue to work, such as 5823 5824 * android.control.aeTargetFpsRange 5825 * android.control.aeExposureCompensation 5826 * android.control.aeLock 5827 * android.control.awbLock 5828 * android.control.effectMode 5829 * android.control.aeRegions 5830 * android.control.afRegions 5831 * android.control.awbRegions 5832 * android.control.afTrigger 5833 * android.control.aePrecaptureTrigger 5834 * android.control.zoomRatio 5835 5836 Outside of android.control.*, the following controls will work: 5837 5838 * android.flash.mode (TORCH mode only, automatic flash for still capture will not 5839 work since aeMode is ON) 5840 * android.lens.opticalStabilizationMode (if it is supported) 5841 * android.scaler.cropRegion 5842 * android.statistics.faceDetectMode (if it is supported) 5843 5844 For high speed recording use case, the actual maximum supported frame rate may 5845 be lower than what camera can output, depending on the destination Surfaces for 5846 the image data. For example, if the destination surface is from video encoder, 5847 the application need check if the video encoder is capable of supporting the 5848 high frame rate for a given video size, or it will end up with lower recording 5849 frame rate. If the destination surface is from preview window, the actual preview frame 5850 rate will be bounded by the screen refresh rate. 5851 5852 The camera device will only support up to 2 high speed simultaneous output surfaces 5853 (preview and recording surfaces) in this mode. Above controls will be effective only 5854 if all of below conditions are true: 5855 5856 * The application creates a camera capture session with no more than 2 surfaces via 5857 {@link 5858 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. The 5859 targeted surfaces must be preview surface (either from {@link 5860 android.view.SurfaceView} or {@link android.graphics.SurfaceTexture}) or recording 5861 surface(either from {@link android.media.MediaRecorder#getSurface} or {@link 5862 android.media.MediaCodec#createInputSurface}). 5863 * The stream sizes are selected from the sizes reported by 5864 {@link android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes}. 5865 * The FPS ranges are selected from {@link 5866 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRanges}. 5867 5868 When above conditions are NOT satistied, 5869 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession} 5870 will fail. 5871 5872 Switching to a FPS range that has different maximum FPS may trigger some camera device 5873 reconfigurations, which may introduce extra latency. It is recommended that 5874 the application avoids unnecessary maximum target FPS changes as much as possible 5875 during high speed streaming. 5876 </notes> 5877 </value> 5878 <value optional="true" hal_version="3.3" >MOTION_TRACKING 5879 <notes> 5880 The camera device supports the MOTION_TRACKING value for 5881 android.control.captureIntent, which limits maximum exposure time to 20 ms. 5882 5883 This limits the motion blur of capture images, resulting in better image tracking 5884 results for use cases such as image stabilization or augmented reality. 5885 </notes> 5886 </value> 5887 <value optional="true" hal_version="3.3">LOGICAL_MULTI_CAMERA 5888 <notes> 5889 The camera device is a logical camera backed by two or more physical cameras. 5890 5891 In API level 28, the physical cameras must also be exposed to the application via 5892 {@link android.hardware.camera2.CameraManager#getCameraIdList}. 5893 5894 Starting from API level 29: 5895 5896 * Some or all physical cameras may not be independently exposed to the application, 5897 in which case the physical camera IDs will not be available in 5898 {@link android.hardware.camera2.CameraManager#getCameraIdList}. But the 5899 application can still query the physical cameras' characteristics by calling 5900 {@link android.hardware.camera2.CameraManager#getCameraCharacteristics}. 5901 * If a physical camera is hidden from camera ID list, the mandatory stream 5902 combinations for that physical camera must be supported through the logical camera 5903 using physical streams. One exception is that in API level 30, a physical camera 5904 may become unavailable via 5905 {@link CameraManager.AvailabilityCallback#onPhysicalCameraUnavailable|ACameraManager_PhysicalCameraAvailabilityCallback} 5906 callback. 5907 5908 Combinations of logical and physical streams, or physical streams from different 5909 physical cameras are not guaranteed. However, if the camera device supports 5910 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported}, 5911 application must be able to query whether a stream combination involving physical 5912 streams is supported by calling 5913 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported}. 5914 5915 Camera application shouldn't assume that there are at most 1 rear camera and 1 front 5916 camera in the system. For an application that switches between front and back cameras, 5917 the recommendation is to switch between the first rear camera and the first front 5918 camera in the list of supported camera devices. 5919 5920 This capability requires the camera device to support the following: 5921 5922 * The IDs of underlying physical cameras are returned via 5923 {@link android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds}. 5924 * This camera device must list static metadata 5925 android.logicalMultiCamera.sensorSyncType in 5926 {@link android.hardware.camera2.CameraCharacteristics}. 5927 * The underlying physical cameras' static metadata must list the following entries, 5928 so that the application can correlate pixels from the physical streams: 5929 - android.lens.poseReference 5930 - android.lens.poseRotation 5931 - android.lens.poseTranslation 5932 - android.lens.intrinsicCalibration 5933 - android.lens.distortion 5934 * The SENSOR_INFO_TIMESTAMP_SOURCE of the logical device and physical devices must be 5935 the same. 5936 * The logical camera must be LIMITED or higher device. 5937 5938 A logical camera device's dynamic metadata may contain 5939 android.logicalMultiCamera.activePhysicalId to notify the application of the current 5940 active physical camera Id. An active physical camera is the physical camera from which 5941 the logical camera's main image data outputs (YUV or RAW) and metadata come from. 5942 In addition, this serves as an indication which physical camera is used to output to 5943 a RAW stream, or in case only physical cameras support RAW, which physical RAW stream 5944 the application should request. 5945 5946 Logical camera's static metadata tags below describe the default active physical 5947 camera. An active physical camera is default if it's used when application directly 5948 uses requests built from a template. All templates will default to the same active 5949 physical camera. 5950 5951 - android.sensor.info.sensitivityRange 5952 - android.sensor.info.colorFilterArrangement 5953 - android.sensor.info.exposureTimeRange 5954 - android.sensor.info.maxFrameDuration 5955 - android.sensor.info.physicalSize 5956 - android.sensor.info.whiteLevel 5957 - android.sensor.info.lensShadingApplied 5958 - android.sensor.referenceIlluminant1 5959 - android.sensor.referenceIlluminant2 5960 - android.sensor.calibrationTransform1 5961 - android.sensor.calibrationTransform2 5962 - android.sensor.colorTransform1 5963 - android.sensor.colorTransform2 5964 - android.sensor.forwardMatrix1 5965 - android.sensor.forwardMatrix2 5966 - android.sensor.blackLevelPattern 5967 - android.sensor.maxAnalogSensitivity 5968 - android.sensor.opticalBlackRegions 5969 - android.sensor.availableTestPatternModes 5970 - android.lens.info.hyperfocalDistance 5971 - android.lens.info.minimumFocusDistance 5972 - android.lens.info.focusDistanceCalibration 5973 - android.lens.poseRotation 5974 - android.lens.poseTranslation 5975 - android.lens.intrinsicCalibration 5976 - android.lens.poseReference 5977 - android.lens.distortion 5978 5979 The field of view of non-RAW physical streams must not be smaller than that of the 5980 non-RAW logical streams, or the maximum field-of-view of the physical camera, 5981 whichever is smaller. The application should check the physical capture result 5982 metadata for how the physical streams are cropped or zoomed. More specifically, given 5983 the physical camera result metadata, the effective horizontal field-of-view of the 5984 physical camera is: 5985 5986 fov = 2 * atan2(cropW * sensorW / (2 * zoomRatio * activeArrayW), focalLength) 5987 5988 where the equation parameters are the physical camera's crop region width, physical 5989 sensor width, zoom ratio, active array width, and focal length respectively. Typically 5990 the physical stream of active physical camera has the same field-of-view as the 5991 logical streams. However, the same may not be true for physical streams from 5992 non-active physical cameras. For example, if the logical camera has a wide-ultrawide 5993 configuration where the wide lens is the default, when the crop region is set to the 5994 logical camera's active array size, (and the zoom ratio set to 1.0 starting from 5995 Android 11), a physical stream for the ultrawide camera may prefer outputing images 5996 with larger field-of-view than that of the wide camera for better stereo matching 5997 margin or more robust motion tracking. At the same time, the physical non-RAW streams' 5998 field of view must not be smaller than the requested crop region and zoom ratio, as 5999 long as it's within the physical lens' capability. For example, for a logical camera 6000 with wide-tele lens configuration where the wide lens is the default, if the logical 6001 camera's crop region is set to maximum size, and zoom ratio set to 1.0, the physical 6002 stream for the tele lens will be configured to its maximum size crop region (no zoom). 6003 6004 *Deprecated:* Prior to Android 11, the field of view of all non-RAW physical streams 6005 cannot be larger than that of non-RAW logical streams. If the logical camera has a 6006 wide-ultrawide lens configuration where the wide lens is the default, when the logical 6007 camera's crop region is set to maximum size, the FOV of the physical streams for the 6008 ultrawide lens will be the same as the logical stream, by making the crop region 6009 smaller than its active array size to compensate for the smaller focal length. 6010 6011 There are two ways for the application to capture RAW images from a logical camera 6012 with RAW capability: 6013 6014 * Because the underlying physical cameras may have different RAW capabilities (such 6015 as resolution or CFA pattern), to maintain backward compatibility, when a RAW stream 6016 is configured, the camera device makes sure the default active physical camera remains 6017 active and does not switch to other physical cameras. (One exception is that, if the 6018 logical camera consists of identical image sensors and advertises multiple focalLength 6019 due to different lenses, the camera device may generate RAW images from different 6020 physical cameras based on the focalLength being set by the application.) This 6021 backward-compatible approach usually results in loss of optical zoom, to telephoto 6022 lens or to ultrawide lens. 6023 * Alternatively, to take advantage of the full zoomRatio range of the logical camera, 6024 the application should use {@link android.hardware.camera2.MultiResolutionImageReader} 6025 to capture RAW images from the currently active physical camera. Because different 6026 physical camera may have different RAW characteristics, the application needs to use 6027 the characteristics and result metadata of the active physical camera for the 6028 relevant RAW metadata. 6029 6030 The capture request and result metadata tags required for backward compatible camera 6031 functionalities will be solely based on the logical camera capability. On the other 6032 hand, the use of manual capture controls (sensor or post-processing) with a 6033 logical camera may result in unexpected behavior when the HAL decides to switch 6034 between physical cameras with different characteristics under the hood. For example, 6035 when the application manually sets exposure time and sensitivity while zooming in, 6036 the brightness of the camera images may suddenly change because HAL switches from one 6037 physical camera to the other. 6038 </notes> 6039 </value> 6040 <value optional="true" hal_version="3.3" >MONOCHROME 6041 <notes> 6042 The camera device is a monochrome camera that doesn't contain a color filter array, 6043 and for YUV_420_888 stream, the pixel values on U and V planes are all 128. 6044 6045 A MONOCHROME camera must support the guaranteed stream combinations required for 6046 its device level and capabilities. Additionally, if the monochrome camera device 6047 supports Y8 format, all mandatory stream combination requirements related to {@link 6048 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888} apply 6049 to {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} as well. There are no 6050 mandatory stream combination requirements with regard to 6051 {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} for Bayer camera devices. 6052 6053 Starting from Android Q, the SENSOR_INFO_COLOR_FILTER_ARRANGEMENT of a MONOCHROME 6054 camera will be either MONO or NIR. 6055 </notes> 6056 </value> 6057 <value optional="true" hal_version="3.4" >SECURE_IMAGE_DATA 6058 <notes> 6059 The camera device is capable of writing image data into a region of memory 6060 inaccessible to Android userspace or the Android kernel, and only accessible to 6061 trusted execution environments (TEE). 6062 </notes> 6063 </value> 6064 <value optional="true" hal_version="3.5" >SYSTEM_CAMERA 6065 <notes> 6066 The camera device is only accessible by Android's system components and privileged 6067 applications. Processes need to have the android.permission.SYSTEM_CAMERA in 6068 addition to android.permission.CAMERA in order to connect to this camera device. 6069 </notes> 6070 </value> 6071 <value optional="true" visibility="java_public" hal_version="3.5">OFFLINE_PROCESSING 6072 <notes> 6073 The camera device supports the OFFLINE_PROCESSING use case. 6074 6075 With OFFLINE_PROCESSING capability, the application can switch an ongoing 6076 capture session to offline mode by calling the 6077 CameraCaptureSession#switchToOffline method and specify streams to be kept in offline 6078 mode. The camera will then stop currently active repeating requests, prepare for 6079 some requests to go into offline mode, and return an offline session object. After 6080 the switchToOffline call returns, the original capture session is in closed state as 6081 if the CameraCaptureSession#close method has been called. 6082 In the offline mode, all inflight requests will continue to be processed in the 6083 background, and the application can immediately close the camera or create a new 6084 capture session without losing those requests' output images and capture results. 6085 6086 While the camera device is processing offline requests, it 6087 might not be able to support all stream configurations it can support 6088 without offline requests. When that happens, the createCaptureSession 6089 method call will fail. The following stream configurations are guaranteed to work 6090 without hitting the resource busy exception: 6091 6092 * One ongoing offline session: target one output surface of YUV or 6093 JPEG format, any resolution. 6094 * The active camera capture session: 6095 1. One preview surface (SurfaceView or SurfaceTexture) up to 1920 width 6096 1. One YUV ImageReader surface up to 1920 width 6097 1. One Jpeg ImageReader, any resolution: the camera device is 6098 allowed to slow down JPEG output speed by 50% if there is any ongoing offline 6099 session. 6100 1. If the device supports PRIVATE_REPROCESSING, one pair of ImageWriter/ImageReader 6101 surfaces of private format, with the same resolution that is larger or equal to 6102 the JPEG ImageReader resolution above. 6103 * Alternatively, the active camera session above can be replaced by an legacy 6104 {@link android.hardware.Camera Camera} with the following parameter settings: 6105 1. Preview size up to 1920 width 6106 1. Preview callback size up to 1920 width 6107 1. Video size up to 1920 width 6108 1. Picture size, any resolution: the camera device is 6109 allowed to slow down JPEG output speed by 50% if there is any ongoing offline 6110 session. 6111 </notes> 6112 </value> 6113 <value optional="true" hal_version="3.6" >ULTRA_HIGH_RESOLUTION_SENSOR 6114 <notes> 6115 This camera device is capable of producing ultra high resolution images in 6116 addition to the image sizes described in the 6117 android.scaler.streamConfigurationMap. 6118 It can operate in 'default' mode and 'max resolution' mode. It generally does this 6119 by binning pixels in 'default' mode and not binning them in 'max resolution' mode. 6120 `android.scaler.streamConfigurationMap` describes the streams supported in 'default' 6121 mode. 6122 The stream configurations supported in 'max resolution' mode are described by 6123 `android.scaler.streamConfigurationMapMaximumResolution`. 6124 The maximum resolution mode pixel array size of a camera device 6125 (`android.sensor.info.pixelArraySize`) with this capability, 6126 will be at least 24 megapixels. 6127 </notes> 6128 </value> 6129 <value optional="true" visibility="java_public" hal_version="3.6">REMOSAIC_REPROCESSING 6130 <notes> 6131 The device supports reprocessing from the `RAW_SENSOR` format with a bayer pattern 6132 given by android.sensor.info.binningFactor (m x n group of pixels with the same 6133 color filter) to a remosaiced regular bayer pattern. 6134 6135 This capability will only be present for devices with 6136 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 6137 capability. When 6138 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 6139 devices do not advertise this capability, 6140 {@link android.graphics.ImageFormat#RAW_SENSOR} images will already have a 6141 regular bayer pattern. 6142 6143 If a `RAW_SENSOR` stream is requested along with another non-RAW stream in a 6144 {@link android.hardware.camera2.CaptureRequest} (if multiple streams are supported 6145 when android.sensor.pixelMode is set to 6146 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}), 6147 the `RAW_SENSOR` stream will have a regular bayer pattern. 6148 6149 This capability requires the camera device to support the following : 6150 * The {@link android.hardware.camera2.params.StreamConfigurationMap} mentioned below 6151 refers to the one, described by 6152 `android.scaler.streamConfigurationMapMaximumResolution`. 6153 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 6154 * {@link android.graphics.ImageFormat#RAW_SENSOR} is supported as an output/input 6155 format, that is, {@link android.graphics.ImageFormat#RAW_SENSOR} is included in the 6156 lists of formats returned by {@link 6157 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 6158 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 6159 * {@link android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 6160 returns non-empty int[] for each supported input format returned by {@link 6161 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 6162 * Each size returned by {@link 6163 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 6164 getInputSizes(ImageFormat.RAW_SENSOR)} is also included in {@link 6165 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 6166 getOutputSizes(ImageFormat.RAW_SENSOR)} 6167 * Using {@link android.graphics.ImageFormat#RAW_SENSOR} does not cause a frame rate 6168 drop relative to the sensor's maximum capture rate (at that resolution). 6169 * No CaptureRequest controls will be applicable when a request has an input target 6170 with {@link android.graphics.ImageFormat#RAW_SENSOR} format. 6171 </notes> 6172 </value> 6173 </enum> 6174 <description>List of capabilities that this camera device 6175 advertises as fully supporting.</description> 6176 <details> 6177 A capability is a contract that the camera device makes in order 6178 to be able to satisfy one or more use cases. 6179 6180 Listing a capability guarantees that the whole set of features 6181 required to support a common use will all be available. 6182 6183 Using a subset of the functionality provided by an unsupported 6184 capability may be possible on a specific camera device implementation; 6185 to do this query each of android.request.availableRequestKeys, 6186 android.request.availableResultKeys, 6187 android.request.availableCharacteristicsKeys. 6188 6189 The following capabilities are guaranteed to be available on 6190 android.info.supportedHardwareLevel `==` FULL devices: 6191 6192 * MANUAL_SENSOR 6193 * MANUAL_POST_PROCESSING 6194 6195 Other capabilities may be available on either FULL or LIMITED 6196 devices, but the application should query this key to be sure. 6197 </details> 6198 <hal_details> 6199 Additional constraint details per-capability will be available 6200 in the Compatibility Test Suite. 6201 6202 Minimum baseline requirements required for the 6203 BACKWARD_COMPATIBLE capability are not explicitly listed. 6204 Instead refer to "BC" tags and the camera CTS tests in the 6205 android.hardware.camera2.cts package. 6206 6207 Listed controls that can be either request or result (e.g. 6208 android.sensor.exposureTime) must be available both in the 6209 request and the result in order to be considered to be 6210 capability-compliant. 6211 6212 For example, if the HAL claims to support MANUAL control, 6213 then exposure time must be configurable via the request _and_ 6214 the actual exposure applied must be available via 6215 the result. 6216 6217 If MANUAL_SENSOR is omitted, the HAL may choose to omit the 6218 android.scaler.availableMinFrameDurations static property entirely. 6219 6220 For PRIVATE_REPROCESSING and YUV_REPROCESSING capabilities, see 6221 hardware/libhardware/include/hardware/camera3.h Section 10 for more information. 6222 6223 Devices that support the MANUAL_SENSOR capability must support the 6224 CAMERA3_TEMPLATE_MANUAL template defined in camera3.h. 6225 6226 Devices that support the PRIVATE_REPROCESSING capability or the 6227 YUV_REPROCESSING capability must support the 6228 CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template defined in camera3.h. 6229 6230 For DEPTH_OUTPUT, the depth-format keys 6231 android.depth.availableDepthStreamConfigurations, 6232 android.depth.availableDepthMinFrameDurations, 6233 android.depth.availableDepthStallDurations must be available, in 6234 addition to the other keys explicitly mentioned in the DEPTH_OUTPUT 6235 enum notes. The entry android.depth.maxDepthSamples must be available 6236 if the DEPTH_POINT_CLOUD format is supported (HAL pixel format BLOB, dataspace 6237 DEPTH). 6238 6239 For a camera device with LOGICAL_MULTI_CAMERA capability, it should operate in the 6240 same way as a physical camera device based on its hardware level and capabilities. 6241 It's recommended that its feature set is superset of that of individual physical cameras. 6242 6243 * In camera1 API, to maintain application compatibility, for each camera facing, there 6244 may be one or more {logical_camera_id, physical_camera_1_id, physical_camera_2_id, ...} 6245 combinations, where logical_camera_id is composed of physical_camera_N_id, camera 6246 framework will only advertise one camera id 6247 (within the combinations for the particular facing) that is frontmost in the HAL 6248 published camera id list. 6249 For example, if HAL advertises 6 back facing camera IDs (ID0 to ID5), among which ID4 6250 and ID5 are logical cameras backed by ID0+ID1 and ID2+ID3 respectively. In this case, 6251 only ID0 will be available for camera1 API to use. 6252 6253 * Camera HAL is strongly recommended to advertise camera devices with best feature, 6254 power, performance, and latency tradeoffs at the front of the camera id list. 6255 6256 * Camera HAL may switch between physical cameras depending on focalLength, cropRegion, or 6257 zoomRatio. If physical cameras have different sizes, HAL must maintain a single logical 6258 camera activeArraySize/pixelArraySize/preCorrectionActiveArraySize, and must do proper 6259 mapping between logical camera and underlying physical cameras for all related metadata 6260 tags, such as crop region, zoomRatio, 3A regions, and intrinsicCalibration. 6261 6262 * Starting from HIDL ICameraDevice version 3.5, camera HAL must support 6263 isStreamCombinationSupported for application to query whether a particular logical and 6264 physical streams combination are supported. 6265 6266 A MONOCHROME camera device must also advertise BACKWARD_COMPATIBLE capability, and must 6267 not advertise MANUAL_POST_PROCESSING capability. 6268 6269 * To maintain backward compatibility, the camera device must support all 6270 BACKWARD_COMPATIBLE required keys. The android.control.awbAvailableModes key only contains 6271 AUTO, and android.control.awbState are either CONVERGED or LOCKED depending on 6272 android.control.awbLock. 6273 6274 * android.colorCorrection.mode, android.colorCorrection.transform, and 6275 android.colorCorrection.gains must not be in available request and result keys. 6276 As a result, the camera device cannot be a FULL device. However, the HAL can 6277 still advertise other individual capabilites. 6278 6279 * If the device supports tonemap control, only android.tonemap.curveRed is used. 6280 CurveGreen and curveBlue are no-ops. 6281 6282 In Android API level 28, a MONOCHROME camera device must not have RAW capability. From 6283 API level 29, a camera is allowed to have both MONOCHROME and RAW capabilities. 6284 6285 To support the legacy API to ICameraDevice 3.x shim layer, devices advertising 6286 OFFLINE_PROCESSING capability must also support configuring an input stream of the same 6287 size as the picture size if: 6288 6289 * The device supports PRIVATE_REPROCESSING capability 6290 * The device's maximal JPEG resolution can reach 30 FPS min frame duration 6291 * The device does not support HAL based ZSL (android.control.enableZsl) 6292 6293 For devices which support SYSTEM_CAMERA and LOGICAL_MULTI_CAMERA capabilities: 6294 6295 Hidden physical camera ids[1] must not be be shared[2] between public camera devices 6296 and camera devices advertising SYSTEM_CAMERA capability. 6297 6298 [1] - Camera device ids which are advertised in the 6299 ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS list, and not available through 6300 ICameraProvider.getCameraIdList(). 6301 6302 [2] - The ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS lists, must not have common 6303 camera ids. 6304 </hal_details> 6305 </entry> 6306 <entry name="availableRequestKeys" type="int32" visibility="ndk_public" 6307 container="array" hwlevel="legacy"> 6308 <array> 6309 <size>n</size> 6310 </array> 6311 <description>A list of all keys that the camera device has available 6312 to use with {@link android.hardware.camera2.CaptureRequest|ACaptureRequest}.</description> 6313 6314 <details>Attempting to set a key into a CaptureRequest that is not 6315 listed here will result in an invalid request and will be rejected 6316 by the camera device. 6317 6318 This field can be used to query the feature set of a camera device 6319 at a more granular level than capabilities. This is especially 6320 important for optional keys that are not listed under any capability 6321 in android.request.availableCapabilities. 6322 </details> 6323 <hal_details> 6324 Vendor tags can be listed here. Vendor tag metadata should also 6325 use the extensions C api (refer to camera3.h for more details). 6326 6327 Setting/getting vendor tags will be checked against the metadata 6328 vendor extensions API and not against this field. 6329 6330 The HAL must not consume any request tags that are not listed either 6331 here or in the vendor tag list. 6332 6333 The public camera2 API will always make the vendor tags visible 6334 via 6335 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureRequestKeys}. 6336 </hal_details> 6337 </entry> 6338 <entry name="availableResultKeys" type="int32" visibility="ndk_public" 6339 container="array" hwlevel="legacy"> 6340 <array> 6341 <size>n</size> 6342 </array> 6343 <description>A list of all keys that the camera device has available to use with {@link 6344 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result}. 6345 </description> 6346 6347 <details>Attempting to get a key from a CaptureResult that is not 6348 listed here will always return a `null` value. Getting a key from 6349 a CaptureResult that is listed here will generally never return a `null` 6350 value. 6351 6352 The following keys may return `null` unless they are enabled: 6353 6354 * android.statistics.lensShadingMap (non-null iff android.statistics.lensShadingMapMode == ON) 6355 6356 (Those sometimes-null keys will nevertheless be listed here 6357 if they are available.) 6358 6359 This field can be used to query the feature set of a camera device 6360 at a more granular level than capabilities. This is especially 6361 important for optional keys that are not listed under any capability 6362 in android.request.availableCapabilities. 6363 </details> 6364 <hal_details> 6365 Tags listed here must always have an entry in the result metadata, 6366 even if that size is 0 elements. Only array-type tags (e.g. lists, 6367 matrices, strings) are allowed to have 0 elements. 6368 6369 Vendor tags can be listed here. Vendor tag metadata should also 6370 use the extensions C api (refer to camera3.h for more details). 6371 6372 Setting/getting vendor tags will be checked against the metadata 6373 vendor extensions API and not against this field. 6374 6375 The HAL must not produce any result tags that are not listed either 6376 here or in the vendor tag list. 6377 6378 The public camera2 API will always make the vendor tags visible via {@link 6379 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys}. 6380 </hal_details> 6381 </entry> 6382 <entry name="availableCharacteristicsKeys" type="int32" visibility="ndk_public" 6383 container="array" hwlevel="legacy"> 6384 <array> 6385 <size>n</size> 6386 </array> 6387 <description>A list of all keys that the camera device has available to use with {@link 6388 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics}. 6389 </description> 6390 <details>This entry follows the same rules as 6391 android.request.availableResultKeys (except that it applies for 6392 CameraCharacteristics instead of CaptureResult). See above for more 6393 details. 6394 </details> 6395 <hal_details> 6396 Keys listed here must always have an entry in the static info metadata, 6397 even if that size is 0 elements. Only array-type tags (e.g. lists, 6398 matrices, strings) are allowed to have 0 elements. 6399 6400 Vendor tags can listed here. Vendor tag metadata should also use 6401 the extensions C api (refer to camera3.h for more details). 6402 6403 Setting/getting vendor tags will be checked against the metadata 6404 vendor extensions API and not against this field. 6405 6406 The HAL must not have any tags in its static info that are not listed 6407 either here or in the vendor tag list. 6408 6409 The public camera2 API will always make the vendor tags visible 6410 via {@link android.hardware.camera2.CameraCharacteristics#getKeys}. 6411 </hal_details> 6412 </entry> 6413 <entry name="availableSessionKeys" type="int32" visibility="ndk_public" 6414 container="array" hwlevel="legacy" hal_version="3.3"> 6415 <array> 6416 <size>n</size> 6417 </array> 6418 <description>A subset of the available request keys that the camera device 6419 can pass as part of the capture session initialization.</description> 6420 6421 <details> This is a subset of android.request.availableRequestKeys which 6422 contains a list of keys that are difficult to apply per-frame and 6423 can result in unexpected delays when modified during the capture session 6424 lifetime. Typical examples include parameters that require a 6425 time-consuming hardware re-configuration or internal camera pipeline 6426 change. For performance reasons we advise clients to pass their initial 6427 values as part of 6428 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 6429 Once the camera capture session is enabled it is also recommended to avoid 6430 changing them from their initial values set in 6431 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 6432 Control over session parameters can still be exerted in capture requests 6433 but clients should be aware and expect delays during their application. 6434 An example usage scenario could look like this: 6435 6436 * The camera client starts by quering the session parameter key list via 6437 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 6438 * Before triggering the capture session create sequence, a capture request 6439 must be built via 6440 {@link CameraDevice#createCaptureRequest|ACameraDevice_createCaptureRequest} 6441 using an appropriate template matching the particular use case. 6442 * The client should go over the list of session parameters and check 6443 whether some of the keys listed matches with the parameters that 6444 they intend to modify as part of the first capture request. 6445 * If there is no such match, the capture request can be passed 6446 unmodified to 6447 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 6448 * If matches do exist, the client should update the respective values 6449 and pass the request to 6450 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 6451 * After the capture session initialization completes the session parameter 6452 key list can continue to serve as reference when posting or updating 6453 further requests. As mentioned above further changes to session 6454 parameters should ideally be avoided, if updates are necessary 6455 however clients could expect a delay/glitch during the 6456 parameter switch. 6457 6458 </details> 6459 <hal_details> 6460 If android.control.aeTargetFpsRange is part of the session parameters and constrained high 6461 speed mode is enabled, then only modifications of the maximum framerate value will be 6462 monitored by the framework and can trigger camera re-configuration. For more information 6463 about framerate ranges during constrained high speed sessions see 6464 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. 6465 Vendor tags can be listed here. Vendor tag metadata should also 6466 use the extensions C api (refer to 6467 android.hardware.camera.device.V3_4.StreamConfiguration.sessionParams for more details). 6468 6469 Setting/getting vendor tags will be checked against the metadata 6470 vendor extensions API and not against this field. 6471 6472 The HAL must not consume any request tags in the session parameters that 6473 are not listed either here or in the vendor tag list. 6474 6475 The public camera2 API will always make the vendor tags visible 6476 via 6477 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys}. 6478 </hal_details> 6479 </entry> 6480 <entry name="availablePhysicalCameraRequestKeys" type="int32" visibility="ndk_public" 6481 container="array" hwlevel="limited" hal_version="3.3"> 6482 <array> 6483 <size>n</size> 6484 </array> 6485 <description>A subset of the available request keys that can be overridden for 6486 physical devices backing a logical multi-camera.</description> 6487 <details> 6488 This is a subset of android.request.availableRequestKeys which contains a list 6489 of keys that can be overridden using {@link CaptureRequest.Builder#setPhysicalCameraKey}. 6490 The respective value of such request key can be obtained by calling 6491 {@link CaptureRequest.Builder#getPhysicalCameraKey}. Capture requests that contain 6492 individual physical device requests must be built via 6493 {@link android.hardware.camera2.CameraDevice#createCaptureRequest(int, Set)}. 6494 </details> 6495 <hal_details> 6496 Vendor tags can be listed here. Vendor tag metadata should also 6497 use the extensions C api (refer to 6498 android.hardware.camera.device.V3_4.CaptureRequest.physicalCameraSettings for more 6499 details). 6500 6501 Setting/getting vendor tags will be checked against the metadata 6502 vendor extensions API and not against this field. 6503 6504 The HAL must not consume any request tags in the session parameters that 6505 are not listed either here or in the vendor tag list. 6506 6507 There should be no overlap between this set of keys and the available session keys 6508 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys} along 6509 with any other controls that can have impact on the dual-camera sync. 6510 6511 The public camera2 API will always make the vendor tags visible 6512 via 6513 {@link android.hardware.camera2.CameraCharacteristics#getAvailablePhysicalCameraRequestKeys}. 6514 </hal_details> 6515 </entry> 6516 <entry name="characteristicKeysNeedingPermission" type="int32" visibility="hidden" 6517 container="array" hwlevel="legacy" hal_version="3.4"> 6518 <array> 6519 <size>n</size> 6520 </array> 6521 <description>A list of camera characteristics keys that are only available 6522 in case the camera client has camera permission.</description> 6523 6524 <details>The entry contains a subset of 6525 {@link android.hardware.camera2.CameraCharacteristics#getKeys} that require camera clients 6526 to acquire the {@link android.Manifest.permission#CAMERA} permission before calling 6527 {@link android.hardware.camera2.CameraManager#getCameraCharacteristics}. If the 6528 permission is not held by the camera client, then the values of the repsective properties 6529 will not be present in {@link android.hardware.camera2.CameraCharacteristics}. 6530 </details> 6531 <hal_details> 6532 Do not set this property directly, camera service will overwrite any previous values. 6533 </hal_details> 6534 </entry> 6535 </static> 6536 </section> 6537 <section name="scaler"> 6538 <controls> 6539 <entry name="cropRegion" type="int32" visibility="public" 6540 container="array" typedef="rectangle" hwlevel="legacy"> 6541 <array> 6542 <size>4</size> 6543 </array> 6544 <description>The desired region of the sensor to read out for this capture.</description> 6545 <units>Pixel coordinates relative to 6546 android.sensor.info.activeArraySize or 6547 android.sensor.info.preCorrectionActiveArraySize depending on distortion correction 6548 capability and mode</units> 6549 <details> 6550 This control can be used to implement digital zoom. 6551 6552 For devices not supporting android.distortionCorrection.mode control, the coordinate 6553 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 6554 the top-left pixel of the active array. 6555 6556 For devices supporting android.distortionCorrection.mode control, the coordinate system 6557 depends on the mode being set. When the distortion correction mode is OFF, the 6558 coordinate system follows android.sensor.info.preCorrectionActiveArraySize, with `(0, 6559 0)` being the top-left pixel of the pre-correction active array. When the distortion 6560 correction mode is not OFF, the coordinate system follows 6561 android.sensor.info.activeArraySize, with `(0, 0)` being the top-left pixel of the 6562 active array. 6563 6564 Output streams use this rectangle to produce their output, cropping to a smaller region 6565 if necessary to maintain the stream's aspect ratio, then scaling the sensor input to 6566 match the output's configured resolution. 6567 6568 The crop region is applied after the RAW to other color space (e.g. YUV) 6569 conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, they are not 6570 croppable. The crop region will be ignored by raw streams. 6571 6572 For non-raw streams, any additional per-stream cropping will be done to maximize the 6573 final pixel area of the stream. 6574 6575 For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use 6576 the exact crop region. 16:9 streams will further crop vertically (letterbox). 6577 6578 Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally 6579 (pillarbox), and 16:9 streams will match exactly. These additional crops will be 6580 centered within the crop region. 6581 6582 To illustrate, here are several scenarios of different crop regions and output streams, 6583 for a hypothetical camera device with an active array of size `(2000,1500)`. Note that 6584 several of these examples use non-centered crop regions for ease of illustration; such 6585 regions are only supported on devices with FREEFORM capability 6586 (android.scaler.croppingType `== FREEFORM`), but this does not affect the way the crop 6587 rules work otherwise. 6588 6589 * Camera Configuration: 6590 * Active array size: `2000x1500` (3 MP, 4:3 aspect ratio) 6591 * Output stream #1: `640x480` (VGA, 4:3 aspect ratio) 6592 * Output stream #2: `1280x720` (720p, 16:9 aspect ratio) 6593 * Case #1: 4:3 crop region with 2x digital zoom 6594 * Crop region: `Rect(500, 375, 1500, 1125) // (left, top, right, bottom)` 6595 *  6596 * `640x480` stream source area: `(500, 375, 1500, 1125)` (equal to crop region) 6597 * `1280x720` stream source area: `(500, 469, 1500, 1031)` (letterboxed) 6598 * Case #2: 16:9 crop region with ~1.5x digital zoom. 6599 * Crop region: `Rect(500, 375, 1833, 1125)` 6600 *  6601 * `640x480` stream source area: `(666, 375, 1666, 1125)` (pillarboxed) 6602 * `1280x720` stream source area: `(500, 375, 1833, 1125)` (equal to crop region) 6603 * Case #3: 1:1 crop region with ~2.6x digital zoom. 6604 * Crop region: `Rect(500, 375, 1250, 1125)` 6605 *  6606 * `640x480` stream source area: `(500, 469, 1250, 1031)` (letterboxed) 6607 * `1280x720` stream source area: `(500, 543, 1250, 957)` (letterboxed) 6608 * Case #4: Replace `640x480` stream with `1024x1024` stream, with 4:3 crop region: 6609 * Crop region: `Rect(500, 375, 1500, 1125)` 6610 *  6611 * `1024x1024` stream source area: `(625, 375, 1375, 1125)` (pillarboxed) 6612 * `1280x720` stream source area: `(500, 469, 1500, 1031)` (letterboxed) 6613 * Note that in this case, neither of the two outputs is a subset of the other, with 6614 each containing image data the other doesn't have. 6615 6616 If the coordinate system is android.sensor.info.activeArraySize, the width and height 6617 of the crop region cannot be set to be smaller than 6618 `floor( activeArraySize.width / android.scaler.availableMaxDigitalZoom )` and 6619 `floor( activeArraySize.height / android.scaler.availableMaxDigitalZoom )`, respectively. 6620 6621 If the coordinate system is android.sensor.info.preCorrectionActiveArraySize, the width 6622 and height of the crop region cannot be set to be smaller than 6623 `floor( preCorrectionActiveArraySize.width / android.scaler.availableMaxDigitalZoom )` 6624 and 6625 `floor( preCorrectionActiveArraySize.height / android.scaler.availableMaxDigitalZoom )`, 6626 respectively. 6627 6628 The camera device may adjust the crop region to account for rounding and other hardware 6629 requirements; the final crop region used will be included in the output capture result. 6630 6631 The camera sensor output aspect ratio depends on factors such as output stream 6632 combination and android.control.aeTargetFpsRange, and shouldn't be adjusted by using 6633 this control. And the camera device will treat different camera sensor output sizes 6634 (potentially with in-sensor crop) as the same crop of 6635 android.sensor.info.activeArraySize. As a result, the application shouldn't assume the 6636 maximum crop region always maps to the same aspect ratio or field of view for the 6637 sensor output. 6638 6639 Starting from API level 30, it's strongly recommended to use android.control.zoomRatio 6640 to take advantage of better support for zoom with logical multi-camera. The benefits 6641 include better precision with optical-digital zoom combination, and ability to do 6642 zoom-out from 1.0x. When using android.control.zoomRatio for zoom, the crop region in 6643 the capture request should be left as the default activeArray size. The 6644 coordinate system is post-zoom, meaning that the activeArraySize or 6645 preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. See 6646 android.control.zoomRatio for details. 6647 6648 For camera devices with the 6649 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 6650 capability, android.sensor.info.activeArraySizeMaximumResolution / 6651 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 6652 coordinate system for requests where android.sensor.pixelMode is set to 6653 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 6654 </details> 6655 <ndk_details> 6656 The data representation is int[4], which maps to (left, top, width, height). 6657 </ndk_details> 6658 <hal_details> 6659 The output streams must maintain square pixels at all 6660 times, no matter what the relative aspect ratios of the 6661 crop region and the stream are. Negative values for 6662 corner are allowed for raw output if full pixel array is 6663 larger than active pixel array. Width and height may be 6664 rounded to nearest larger supportable width, especially 6665 for raw output, where only a few fixed scales may be 6666 possible. 6667 6668 If android.control.zoomRatio is supported by the HAL, the HAL must report the zoom 6669 ratio via android.control.zoomRatio, and change the coordinate system such that 6670 android.sensor.info.preCorrectionActiveArraySize or android.sensor.info.activeArraySize 6671 (depending on whether android.distortionCorrection.mode is supported) is used to 6672 represent the camera field-of-view after zoom. see android.control.zoomRatio for 6673 details. 6674 6675 HAL2.x uses only (x, y, width) 6676 </hal_details> 6677 <tag id="BC" /> 6678 </entry> 6679 </controls> 6680 <static> 6681 <entry name="availableFormats" type="int32" 6682 visibility="hidden" deprecated="true" enum="true" 6683 container="array" typedef="imageFormat"> 6684 <array> 6685 <size>n</size> 6686 </array> 6687 <enum> 6688 <value optional="true" id="0x20">RAW16 6689 <notes> 6690 RAW16 is a standard, cross-platform format for raw image 6691 buffers with 16-bit pixels. 6692 6693 Buffers of this format are typically expected to have a 6694 Color Filter Array (CFA) layout, which is given in 6695 android.sensor.info.colorFilterArrangement. Sensors with 6696 CFAs that are not representable by a format in 6697 android.sensor.info.colorFilterArrangement should not 6698 use this format. 6699 6700 Buffers of this format will also follow the constraints given for 6701 RAW_OPAQUE buffers, but with relaxed performance constraints. 6702 6703 This format is intended to give users access to the full contents 6704 of the buffers coming directly from the image sensor prior to any 6705 cropping or scaling operations, and all coordinate systems for 6706 metadata used for this format are relative to the size of the 6707 active region of the image sensor before any geometric distortion 6708 correction has been applied (i.e. 6709 android.sensor.info.preCorrectionActiveArraySize). Supported 6710 dimensions for this format are limited to the full dimensions of 6711 the sensor (e.g. either android.sensor.info.pixelArraySize or 6712 android.sensor.info.preCorrectionActiveArraySize will be the 6713 only supported output size). 6714 6715 See android.scaler.availableInputOutputFormatsMap for 6716 the full set of performance guarantees. 6717 </notes> 6718 </value> 6719 <value optional="true" id="0x24">RAW_OPAQUE 6720 <notes> 6721 RAW_OPAQUE (or 6722 {@link android.graphics.ImageFormat#RAW_PRIVATE RAW_PRIVATE} 6723 as referred in public API) is a format for raw image buffers 6724 coming from an image sensor. 6725 6726 The actual structure of buffers of this format is 6727 platform-specific, but must follow several constraints: 6728 6729 1. No image post-processing operations may have been applied to 6730 buffers of this type. These buffers contain raw image data coming 6731 directly from the image sensor. 6732 1. If a buffer of this format is passed to the camera device for 6733 reprocessing, the resulting images will be identical to the images 6734 produced if the buffer had come directly from the sensor and was 6735 processed with the same settings. 6736 6737 The intended use for this format is to allow access to the native 6738 raw format buffers coming directly from the camera sensor without 6739 any additional conversions or decrease in framerate. 6740 6741 See android.scaler.availableInputOutputFormatsMap for the full set of 6742 performance guarantees. 6743 </notes> 6744 </value> 6745 <value optional="true" id="0x32315659">YV12 6746 <notes>YCrCb 4:2:0 Planar</notes> 6747 </value> 6748 <value optional="true" id="0x11">YCrCb_420_SP 6749 <notes>NV21</notes> 6750 </value> 6751 <value id="0x22">IMPLEMENTATION_DEFINED 6752 <notes>System internal format, not application-accessible</notes> 6753 </value> 6754 <value id="0x23">YCbCr_420_888 6755 <notes>Flexible YUV420 Format</notes> 6756 </value> 6757 <value id="0x21">BLOB 6758 <notes>JPEG format</notes> 6759 </value> 6760 <value id="0x25" hal_version="3.4">RAW10 6761 <notes>RAW10</notes> 6762 </value> 6763 <value id="0x26" hal_version="3.4">RAW12 6764 <notes>RAW12</notes> 6765 </value> 6766 <value id="0x20203859" hal_version="3.4">Y8 6767 <notes>Y8</notes> 6768 </value> 6769 </enum> 6770 <description>The list of image formats that are supported by this 6771 camera device for output streams.</description> 6772 <deprecation_description> 6773 Not used in HALv3 or newer 6774 </deprecation_description> 6775 <details> 6776 All camera devices will support JPEG and YUV_420_888 formats. 6777 6778 When set to YUV_420_888, application can access the YUV420 data directly. 6779 </details> 6780 <hal_details> 6781 These format values are from HAL_PIXEL_FORMAT_* in 6782 system/core/libsystem/include/system/graphics-base.h. 6783 6784 When IMPLEMENTATION_DEFINED is used, the platform 6785 gralloc module will select a format based on the usage flags provided 6786 by the camera HAL device and the other endpoint of the stream. It is 6787 usually used by preview and recording streams, where the application doesn't 6788 need access the image data. 6789 6790 YCbCr_420_888 format must be supported by the HAL. When an image stream 6791 needs CPU/application direct access, this format will be used. For a MONOCHROME 6792 camera device, the pixel value of Cb and Cr planes is 128. 6793 6794 The BLOB format must be supported by the HAL. This is used for the JPEG stream. 6795 6796 A RAW_OPAQUE buffer should contain only pixel data. It is strongly 6797 recommended that any information used by the camera device when 6798 processing images is fully expressed by the result metadata 6799 for that image buffer. 6800 </hal_details> 6801 <tag id="BC" /> 6802 </entry> 6803 <entry name="availableJpegMinDurations" type="int64" visibility="hidden" deprecated="true" 6804 container="array"> 6805 <array> 6806 <size>n</size> 6807 </array> 6808 <description>The minimum frame duration that is supported 6809 for each resolution in android.scaler.availableJpegSizes. 6810 </description> 6811 <deprecation_description> 6812 Not used in HALv3 or newer 6813 </deprecation_description> 6814 <units>Nanoseconds</units> 6815 <range>TODO: Remove property.</range> 6816 <details> 6817 This corresponds to the minimum steady-state frame duration when only 6818 that JPEG stream is active and captured in a burst, with all 6819 processing (typically in android.*.mode) set to FAST. 6820 6821 When multiple streams are configured, the minimum 6822 frame duration will be &gt;= max(individual stream min 6823 durations)</details> 6824 <tag id="BC" /> 6825 </entry> 6826 <entry name="availableJpegSizes" type="int32" visibility="hidden" 6827 deprecated="true" container="array" typedef="size"> 6828 <array> 6829 <size>n</size> 6830 <size>2</size> 6831 </array> 6832 <description>The JPEG resolutions that are supported by this camera device.</description> 6833 <deprecation_description> 6834 Not used in HALv3 or newer 6835 </deprecation_description> 6836 <range>TODO: Remove property.</range> 6837 <details> 6838 The resolutions are listed as `(width, height)` pairs. All camera devices will support 6839 sensor maximum resolution (defined by android.sensor.info.activeArraySize). 6840 </details> 6841 <hal_details> 6842 The HAL must include sensor maximum resolution 6843 (defined by android.sensor.info.activeArraySize), 6844 and should include half/quarter of sensor maximum resolution. 6845 </hal_details> 6846 <tag id="BC" /> 6847 </entry> 6848 <entry name="availableMaxDigitalZoom" type="float" visibility="public" 6849 hwlevel="legacy"> 6850 <description>The maximum ratio between both active area width 6851 and crop region width, and active area height and 6852 crop region height, for android.scaler.cropRegion. 6853 </description> 6854 <units>Zoom scale factor</units> 6855 <range>&gt;=1</range> 6856 <details> 6857 This represents the maximum amount of zooming possible by 6858 the camera device, or equivalently, the minimum cropping 6859 window size. 6860 6861 Crop regions that have a width or height that is smaller 6862 than this ratio allows will be rounded up to the minimum 6863 allowed size by the camera device. 6864 6865 Starting from API level 30, when using android.control.zoomRatio to zoom in or out, 6866 the application must use android.control.zoomRatioRange to query both the minimum and 6867 maximum zoom ratio. 6868 </details> 6869 <hal_details> 6870 If the HAL supports android.control.zoomRatio, this value must be equal to or less than 6871 the maximum supported zoomRatio specified in android.control.zoomRatioRange. 6872 </hal_details> 6873 <tag id="BC" /> 6874 </entry> 6875 <entry name="availableProcessedMinDurations" type="int64" visibility="hidden" deprecated="true" 6876 container="array"> 6877 <array> 6878 <size>n</size> 6879 </array> 6880 <description>For each available processed output size (defined in 6881 android.scaler.availableProcessedSizes), this property lists the 6882 minimum supportable frame duration for that size. 6883 </description> 6884 <deprecation_description> 6885 Not used in HALv3 or newer 6886 </deprecation_description> 6887 <units>Nanoseconds</units> 6888 <details> 6889 This should correspond to the frame duration when only that processed 6890 stream is active, with all processing (typically in android.*.mode) 6891 set to FAST. 6892 6893 When multiple streams are configured, the minimum frame duration will 6894 be &gt;= max(individual stream min durations). 6895 </details> 6896 <tag id="BC" /> 6897 </entry> 6898 <entry name="availableProcessedSizes" type="int32" visibility="hidden" 6899 deprecated="true" container="array" typedef="size"> 6900 <array> 6901 <size>n</size> 6902 <size>2</size> 6903 </array> 6904 <description>The resolutions available for use with 6905 processed output streams, such as YV12, NV12, and 6906 platform opaque YUV/RGB streams to the GPU or video 6907 encoders.</description> 6908 <deprecation_description> 6909 Not used in HALv3 or newer 6910 </deprecation_description> 6911 <details> 6912 The resolutions are listed as `(width, height)` pairs. 6913 6914 For a given use case, the actual maximum supported resolution 6915 may be lower than what is listed here, depending on the destination 6916 Surface for the image data. For example, for recording video, 6917 the video encoder chosen may have a maximum size limit (e.g. 1080p) 6918 smaller than what the camera (e.g. maximum resolution is 3264x2448) 6919 can provide. 6920 6921 Please reference the documentation for the image data destination to 6922 check if it limits the maximum size for image data. 6923 </details> 6924 <hal_details> 6925 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 6926 the HAL must include all JPEG sizes listed in android.scaler.availableJpegSizes 6927 and each below resolution if it is smaller than or equal to the sensor 6928 maximum resolution (if they are not listed in JPEG sizes already): 6929 6930 * 240p (320 x 240) 6931 * 480p (640 x 480) 6932 * 720p (1280 x 720) 6933 * 1080p (1920 x 1080) 6934 6935 For LIMITED capability devices (`android.info.supportedHardwareLevel == LIMITED`), 6936 the HAL only has to list up to the maximum video size supported by the devices. 6937 </hal_details> 6938 <tag id="BC" /> 6939 </entry> 6940 <entry name="availableRawMinDurations" type="int64" deprecated="true" 6941 container="array"> 6942 <array> 6943 <size>n</size> 6944 </array> 6945 <description> 6946 For each available raw output size (defined in 6947 android.scaler.availableRawSizes), this property lists the minimum 6948 supportable frame duration for that size. 6949 </description> 6950 <deprecation_description> 6951 Not used in HALv3 or newer 6952 </deprecation_description> 6953 <units>Nanoseconds</units> 6954 <details> 6955 Should correspond to the frame duration when only the raw stream is 6956 active. 6957 6958 When multiple streams are configured, the minimum 6959 frame duration will be &gt;= max(individual stream min 6960 durations)</details> 6961 <tag id="BC" /> 6962 </entry> 6963 <entry name="availableRawSizes" type="int32" deprecated="true" 6964 container="array" typedef="size"> 6965 <array> 6966 <size>n</size> 6967 <size>2</size> 6968 </array> 6969 <description>The resolutions available for use with raw 6970 sensor output streams, listed as width, 6971 height</description> 6972 <deprecation_description> 6973 Not used in HALv3 or newer 6974 </deprecation_description> 6975 </entry> 6976 </static> 6977 <dynamic> 6978 <clone entry="android.scaler.cropRegion" kind="controls"> 6979 </clone> 6980 </dynamic> 6981 <static> 6982 <entry name="availableInputOutputFormatsMap" type="int32" visibility="hidden" 6983 typedef="reprocessFormatsMap"> 6984 <description>The mapping of image formats that are supported by this 6985 camera device for input streams, to their corresponding output formats. 6986 </description> 6987 <details> 6988 All camera devices with at least 1 6989 android.request.maxNumInputStreams will have at least one 6990 available input format. 6991 6992 The camera device will support the following map of formats, 6993 if its dependent capability (android.request.availableCapabilities) is supported: 6994 6995 Input Format | Output Format | Capability 6996 :-------------------------------------------------|:--------------------------------------------------|:---------- 6997 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#JPEG} | PRIVATE_REPROCESSING 6998 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#YUV_420_888} | PRIVATE_REPROCESSING 6999 {@link android.graphics.ImageFormat#YUV_420_888} | {@link android.graphics.ImageFormat#JPEG} | YUV_REPROCESSING 7000 {@link android.graphics.ImageFormat#YUV_420_888} | {@link android.graphics.ImageFormat#YUV_420_888} | YUV_REPROCESSING 7001 7002 PRIVATE refers to a device-internal format that is not directly application-visible. A 7003 PRIVATE input surface can be acquired by {@link android.media.ImageReader#newInstance} 7004 with {@link android.graphics.ImageFormat#PRIVATE} as the format. 7005 7006 For a PRIVATE_REPROCESSING-capable camera device, using the PRIVATE format as either input 7007 or output will never hurt maximum frame rate (i.e. {@link 7008 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration 7009 getOutputStallDuration(ImageFormat.PRIVATE, size)} is always 0), 7010 7011 Attempting to configure an input stream with output streams not 7012 listed as available in this map is not valid. 7013 7014 Additionally, if the camera device is MONOCHROME with Y8 support, it will also support 7015 the following map of formats if its dependent capability 7016 (android.request.availableCapabilities) is supported: 7017 7018 Input Format | Output Format | Capability 7019 :-------------------------------------------------|:--------------------------------------------------|:---------- 7020 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#Y8} | PRIVATE_REPROCESSING 7021 {@link android.graphics.ImageFormat#Y8} | {@link android.graphics.ImageFormat#JPEG} | YUV_REPROCESSING 7022 {@link android.graphics.ImageFormat#Y8} | {@link android.graphics.ImageFormat#Y8} | YUV_REPROCESSING 7023 7024 </details> 7025 <hal_details> 7026 For the formats, see `system/core/libsystem/include/system/graphics-base.h` for a 7027 definition of the image format enumerations. The PRIVATE format refers to the 7028 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED format. The HAL could determine 7029 the actual format by using the gralloc usage flags. 7030 For ZSL use case in particular, the HAL could choose appropriate format (partially 7031 processed YUV or RAW based format) by checking the format and GRALLOC_USAGE_HW_CAMERA_ZSL. 7032 See camera3.h for more details. 7033 7034 This value is encoded as a variable-size array-of-arrays. 7035 The inner array always contains `[format, length, ...]` where 7036 `...` has `length` elements. An inner array is followed by another 7037 inner array if the total metadata entry size hasn't yet been exceeded. 7038 7039 A code sample to read/write this encoding (with a device that 7040 supports reprocessing IMPLEMENTATION_DEFINED to YUV_420_888, and JPEG, 7041 and reprocessing YUV_420_888 to YUV_420_888 and JPEG): 7042 7043 // reading 7044 int32_t* contents = &entry.i32[0]; 7045 for (size_t i = 0; i < entry.count; ) { 7046 int32_t format = contents[i++]; 7047 int32_t length = contents[i++]; 7048 int32_t output_formats[length]; 7049 memcpy(&output_formats[0], &contents[i], 7050 length * sizeof(int32_t)); 7051 i += length; 7052 } 7053 7054 // writing (static example, PRIVATE_REPROCESSING + YUV_REPROCESSING) 7055 int32_t[] contents = { 7056 IMPLEMENTATION_DEFINED, 2, YUV_420_888, BLOB, 7057 YUV_420_888, 2, YUV_420_888, BLOB, 7058 }; 7059 update_camera_metadata_entry(metadata, index, &contents[0], 7060 sizeof(contents)/sizeof(contents[0]), &updated_entry); 7061 7062 If the HAL claims to support any of the capabilities listed in the 7063 above details, then it must also support all the input-output 7064 combinations listed for that capability. It can optionally support 7065 additional formats if it so chooses. 7066 </hal_details> 7067 <tag id="REPROC" /> 7068 </entry> 7069 <entry name="availableStreamConfigurations" type="int32" visibility="ndk_public" 7070 enum="true" container="array" typedef="streamConfiguration" hwlevel="legacy"> 7071 <array> 7072 <size>n</size> 7073 <size>4</size> 7074 </array> 7075 <enum> 7076 <value>OUTPUT</value> 7077 <value>INPUT</value> 7078 </enum> 7079 <description>The available stream configurations that this 7080 camera device supports 7081 (i.e. format, width, height, output/input stream). 7082 </description> 7083 <details> 7084 The configurations are listed as `(format, width, height, input?)` 7085 tuples. 7086 7087 For a given use case, the actual maximum supported resolution 7088 may be lower than what is listed here, depending on the destination 7089 Surface for the image data. For example, for recording video, 7090 the video encoder chosen may have a maximum size limit (e.g. 1080p) 7091 smaller than what the camera (e.g. maximum resolution is 3264x2448) 7092 can provide. 7093 7094 Please reference the documentation for the image data destination to 7095 check if it limits the maximum size for image data. 7096 7097 Not all output formats may be supported in a configuration with 7098 an input stream of a particular format. For more details, see 7099 android.scaler.availableInputOutputFormatsMap. 7100 7101 For applications targeting SDK version older than 31, the following table 7102 describes the minimum required output stream configurations based on the hardware level 7103 (android.info.supportedHardwareLevel): 7104 7105 Format | Size | Hardware Level | Notes 7106 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 7107 JPEG | android.sensor.info.activeArraySize | Any | 7108 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 7109 JPEG | 1280x720 (720) | Any | if 720p <= activeArraySize 7110 JPEG | 640x480 (480p) | Any | if 480p <= activeArraySize 7111 JPEG | 320x240 (240p) | Any | if 240p <= activeArraySize 7112 YUV_420_888 | all output sizes available for JPEG | FULL | 7113 YUV_420_888 | all output sizes available for JPEG, up to the maximum video size | LIMITED | 7114 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 7115 7116 For applications targeting SDK version 31 or newer, if the mobile device declares to be 7117 media performance class 12 or higher by setting 7118 {@link android.os.Build.VERSION_CDOES.MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 7119 the primary camera devices (first rear/front camera in the camera ID list) will not 7120 support JPEG sizes smaller than 1080p. If the application configures a JPEG stream 7121 smaller than 1080p, the camera device will round up the JPEG image size to at least 7122 1080p. The requirements for IMPLEMENTATION_DEFINED and YUV_420_888 stay the same. 7123 This new minimum required output stream configurations are illustrated by the table below: 7124 7125 Format | Size | Hardware Level | Notes 7126 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 7127 JPEG | android.sensor.info.activeArraySize | Any | 7128 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 7129 YUV_420_888 | android.sensor.info.activeArraySize | FULL | 7130 YUV_420_888 | 1920x1080 (1080p) | FULL | if 1080p <= activeArraySize 7131 YUV_420_888 | 1280x720 (720) | FULL | if 720p <= activeArraySize 7132 YUV_420_888 | 640x480 (480p) | FULL | if 480p <= activeArraySize 7133 YUV_420_888 | 320x240 (240p) | FULL | if 240p <= activeArraySize 7134 YUV_420_888 | all output sizes available for FULL hardware level, up to the maximum video size | LIMITED | 7135 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 7136 7137 For applications targeting SDK version 31 or newer, if the mobile device doesn't declare 7138 to be media performance class 12 or better by setting 7139 {@link android.os.Build.VERSION_CDOES.MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 7140 or if the camera device isn't a primary rear/front camera, the minimum required output 7141 stream configurations are the same as for applications targeting SDK version older than 7142 31. 7143 7144 Refer to android.request.availableCapabilities for additional 7145 mandatory stream configurations on a per-capability basis. 7146 7147 Exception on 176x144 (QCIF) resolution: camera devices usually have a fixed capability for 7148 downscaling from larger resolution to smaller, and the QCIF resolution sometimes is not 7149 fully supported due to this limitation on devices with high-resolution image sensors. 7150 Therefore, trying to configure a QCIF resolution stream together with any other 7151 stream larger than 1920x1080 resolution (either width or height) might not be supported, 7152 and capture session creation will fail if it is not. 7153 7154 </details> 7155 <hal_details> 7156 It is recommended (but not mandatory) to also include half/quarter 7157 of sensor maximum resolution for JPEG formats (regardless of hardware 7158 level). 7159 7160 (The following is a rewording of the above required table): 7161 7162 For JPEG format, the sizes may be restricted by below conditions: 7163 7164 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 7165 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 7166 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 7167 it does not have to be included in the supported JPEG sizes. 7168 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 7169 the dimensions being a multiple of 16. 7170 7171 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 7172 However, the largest JPEG size must be as close as possible to the sensor maximum 7173 resolution given above constraints. It is required that after aspect ratio adjustments, 7174 additional size reduction due to other issues must be less than 3% in area. For example, 7175 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 7176 ratio 4:3, the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 7177 3264x2448. 7178 7179 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 7180 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 7181 here as output streams. 7182 7183 It must also include each below resolution if it is smaller than or 7184 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 7185 formats), as output streams: 7186 7187 * 240p (320 x 240) 7188 * 480p (640 x 480) 7189 * 720p (1280 x 720) 7190 * 1080p (1920 x 1080) 7191 7192 Note that for primary cameras (first rear/front facing camera in the camera ID list) 7193 on a device with {@link android.os.Build.VERSION_CDOES.MEDIA_PERFORMANCE_CLASS} set to 7194 31 or larger, camera framework filters out JPEG sizes smaller than 1080p depending on 7195 applications' targetSdkLevel. The camera HAL must still support the smaller JPEG sizes 7196 to maintain backward compatibility. 7197 7198 For LIMITED capability devices 7199 (`android.info.supportedHardwareLevel == LIMITED`), 7200 the HAL only has to list up to the maximum video size 7201 supported by the device. 7202 7203 Regardless of hardware level, every output resolution available for 7204 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 7205 7206 This supercedes the following fields, which are now deprecated: 7207 7208 * availableFormats 7209 * available[Processed,Raw,Jpeg]Sizes 7210 </hal_details> 7211 </entry> 7212 <entry name="availableMinFrameDurations" type="int64" visibility="ndk_public" 7213 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 7214 <array> 7215 <size>4</size> 7216 <size>n</size> 7217 </array> 7218 <description>This lists the minimum frame duration for each 7219 format/size combination. 7220 </description> 7221 <units>(format, width, height, ns) x n</units> 7222 <details> 7223 This should correspond to the frame duration when only that 7224 stream is active, with all processing (typically in android.*.mode) 7225 set to either OFF or FAST. 7226 7227 When multiple streams are used in a request, the minimum frame 7228 duration will be max(individual stream min durations). 7229 7230 See android.sensor.frameDuration and 7231 android.scaler.availableStallDurations for more details about 7232 calculating the max frame rate. 7233 </details> 7234 <tag id="V1" /> 7235 </entry> 7236 <entry name="availableStallDurations" type="int64" visibility="ndk_public" 7237 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 7238 <array> 7239 <size>4</size> 7240 <size>n</size> 7241 </array> 7242 <description>This lists the maximum stall duration for each 7243 output format/size combination. 7244 </description> 7245 <units>(format, width, height, ns) x n</units> 7246 <details> 7247 A stall duration is how much extra time would get added 7248 to the normal minimum frame duration for a repeating request 7249 that has streams with non-zero stall. 7250 7251 For example, consider JPEG captures which have the following 7252 characteristics: 7253 7254 * JPEG streams act like processed YUV streams in requests for which 7255 they are not included; in requests in which they are directly 7256 referenced, they act as JPEG streams. This is because supporting a 7257 JPEG stream requires the underlying YUV data to always be ready for 7258 use by a JPEG encoder, but the encoder will only be used (and impact 7259 frame duration) on requests that actually reference a JPEG stream. 7260 * The JPEG processor can run concurrently to the rest of the camera 7261 pipeline, but cannot process more than 1 capture at a time. 7262 7263 In other words, using a repeating YUV request would result 7264 in a steady frame rate (let's say it's 30 FPS). If a single 7265 JPEG request is submitted periodically, the frame rate will stay 7266 at 30 FPS (as long as we wait for the previous JPEG to return each 7267 time). If we try to submit a repeating YUV + JPEG request, then 7268 the frame rate will drop from 30 FPS. 7269 7270 In general, submitting a new request with a non-0 stall time 7271 stream will _not_ cause a frame rate drop unless there are still 7272 outstanding buffers for that stream from previous requests. 7273 7274 Submitting a repeating request with streams (call this `S`) 7275 is the same as setting the minimum frame duration from 7276 the normal minimum frame duration corresponding to `S`, added with 7277 the maximum stall duration for `S`. 7278 7279 If interleaving requests with and without a stall duration, 7280 a request will stall by the maximum of the remaining times 7281 for each can-stall stream with outstanding buffers. 7282 7283 This means that a stalling request will not have an exposure start 7284 until the stall has completed. 7285 7286 This should correspond to the stall duration when only that stream is 7287 active, with all processing (typically in android.*.mode) set to FAST 7288 or OFF. Setting any of the processing modes to HIGH_QUALITY 7289 effectively results in an indeterminate stall duration for all 7290 streams in a request (the regular stall calculation rules are 7291 ignored). 7292 7293 The following formats may always have a stall duration: 7294 7295 * {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG} 7296 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16} 7297 7298 The following formats will never have a stall duration: 7299 7300 * {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} 7301 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10} 7302 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12} 7303 * {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8} 7304 7305 All other formats may or may not have an allowed stall duration on 7306 a per-capability basis; refer to android.request.availableCapabilities 7307 for more details. 7308 7309 See android.sensor.frameDuration for more information about 7310 calculating the max frame rate (absent stalls). 7311 </details> 7312 <hal_details> 7313 If possible, it is recommended that all non-JPEG formats 7314 (such as RAW16) should not have a stall duration. RAW10, RAW12, RAW_OPAQUE 7315 and IMPLEMENTATION_DEFINED must not have stall durations. 7316 </hal_details> 7317 <tag id="V1" /> 7318 </entry> 7319 <entry name="streamConfigurationMap" type="int32" visibility="java_public" 7320 synthetic="true" typedef="streamConfigurationMap" 7321 hwlevel="legacy"> 7322 <description>The available stream configurations that this 7323 camera device supports; also includes the minimum frame durations 7324 and the stall durations for each format/size combination. 7325 </description> 7326 <details> 7327 All camera devices will support sensor maximum resolution (defined by 7328 android.sensor.info.activeArraySize) for the JPEG format. 7329 7330 For a given use case, the actual maximum supported resolution 7331 may be lower than what is listed here, depending on the destination 7332 Surface for the image data. For example, for recording video, 7333 the video encoder chosen may have a maximum size limit (e.g. 1080p) 7334 smaller than what the camera (e.g. maximum resolution is 3264x2448) 7335 can provide. 7336 7337 Please reference the documentation for the image data destination to 7338 check if it limits the maximum size for image data. 7339 7340 The following table describes the minimum required output stream 7341 configurations based on the hardware level 7342 (android.info.supportedHardwareLevel): 7343 7344 Format | Size | Hardware Level | Notes 7345 :-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------: 7346 {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any | 7347 {@link android.graphics.ImageFormat#JPEG} | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 7348 {@link android.graphics.ImageFormat#JPEG} | 1280x720 (720p) | Any | if 720p <= activeArraySize 7349 {@link android.graphics.ImageFormat#JPEG} | 640x480 (480p) | Any | if 480p <= activeArraySize 7350 {@link android.graphics.ImageFormat#JPEG} | 320x240 (240p) | Any | if 240p <= activeArraySize 7351 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG | FULL | 7352 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG, up to the maximum video size | LIMITED | 7353 {@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any | 7354 7355 Refer to android.request.availableCapabilities and {@link 7356 android.hardware.camera2.CameraDevice#createCaptureSession} for additional mandatory 7357 stream configurations on a per-capability basis. 7358 7359 *1: For JPEG format, the sizes may be restricted by below conditions: 7360 7361 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 7362 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 7363 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 7364 it does not have to be included in the supported JPEG sizes. 7365 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 7366 the dimensions being a multiple of 16. 7367 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 7368 However, the largest JPEG size will be as close as possible to the sensor maximum 7369 resolution given above constraints. It is required that after aspect ratio adjustments, 7370 additional size reduction due to other issues must be less than 3% in area. For example, 7371 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 7372 ratio 4:3, and the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 7373 3264x2448. 7374 7375 Exception on 176x144 (QCIF) resolution: camera devices usually have a fixed capability on 7376 downscaling from larger resolution to smaller ones, and the QCIF resolution can sometimes 7377 not be fully supported due to this limitation on devices with high-resolution image 7378 sensors. Therefore, trying to configure a QCIF resolution stream together with any other 7379 stream larger than 1920x1080 resolution (either width or height) might not be supported, 7380 and capture session creation will fail if it is not. 7381 7382 </details> 7383 <hal_details> 7384 Do not set this property directly 7385 (it is synthetic and will not be available at the HAL layer); 7386 set the android.scaler.availableStreamConfigurations instead. 7387 7388 Not all output formats may be supported in a configuration with 7389 an input stream of a particular format. For more details, see 7390 android.scaler.availableInputOutputFormatsMap. 7391 7392 It is recommended (but not mandatory) to also include half/quarter 7393 of sensor maximum resolution for JPEG formats (regardless of hardware 7394 level). 7395 7396 (The following is a rewording of the above required table): 7397 7398 The HAL must include sensor maximum resolution (defined by 7399 android.sensor.info.activeArraySize). 7400 7401 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 7402 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 7403 here as output streams. 7404 7405 It must also include each below resolution if it is smaller than or 7406 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 7407 formats), as output streams: 7408 7409 * 240p (320 x 240) 7410 * 480p (640 x 480) 7411 * 720p (1280 x 720) 7412 * 1080p (1920 x 1080) 7413 7414 For LIMITED capability devices 7415 (`android.info.supportedHardwareLevel == LIMITED`), 7416 the HAL only has to list up to the maximum video size 7417 supported by the device. 7418 7419 Regardless of hardware level, every output resolution available for 7420 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 7421 7422 This supercedes the following fields, which are now deprecated: 7423 7424 * availableFormats 7425 * available[Processed,Raw,Jpeg]Sizes 7426 </hal_details> 7427 </entry> 7428 <entry name="croppingType" type="byte" visibility="public" enum="true" 7429 hwlevel="legacy"> 7430 <enum> 7431 <value>CENTER_ONLY 7432 <notes> 7433 The camera device only supports centered crop regions. 7434 </notes> 7435 </value> 7436 <value>FREEFORM 7437 <notes> 7438 The camera device supports arbitrarily chosen crop regions. 7439 </notes> 7440 </value> 7441 </enum> 7442 <description>The crop type that this camera device supports.</description> 7443 <details> 7444 When passing a non-centered crop region (android.scaler.cropRegion) to a camera 7445 device that only supports CENTER_ONLY cropping, the camera device will move the 7446 crop region to the center of the sensor active array (android.sensor.info.activeArraySize) 7447 and keep the crop region width and height unchanged. The camera device will return the 7448 final used crop region in metadata result android.scaler.cropRegion. 7449 7450 Camera devices that support FREEFORM cropping will support any crop region that 7451 is inside of the active array. The camera device will apply the same crop region and 7452 return the final used crop region in capture result metadata android.scaler.cropRegion. 7453 7454 Starting from API level 30, 7455 7456 * If the camera device supports FREEFORM cropping, in order to do FREEFORM cropping, the 7457 application must set android.control.zoomRatio to 1.0, and use android.scaler.cropRegion 7458 for zoom. 7459 * To do CENTER_ONLY zoom, the application has below 2 options: 7460 1. Set android.control.zoomRatio to 1.0; adjust zoom by android.scaler.cropRegion. 7461 2. Adjust zoom by android.control.zoomRatio; use android.scaler.cropRegion to crop 7462 the field of view vertically (letterboxing) or horizontally (pillarboxing), but not 7463 windowboxing. 7464 * Setting android.control.zoomRatio to values different than 1.0 and 7465 android.scaler.cropRegion to be windowboxing at the same time are not supported. In this 7466 case, the camera framework will override the android.scaler.cropRegion to be the active 7467 array. 7468 7469 LEGACY capability devices will only support CENTER_ONLY cropping. 7470 </details> 7471 <hal_details> 7472 If the HAL supports android.control.zoomRatio, this tag must be set to CENTER_ONLY. 7473 </hal_details> 7474 </entry> 7475 <entry name="availableRecommendedStreamConfigurations" type="int32" visibility="ndk_public" 7476 optional="true" enum="true" container="array" typedef="recommendedStreamConfiguration" 7477 hal_version="3.4"> 7478 <array> 7479 <size>n</size> 7480 <size>5</size> 7481 </array> 7482 <enum> 7483 <value id="0x0">PREVIEW 7484 <notes> 7485 Preview must only include non-stalling processed stream configurations with 7486 output formats like 7487 {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888}, 7488 {@link android.graphics.ImageFormat#PRIVATE|AIMAGE_FORMAT_PRIVATE}, etc. 7489 </notes> 7490 </value> 7491 <value id="0x1">RECORD 7492 <notes> 7493 Video record must include stream configurations that match the advertised 7494 supported media profiles {@link android.media.CamcorderProfile} with 7495 IMPLEMENTATION_DEFINED format. 7496 </notes> 7497 </value> 7498 <value id="0x2">VIDEO_SNAPSHOT 7499 <notes> 7500 Video snapshot must include stream configurations at least as big as 7501 the maximum RECORD resolutions and only with 7502 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format}. 7503 Additionally the configurations shouldn't cause preview glitches and also be able to 7504 run at 30 fps. 7505 </notes> 7506 </value> 7507 <value id="0x3">SNAPSHOT 7508 <notes> 7509 Recommended snapshot stream configurations must include at least one with 7510 size close to android.sensor.info.activeArraySize and 7511 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format}. 7512 Taking into account restrictions on aspect ratio, alignment etc. the area of the 7513 maximum suggested size shouldn’t be less than 97% of the sensor array size area. 7514 </notes> 7515 </value> 7516 <value id="0x4">ZSL 7517 <notes> 7518 If supported, recommended input stream configurations must only be advertised with 7519 ZSL along with other processed and/or stalling output formats. 7520 </notes> 7521 </value> 7522 <value id="0x5">RAW 7523 <notes> 7524 If supported, recommended raw stream configurations must only include RAW based 7525 output formats. 7526 </notes> 7527 </value> 7528 <value id="0x6">LOW_LATENCY_SNAPSHOT 7529 <notes> 7530 If supported, the recommended low latency stream configurations must have 7531 end-to-end latency that does not exceed 200 ms. under standard operating conditions 7532 (reasonable light levels, not loaded system) and using template 7533 TEMPLATE_STILL_CAPTURE. This is primarily for listing configurations for the 7534 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format} 7535 however other supported output formats can be added as well. 7536 </notes> 7537 </value> 7538 <value id="0x7">PUBLIC_END 7539 </value> 7540 <value id="0x18">VENDOR_START 7541 <notes> 7542 Vendor defined use cases. These depend on the vendor implementation. 7543 </notes> 7544 </value> 7545 </enum> 7546 <description>Recommended stream configurations for common client use cases. 7547 </description> 7548 <details>Optional subset of the android.scaler.availableStreamConfigurations that contains 7549 similar tuples listed as 7550 (i.e. width, height, format, output/input stream, usecase bit field). 7551 Camera devices will be able to suggest particular stream configurations which are 7552 power and performance efficient for specific use cases. For more information about 7553 retrieving the suggestions see 7554 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 7555 </details> 7556 <ndk_details> 7557 The data representation is int[5], which maps to 7558 (width, height, format, output/input stream, usecase bit field). The array can be 7559 parsed using the following pseudo code: 7560 7561 struct StreamConfiguration { 7562 int32_t format; 7563 int32_t width; 7564 int32_t height; 7565 int32_t isInput; }; 7566 7567 void getPreferredStreamConfigurations( 7568 int32_t *array, size_t count, int32_t usecaseId, 7569 Vector < StreamConfiguration > * scs) { 7570 const size_t STREAM_CONFIGURATION_SIZE = 5; 7571 const size_t STREAM_WIDTH_OFFSET = 0; 7572 const size_t STREAM_HEIGHT_OFFSET = 1; 7573 const size_t STREAM_FORMAT_OFFSET = 2; 7574 const size_t STREAM_IS_INPUT_OFFSET = 3; 7575 const size_t STREAM_USECASE_BITMAP_OFFSET = 4; 7576 7577 for (size_t i = 0; i < count; i+= STREAM_CONFIGURATION_SIZE) { 7578 int32_t width = array[i + STREAM_WIDTH_OFFSET]; 7579 int32_t height = array[i + STREAM_HEIGHT_OFFSET]; 7580 int32_t format = array[i + STREAM_FORMAT_OFFSET]; 7581 int32_t isInput = array[i + STREAM_IS_INPUT_OFFSET]; 7582 int32_t supportedUsecases = array[i + STREAM_USECASE_BITMAP_OFFSET]; 7583 if (supportedUsecases & (1 << usecaseId)) { 7584 StreamConfiguration sc = {format, width, height, isInput}; 7585 scs->add(sc); 7586 } 7587 } 7588 } 7589 7590 </ndk_details> 7591 <hal_details> 7592 There are some requirements that need to be considered regarding the usecases and the 7593 suggested configurations: 7594 7595 * If android.scaler.availableRecommendedStreamConfigurations is set, then recommended 7596 stream configurations must be present for all mandatory usecases PREVIEW, 7597 SNAPSHOT, RECORD, VIDEO_SNAPSHOT. ZSL and RAW are 7598 required depending on device capabilities see android.request.availableCapabilities. 7599 * Non-existing usecases and non-vendor usecases within the range 7600 (RAW : VENDOR_START] are prohibited as well as stream configurations not 7601 present in the exhaustive android.scaler.availableStreamConfigurations list. 7602 7603 For example, in case the camera device supports only 4K and 1080p and both resolutions are 7604 recommended for the mandatory usecases except preview which can run efficiently only 7605 on 1080p. The array may look like this: 7606 7607 [3840, 2160, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 7608 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT, 7609 (1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD | 7610 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT | 7611 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT), 7612 7613 1920, 1080, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 7614 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT, 7615 (1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_PREVIEW | 7616 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD | 7617 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT | 7618 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT)] 7619 7620 </hal_details> 7621 </entry> 7622 <entry name="availableRecommendedInputOutputFormatsMap" type="int32" visibility="ndk_public" 7623 optional="true" typedef="reprocessFormatsMap" hal_version="3.4"> 7624 <description>Recommended mappings of image formats that are supported by this 7625 camera device for input streams, to their corresponding output formats. 7626 </description> 7627 <details> 7628 This is a recommended subset of the complete list of mappings found in 7629 android.scaler.availableInputOutputFormatsMap. The same requirements apply here as well. 7630 The list however doesn't need to contain all available and supported mappings. Instead of 7631 this developers must list only recommended and efficient entries. 7632 If set, the information will be available in the ZERO_SHUTTER_LAG recommended stream 7633 configuration see 7634 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 7635 </details> 7636 <hal_details> 7637 For a code sample of the required data encoding please check 7638 android.scaler.availableInputOutputFormatsMap. 7639 </hal_details> 7640 <tag id="REPROC" /> 7641 </entry> 7642 <entry name="mandatoryStreamCombinations" type="int32" visibility="java_public" 7643 synthetic="true" container="array" typedef="mandatoryStreamCombination" hwlevel="limited"> 7644 <array> 7645 <size>n</size> 7646 </array> 7647 <description> 7648 An array of mandatory stream combinations generated according to the camera device 7649 {@link android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 7650 and {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES}. 7651 This is an app-readable conversion of the mandatory stream combination 7652 {@link android.hardware.camera2.CameraDevice#createCaptureSession tables}. 7653 </description> 7654 <details> 7655 The array of 7656 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 7657 generated according to the documented 7658 {@link android.hardware.camera2.CameraDevice#createCaptureSession guideline} based on 7659 specific device level and capabilities. 7660 Clients can use the array as a quick reference to find an appropriate camera stream 7661 combination. 7662 As per documentation, the stream combinations with given PREVIEW, RECORD and 7663 MAXIMUM resolutions and anything smaller from the list given by 7664 {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} are 7665 guaranteed to work. 7666 For a physical camera not independently exposed in 7667 {@link android.hardware.camera2.CameraManager#getCameraIdList}, the mandatory stream 7668 combinations for that physical camera Id are also generated, so that the application can 7669 configure them as physical streams via the logical camera. 7670 The mandatory stream combination array will be {@code null} in case the device is not 7671 backward compatible. 7672 </details> 7673 <hal_details> 7674 Do not set this property directly 7675 (it is synthetic and will not be available at the HAL layer). 7676 </hal_details> 7677 </entry> 7678 <entry name="mandatoryConcurrentStreamCombinations" type="int32" visibility="java_public" 7679 synthetic="true" container="array" typedef="mandatoryStreamCombination"> 7680 <array> 7681 <size>n</size> 7682 </array> 7683 <description> 7684 An array of mandatory concurrent stream combinations. 7685 This is an app-readable conversion of the concurrent mandatory stream combination 7686 {@link android.hardware.camera2.CameraDevice#createCaptureSession tables}. 7687 </description> 7688 <details> 7689 The array of 7690 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 7691 generated according to the documented 7692 {@link android.hardware.camera2.CameraDevice#createCaptureSession guideline} for each 7693 device which has its Id present in the set returned by 7694 {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds}. 7695 Clients can use the array as a quick reference to find an appropriate camera stream 7696 combination. 7697 The mandatory stream combination array will be {@code null} in case the device is not a 7698 part of at least one set of combinations returned by 7699 {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds}. 7700 </details> 7701 <hal_details> 7702 Do not set this property directly 7703 (it is synthetic and will not be available at the HAL layer). 7704 </hal_details> 7705 </entry> 7706 <entry name="availableRotateAndCropModes" type="byte" visibility="public" 7707 type_notes="list of enums" container="array" typedef="enumList" 7708 hal_version="3.5"> 7709 <array> 7710 <size>n</size> 7711 </array> 7712 <description> 7713 List of rotate-and-crop modes for android.scaler.rotateAndCrop that are supported by this camera device. 7714 </description> 7715 <range>Any value listed in android.scaler.rotateAndCrop</range> 7716 <details> 7717 This entry lists the valid modes for android.scaler.rotateAndCrop for this camera device. 7718 7719 Starting with API level 30, all devices will list at least `ROTATE_AND_CROP_NONE`. 7720 Devices with support for rotate-and-crop will additionally list at least 7721 `ROTATE_AND_CROP_AUTO` and `ROTATE_AND_CROP_90`. 7722 </details> 7723 </entry> 7724 </static> 7725 <controls> 7726 <entry name="rotateAndCrop" type="byte" visibility="public" enum="true" 7727 hal_version="3.5"> 7728 <enum> 7729 <value>NONE 7730 <notes>No rotate and crop is applied. Processed outputs are in the sensor orientation. 7731 </notes> 7732 </value> 7733 <value>90 7734 <notes>Processed images are rotated by 90 degrees clockwise, and then cropped 7735 to the original aspect ratio.</notes> 7736 </value> 7737 <value>180 7738 <notes>Processed images are rotated by 180 degrees. Since the aspect ratio does not 7739 change, no cropping is performed.</notes> 7740 </value> 7741 <value>270 7742 <notes>Processed images are rotated by 270 degrees clockwise, and then cropped 7743 to the original aspect ratio.</notes> 7744 </value> 7745 <value>AUTO 7746 <notes>The camera API automatically selects the best concrete value for 7747 rotate-and-crop based on the application's support for resizability and the current 7748 multi-window mode. 7749 7750 If the application does not support resizing but the display mode for its main 7751 Activity is not in a typical orientation, the camera API will set `ROTATE_AND_CROP_90` 7752 or some other supported rotation value, depending on device configuration, 7753 to ensure preview and captured images are correctly shown to the user. Otherwise, 7754 `ROTATE_AND_CROP_NONE` will be selected. 7755 7756 When a value other than NONE is selected, several metadata fields will also be parsed 7757 differently to ensure that coordinates are correctly handled for features like drawing 7758 face detection boxes or passing in tap-to-focus coordinates. The camera API will 7759 convert positions in the active array coordinate system to/from the cropped-and-rotated 7760 coordinate system to make the operation transparent for applications. 7761 7762 No coordinate mapping will be done when the application selects a non-AUTO mode. 7763 </notes> 7764 </value> 7765 </enum> 7766 <description>Whether a rotation-and-crop operation is applied to processed 7767 outputs from the camera.</description> 7768 <range>android.scaler.availableRotateAndCropModes</range> 7769 <details> 7770 This control is primarily intended to help camera applications with no support for 7771 multi-window modes to work correctly on devices where multi-window scenarios are 7772 unavoidable, such as foldables or other devices with variable display geometry or more 7773 free-form window placement (such as laptops, which often place portrait-orientation apps 7774 in landscape with pillarboxing). 7775 7776 If supported, the default value is `ROTATE_AND_CROP_AUTO`, which allows the camera API 7777 to enable backwards-compatibility support for applications that do not support resizing 7778 / multi-window modes, when the device is in fact in a multi-window mode (such as inset 7779 portrait on laptops, or on a foldable device in some fold states). In addition, 7780 `ROTATE_AND_CROP_NONE` and `ROTATE_AND_CROP_90` will always be available if this control 7781 is supported by the device. If not supported, devices API level 30 or higher will always 7782 list only `ROTATE_AND_CROP_NONE`. 7783 7784 When `CROP_AUTO` is in use, and the camera API activates backward-compatibility mode, 7785 several metadata fields will also be parsed differently to ensure that coordinates are 7786 correctly handled for features like drawing face detection boxes or passing in 7787 tap-to-focus coordinates. The camera API will convert positions in the active array 7788 coordinate system to/from the cropped-and-rotated coordinate system to make the 7789 operation transparent for applications. The following controls are affected: 7790 7791 * android.control.aeRegions 7792 * android.control.afRegions 7793 * android.control.awbRegions 7794 * android.statistics.faces 7795 7796 Capture results will contain the actual value selected by the API; 7797 `ROTATE_AND_CROP_AUTO` will never be seen in a capture result. 7798 7799 Applications can also select their preferred cropping mode, either to opt out of the 7800 backwards-compatibility treatment, or to use the cropping feature themselves as needed. 7801 In this case, no coordinate translation will be done automatically, and all controls 7802 will continue to use the normal active array coordinates. 7803 7804 Cropping and rotating is done after the application of digital zoom (via either 7805 android.scaler.cropRegion or android.control.zoomRatio), but before each individual 7806 output is further cropped and scaled. It only affects processed outputs such as 7807 YUV, PRIVATE, and JPEG. It has no effect on RAW outputs. 7808 7809 When `CROP_90` or `CROP_270` are selected, there is a significant loss to the field of 7810 view. For example, with a 4:3 aspect ratio output of 1600x1200, `CROP_90` will still 7811 produce 1600x1200 output, but these buffers are cropped from a vertical 3:4 slice at the 7812 center of the 4:3 area, then rotated to be 4:3, and then upscaled to 1600x1200. Only 7813 56.25% of the original FOV is still visible. In general, for an aspect ratio of `w:h`, 7814 the crop and rotate operation leaves `(h/w)^2` of the field of view visible. For 16:9, 7815 this is ~31.6%. 7816 7817 As a visual example, the figure below shows the effect of `ROTATE_AND_CROP_90` on the 7818 outputs for the following parameters: 7819 7820 * Sensor active array: `2000x1500` 7821 * Crop region: top-left: `(500, 375)`, size: `(1000, 750)` (4:3 aspect ratio) 7822 * Output streams: YUV `640x480` and YUV `1280x720` 7823 * `ROTATE_AND_CROP_90` 7824 7825  7826 7827 With these settings, the regions of the active array covered by the output streams are: 7828 7829 * 640x480 stream crop: top-left: `(219, 375)`, size: `(562, 750)` 7830 * 1280x720 stream crop: top-left: `(289, 375)`, size: `(422, 750)` 7831 7832 Since the buffers are rotated, the buffers as seen by the application are: 7833 7834 * 640x480 stream: top-left: `(781, 375)` on active array, size: `(640, 480)`, downscaled 1.17x from sensor pixels 7835 * 1280x720 stream: top-left: `(711, 375)` on active array, size: `(1280, 720)`, upscaled 1.71x from sensor pixels 7836 </details> 7837 <hal_details> 7838 ROTATE_AND_CROP_AUTO will never be sent to the HAL, though it must be set as the default 7839 value in all the capture request templates by the HAL. The camera service will 7840 translate AUTO to a specific rotation value based on the current application's 7841 multi-window state and its support of resizability. 7842 7843 The HAL also does not need to consider coordinate transforms for ROTATE_AND_CROP - all 7844 capture request and result fields should be kept in the active array coordinate frame. 7845 Any translation required to implement ROTATE_AND_CROP_AUTO will be handled by the camera 7846 service. 7847 </hal_details> 7848 </entry> 7849 </controls> 7850 <dynamic> 7851 <clone entry="android.scaler.rotateAndCrop" kind="controls" hal_version="3.5"> 7852 </clone> 7853 </dynamic> 7854 <static> 7855 <entry name="defaultSecureImageSize" type="int32" visibility="public" 7856 type_notes="width/height for the default secure image data size" container="array" 7857 typedef="size" hal_version="3.6"> 7858 <array> 7859 <size>2</size> 7860 </array> 7861 <description> 7862 Default YUV/PRIVATE size to use for requesting secure image buffers. 7863 </description> 7864 <units>Pixels</units> 7865 <details> 7866 This entry lists the default size supported in the secure camera mode. This entry is 7867 optional on devices support the SECURE_IMAGE_DATA capability. This entry will be null 7868 if the camera device does not list SECURE_IMAGE_DATA capability. 7869 7870 When the key is present, only a PRIVATE/YUV output of the specified size is guaranteed 7871 to be supported by the camera HAL in the secure camera mode. Any other format or 7872 resolutions might not be supported. Use 7873 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported} 7874 API to query if a secure session configuration is supported if the device supports this 7875 API. 7876 7877 If this key returns null on a device with SECURE_IMAGE_DATA capability, the application 7878 can assume all output sizes listed in the 7879 {@link 7880 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 7881 are supported. 7882 </details> 7883 </entry> 7884 <entry name="physicalCameraMultiResolutionStreamConfigurations" type="int32" 7885 visibility="ndk_public" optional="true" enum="true" container="array" 7886 typedef="streamConfiguration" hwlevel="limited" hal_version="3.6"> 7887 <array> 7888 <size>n</size> 7889 <size>4</size> 7890 </array> 7891 <enum> 7892 <value>OUTPUT</value> 7893 <value>INPUT</value> 7894 </enum> 7895 <description>The available multi-resolution stream configurations that this 7896 physical camera device supports 7897 (i.e. format, width, height, output/input stream). 7898 </description> 7899 <details> 7900 This list contains a subset of the parent logical camera's multi-resolution stream 7901 configurations which belong to this physical camera, and it will advertise and will only 7902 advertise the maximum supported resolutions for a particular format. 7903 7904 If this camera device isn't a physical camera device constituting a logical camera, 7905 but a standalone {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 7906 camera, this field represents the multi-resolution input/output stream configurations of 7907 default mode and max resolution modes. The sizes will be the maximum resolution of a 7908 particular format for default mode and max resolution mode. 7909 7910 This field will only be advertised if the device is a physical camera of a 7911 logical multi-camera device or an ultra high resolution sensor camera. For a logical 7912 multi-camera, the camera API will derive the logical camera’s multi-resolution stream 7913 configurations from all physical cameras. For an ultra high resolution sensor camera, this 7914 is used directly as the camera’s multi-resolution stream configurations. 7915 </details> 7916 <hal_details> 7917 If this field contains input stream configurations, and the camera device is a physical 7918 camera (not a standalone ultra-high resolution camera), the 7919 android.logicalMultiCamera.activePhysicalId tag must be set to the physical camera Id in 7920 the physical camera result metadata. This is to make sure during multi-resolution 7921 reprocessing, the camera HAL is notified of which physical camera the reprocessing 7922 request comes from. 7923 </hal_details> 7924 </entry> 7925 <entry name="multiResolutionStreamConfigurationMap" type="int32" visibility="java_public" 7926 synthetic="true" optional="true" typedef="multiResolutionStreamConfigurationMap"> 7927 <description>The multi-resolution stream configurations supported by this logical camera 7928 or ultra high resolution sensor camera device. 7929 </description> 7930 <details> 7931 Multi-resolution streams can be used by a LOGICAL_MULTI_CAMERA or an 7932 ULTRA_HIGH_RESOLUTION_SENSOR camera where the images sent or received can vary in 7933 resolution per frame. This is useful in cases where the camera device's effective full 7934 resolution changes depending on factors such as the current zoom level, lighting 7935 condition, focus distance, or pixel mode. 7936 7937 * For a logical multi-camera implementing optical zoom, at different zoom level, a 7938 different physical camera may be active, resulting in different full-resolution image 7939 sizes. 7940 * For an ultra high resolution camera, depending on whether the camera operates in default 7941 mode, or maximum resolution mode, the output full-size images may be of either binned 7942 resolution or maximum resolution. 7943 7944 To use multi-resolution output streams, the supported formats can be queried by {@link 7945 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputFormats}. 7946 A {@link android.hardware.camera2.MultiResolutionImageReader} can then be created for a 7947 supported format with the MultiResolutionStreamInfo group queried by {@link 7948 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputInfo}. 7949 7950 If a camera device supports multi-resolution output streams for a particular format, for 7951 each of its mandatory stream combinations, the camera device will support using a 7952 MultiResolutionImageReader for the MAXIMUM stream of supported formats. Refer to 7953 {@link android.hardware.camera2.CameraDevice#createCaptureSession} for additional details. 7954 7955 To use multi-resolution input streams, the supported formats can be queried by {@link 7956 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getInputFormats}. 7957 A reprocessable CameraCaptureSession can then be created using an {@link 7958 android.hardware.camera2.params.InputConfiguration InputConfiguration} constructed with 7959 the input MultiResolutionStreamInfo group, queried by {@link 7960 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getInputInfo}. 7961 7962 If a camera device supports multi-resolution {@code YUV} input and multi-resolution 7963 {@code YUV} output, or multi-resolution {@code PRIVATE} input and multi-resolution 7964 {@code PRIVATE} output, {@code JPEG} and {@code YUV} are guaranteed to be supported 7965 multi-resolution output stream formats. Refer to 7966 {@link android.hardware.camera2.CameraDevice#createCaptureSession} for 7967 details about the additional mandatory stream combinations in this case. 7968 </details> 7969 <hal_details> 7970 Do not set this property directly 7971 (it is synthetic and will not be available at the HAL layer). 7972 </hal_details> 7973 </entry> 7974 <entry name="availableStreamConfigurationsMaximumResolution" type="int32" 7975 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 7976 hal_version="3.6"> 7977 <array> 7978 <size>n</size> 7979 <size>4</size> 7980 </array> 7981 <enum> 7982 <value>OUTPUT</value> 7983 <value>INPUT</value> 7984 </enum> 7985 <description>The available stream configurations that this 7986 camera device supports (i.e. format, width, height, output/input stream) for a 7987 CaptureRequest with android.sensor.pixelMode set to 7988 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 7989 </description> 7990 <details> 7991 Analogous to android.scaler.availableStreamConfigurations, for configurations 7992 which are applicable when android.sensor.pixelMode is set to 7993 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 7994 7995 Not all output formats may be supported in a configuration with 7996 an input stream of a particular format. For more details, see 7997 android.scaler.availableInputOutputFormatsMapMaximumResolution. 7998 </details> 7999 <hal_details> 8000 Refer to hal_details for android.scaler.availableStreamConfigurations. 8001 </hal_details> 8002 </entry> 8003 <entry name="availableMinFrameDurationsMaximumResolution" type="int64" visibility="ndk_public" 8004 container="array" typedef="streamConfigurationDuration" hal_version="3.6"> 8005 <array> 8006 <size>4</size> 8007 <size>n</size> 8008 </array> 8009 <description>This lists the minimum frame duration for each 8010 format/size combination when the camera device is sent a CaptureRequest with 8011 android.sensor.pixelMode set to 8012 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8013 </description> 8014 <units>(format, width, height, ns) x n</units> 8015 <details> 8016 Analogous to android.scaler.availableMinFrameDurations, for configurations 8017 which are applicable when android.sensor.pixelMode is set to 8018 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8019 8020 When multiple streams are used in a request (if supported, when android.sensor.pixelMode 8021 is set to 8022 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}), the 8023 minimum frame duration will be max(individual stream min durations). 8024 8025 See android.sensor.frameDuration and 8026 android.scaler.availableStallDurationsMaximumResolution for more details about 8027 calculating the max frame rate. 8028 </details> 8029 </entry> 8030 <entry name="availableStallDurationsMaximumResolution" type="int64" visibility="ndk_public" 8031 container="array" typedef="streamConfigurationDuration" hal_version="3.6"> 8032 <array> 8033 <size>4</size> 8034 <size>n</size> 8035 </array> 8036 <description>This lists the maximum stall duration for each 8037 output format/size combination when CaptureRequests are submitted with 8038 android.sensor.pixelMode set to 8039 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 8040 </description> 8041 <units>(format, width, height, ns) x n</units> 8042 <details> 8043 Analogous to android.scaler.availableMinFrameDurations, for configurations 8044 which are applicable when android.sensor.pixelMode is set to 8045 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8046 </details> 8047 <hal_details> 8048 If possible, it is recommended that all non-JPEG formats 8049 (such as RAW16) should not have a stall duration. RAW10, RAW12, RAW_OPAQUE 8050 and IMPLEMENTATION_DEFINED must not have stall durations. 8051 </hal_details> 8052 </entry> 8053 <entry name="streamConfigurationMapMaximumResolution" type="int32" visibility="java_public" 8054 synthetic="true" typedef="streamConfigurationMap"> 8055 <description>The available stream configurations that this 8056 camera device supports when given a CaptureRequest with android.sensor.pixelMode 8057 set to 8058 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}; 8059 also includes the minimum frame durations 8060 and the stall durations for each format/size combination. 8061 </description> 8062 <details> 8063 Analogous to android.scaler.streamConfigurationMap for CaptureRequests where 8064 android.sensor.pixelMode is 8065 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8066 </details> 8067 <hal_details> 8068 Do not set this property directly 8069 (it is synthetic and will not be available at the HAL layer); 8070 set the android.scaler.availableStreamConfigurationsMaximumResolution instead. 8071 8072 Not all output formats may be supported in a configuration with 8073 an input stream of a particular format. For more details, see 8074 android.scaler.availableInputOutputFormatsMapMaximumResolution. 8075 </hal_details> 8076 </entry> 8077 <entry name="availableInputOutputFormatsMapMaximumResolution" type="int32" 8078 visibility="hidden" typedef="reprocessFormatsMap" hal_version="3.6"> 8079 <description>The mapping of image formats that are supported by this 8080 camera device for input streams, to their corresponding output formats, when 8081 android.sensor.pixelMode is set to 8082 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8083 </description> 8084 <details> 8085 Analogous to android.scaler.availableInputOutputFormatsMap for CaptureRequests where 8086 android.sensor.pixelMode is 8087 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8088 </details> 8089 <hal_details> 8090 Refer to hal details for android.scaler.availableInputOutputFormatsMapMaximumResolution. 8091 </hal_details> 8092 <tag id="REPROC" /> 8093 </entry> 8094 <entry name="mandatoryMaximumResolutionStreamCombinations" type="int32" 8095 visibility="java_public" synthetic="true" container="array" 8096 typedef="mandatoryStreamCombination"> 8097 <array> 8098 <size>n</size> 8099 </array> 8100 <description> 8101 An array of mandatory stream combinations which are applicable when 8102 {@link android.hardware.camera2.CaptureRequest} has android.sensor.pixelMode set 8103 to {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8104 This is an app-readable conversion of the maximum resolution mandatory stream combination 8105 {@link android.hardware.camera2.CameraDevice#createCaptureSession tables}. 8106 </description> 8107 <details> 8108 The array of 8109 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 8110 generated according to the documented 8111 {@link android.hardware.camera2.CameraDevice#createCaptureSession guideline} for each 8112 device which has the 8113 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8114 capability. 8115 Clients can use the array as a quick reference to find an appropriate camera stream 8116 combination. 8117 The mandatory stream combination array will be {@code null} in case the device is not an 8118 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8119 device. 8120 </details> 8121 <hal_details> 8122 Do not set this property directly 8123 (it is synthetic and will not be available at the HAL layer). 8124 </hal_details> 8125 </entry> 8126 <entry name="multiResolutionStreamSupported" type="byte" visibility="ndk_public" enum="true" 8127 typedef="boolean" hwlevel="limited" hal_version="3.6"> 8128 <enum> 8129 <value>FALSE</value> 8130 <value>TRUE</value> 8131 </enum> 8132 <description>Whether the camera device supports multi-resolution input or output streams 8133 </description> 8134 <details> 8135 A logical multi-camera or an ultra high resolution camera may support multi-resolution 8136 input or output streams. With multi-resolution output streams, the camera device is able 8137 to output different resolution images depending on the current active physical camera or 8138 pixel mode. With multi-resolution input streams, the camera device can reprocess images 8139 of different resolutions from different physical cameras or sensor pixel modes. 8140 8141 When set to TRUE: 8142 * For a logical multi-camera, the camera framework derives 8143 android.scaler.multiResolutionStreamConfigurationMap by combining the 8144 android.scaler.physicalCameraMultiResolutionStreamConfigurations from its physical 8145 cameras. 8146 * For an ultra-high resolution sensor camera, the camera framework directly copies 8147 the value of android.scaler.physicalCameraMultiResolutionStreamConfigurations to 8148 android.scaler.multiResolutionStreamConfigurationMap. 8149 </details> 8150 <hal_details> 8151 For the HAL to claim support for multi-resolution streams: 8152 * The HAL must support the buffer management API by setting 8153 supportedBufferManagementVersion to HIDL_DEVICE_3_5. 8154 * For a logical multi-camera, when combined from all its physical cameras, there must be 8155 at a minimum one input or output stream format with at least two different 8156 physicalCameraMultiResolutionStreamConfigurations entries for that format. 8157 * For an ultra high resolution sensor camera, for each supported multi-resolution format, 8158 the physicalCameraMultiResolutionStreamConfigurations must contain both the largest stream 8159 configuration within the android.scaler.streamConfigurationMap and the largest stream 8160 configuration within the android.scaler.streamConfigurationMapMaximumResolution. 8161 * If the HAL advertises multi-resolution input stream support for a particular format 8162 (namely PRIVATE, or YUV), the logical multi-camera or ultra high resolution sensor camera 8163 must have the corresponding reprocessing capabilities (PRIVATE_REPROCESSING, 8164 or YUV_REPROCESSING respectively). The camera HAL must support reprocessing the 8165 multi-resolution input stream to the output formats specified in the camera's 8166 android.scaler.availableInputOutputFormatsMap. 8167 </hal_details> 8168 </entry> 8169 </static> 8170 <controls> 8171 <entry name="cropRegionSet" type="byte" visibility="fwk_only" 8172 enum="true" typedef="boolean"> 8173 <enum> 8174 <value>FALSE 8175 <notes>Crop region (android.scaler.cropRegion) has not been set by the 8176 camera client. 8177 </notes> 8178 </value> 8179 <value>TRUE 8180 <notes> 8181 Scaler crop regions (android.scaler.cropRegion) has been set by the camera 8182 client. 8183 </notes> 8184 </value> 8185 </enum> 8186 <description> 8187 Framework-only private key which informs camera fwk that the scaler crop region 8188 (android.scaler.cropRegion) has been set by the client and it need 8189 not be corrected when android.sensor.pixelMode is set to MAXIMUM_RESOLUTION. 8190 </description> 8191 <details> 8192 This must be set to TRUE by the camera2 java fwk when the camera client sets 8193 android.scaler.cropRegion. 8194 </details> 8195 </entry> 8196 </controls> 8197 </section> 8198 <section name="sensor"> 8199 <controls> 8200 <entry name="exposureTime" type="int64" visibility="public" hwlevel="full"> 8201 <description>Duration each pixel is exposed to 8202 light.</description> 8203 <units>Nanoseconds</units> 8204 <range>android.sensor.info.exposureTimeRange</range> 8205 <details>If the sensor can't expose this exact duration, it will shorten the 8206 duration exposed to the nearest possible value (rather than expose longer). 8207 The final exposure time used will be available in the output capture result. 8208 8209 This control is only effective if android.control.aeMode or android.control.mode is set to 8210 OFF; otherwise the auto-exposure algorithm will override this value. 8211 </details> 8212 <tag id="V1" /> 8213 </entry> 8214 <entry name="frameDuration" type="int64" visibility="public" hwlevel="full"> 8215 <description>Duration from start of frame exposure to 8216 start of next frame exposure.</description> 8217 <units>Nanoseconds</units> 8218 <range>See android.sensor.info.maxFrameDuration, {@link 8219 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. 8220 The duration is capped to `max(duration, exposureTime + overhead)`.</range> 8221 <details> 8222 The maximum frame rate that can be supported by a camera subsystem is 8223 a function of many factors: 8224 8225 * Requested resolutions of output image streams 8226 * Availability of binning / skipping modes on the imager 8227 * The bandwidth of the imager interface 8228 * The bandwidth of the various ISP processing blocks 8229 8230 Since these factors can vary greatly between different ISPs and 8231 sensors, the camera abstraction tries to represent the bandwidth 8232 restrictions with as simple a model as possible. 8233 8234 The model presented has the following characteristics: 8235 8236 * The image sensor is always configured to output the smallest 8237 resolution possible given the application's requested output stream 8238 sizes. The smallest resolution is defined as being at least as large 8239 as the largest requested output stream size; the camera pipeline must 8240 never digitally upsample sensor data when the crop region covers the 8241 whole sensor. In general, this means that if only small output stream 8242 resolutions are configured, the sensor can provide a higher frame 8243 rate. 8244 * Since any request may use any or all the currently configured 8245 output streams, the sensor and ISP must be configured to support 8246 scaling a single capture to all the streams at the same time. This 8247 means the camera pipeline must be ready to produce the largest 8248 requested output size without any delay. Therefore, the overall 8249 frame rate of a given configured stream set is governed only by the 8250 largest requested stream resolution. 8251 * Using more than one output stream in a request does not affect the 8252 frame duration. 8253 * Certain format-streams may need to do additional background processing 8254 before data is consumed/produced by that stream. These processors 8255 can run concurrently to the rest of the camera pipeline, but 8256 cannot process more than 1 capture at a time. 8257 8258 The necessary information for the application, given the model above, is provided via 8259 {@link 8260 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. 8261 These are used to determine the maximum frame rate / minimum frame duration that is 8262 possible for a given stream configuration. 8263 8264 Specifically, the application can use the following rules to 8265 determine the minimum frame duration it can request from the camera 8266 device: 8267 8268 1. Let the set of currently configured input/output streams be called `S`. 8269 1. Find the minimum frame durations for each stream in `S`, by looking it up in {@link 8270 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 8271 (with its respective size/format). Let this set of frame durations be called `F`. 8272 1. For any given request `R`, the minimum frame duration allowed for `R` is the maximum 8273 out of all values in `F`. Let the streams used in `R` be called `S_r`. 8274 8275 If none of the streams in `S_r` have a stall time (listed in {@link 8276 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_SCALER_AVAILABLE_STALL_DURATIONS} 8277 using its respective size/format), then the frame duration in `F` determines the steady 8278 state frame rate that the application will get if it uses `R` as a repeating request. Let 8279 this special kind of request be called `Rsimple`. 8280 8281 A repeating request `Rsimple` can be _occasionally_ interleaved by a single capture of a 8282 new request `Rstall` (which has at least one in-use stream with a non-0 stall time) and if 8283 `Rstall` has the same minimum frame duration this will not cause a frame rate loss if all 8284 buffers from the previous `Rstall` have already been delivered. 8285 8286 For more details about stalling, see {@link 8287 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_SCALER_AVAILABLE_STALL_DURATIONS}. 8288 8289 This control is only effective if android.control.aeMode or android.control.mode is set to 8290 OFF; otherwise the auto-exposure algorithm will override this value. 8291 </details> 8292 <hal_details> 8293 For more details about stalling, see 8294 android.scaler.availableStallDurations. 8295 </hal_details> 8296 <tag id="V1" /> 8297 </entry> 8298 <entry name="sensitivity" type="int32" visibility="public" hwlevel="full"> 8299 <description>The amount of gain applied to sensor data 8300 before processing.</description> 8301 <units>ISO arithmetic units</units> 8302 <range>android.sensor.info.sensitivityRange</range> 8303 <details> 8304 The sensitivity is the standard ISO sensitivity value, 8305 as defined in ISO 12232:2006. 8306 8307 The sensitivity must be within android.sensor.info.sensitivityRange, and 8308 if if it less than android.sensor.maxAnalogSensitivity, the camera device 8309 is guaranteed to use only analog amplification for applying the gain. 8310 8311 If the camera device cannot apply the exact sensitivity 8312 requested, it will reduce the gain to the nearest supported 8313 value. The final sensitivity used will be available in the 8314 output capture result. 8315 8316 This control is only effective if android.control.aeMode or android.control.mode is set to 8317 OFF; otherwise the auto-exposure algorithm will override this value. 8318 8319 Note that for devices supporting postRawSensitivityBoost, the total sensitivity applied 8320 to the final processed image is the combination of android.sensor.sensitivity and 8321 android.control.postRawSensitivityBoost. In case the application uses the sensor 8322 sensitivity from last capture result of an auto request for a manual request, in order 8323 to achieve the same brightness in the output image, the application should also 8324 set postRawSensitivityBoost. 8325 </details> 8326 <hal_details>ISO 12232:2006 REI method is acceptable.</hal_details> 8327 <tag id="V1" /> 8328 </entry> 8329 </controls> 8330 <static> 8331 <namespace name="info"> 8332 <entry name="activeArraySize" type="int32" visibility="public" 8333 type_notes="Four ints defining the active pixel rectangle" 8334 container="array" typedef="rectangle" hwlevel="legacy"> 8335 <array> 8336 <size>4</size> 8337 </array> 8338 <description> 8339 The area of the image sensor which corresponds to active pixels after any geometric 8340 distortion correction has been applied. 8341 </description> 8342 <units>Pixel coordinates on the image sensor</units> 8343 <details> 8344 This is the rectangle representing the size of the active region of the sensor (i.e. 8345 the region that actually receives light from the scene) after any geometric correction 8346 has been applied, and should be treated as the maximum size in pixels of any of the 8347 image output formats aside from the raw formats. 8348 8349 This rectangle is defined relative to the full pixel array; (0,0) is the top-left of 8350 the full pixel array, and the size of the full pixel array is given by 8351 android.sensor.info.pixelArraySize. 8352 8353 The coordinate system for most other keys that list pixel coordinates, including 8354 android.scaler.cropRegion, is defined relative to the active array rectangle given in 8355 this field, with `(0, 0)` being the top-left of this rectangle. 8356 8357 The active array may be smaller than the full pixel array, since the full array may 8358 include black calibration pixels or other inactive regions. 8359 8360 For devices that do not support android.distortionCorrection.mode control, the active 8361 array must be the same as android.sensor.info.preCorrectionActiveArraySize. 8362 8363 For devices that support android.distortionCorrection.mode control, the active array must 8364 be enclosed by android.sensor.info.preCorrectionActiveArraySize. The difference between 8365 pre-correction active array and active array accounts for scaling or cropping caused 8366 by lens geometric distortion correction. 8367 8368 In general, application should always refer to active array size for controls like 8369 metering regions or crop region. Two exceptions are when the application is dealing with 8370 RAW image buffers (RAW_SENSOR, RAW10, RAW12 etc), or when application explicitly set 8371 android.distortionCorrection.mode to OFF. In these cases, application should refer 8372 to android.sensor.info.preCorrectionActiveArraySize. 8373 </details> 8374 <ndk_details> 8375 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 8376 </ndk_details> 8377 <hal_details> 8378 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 8379 &gt;= `(0,0)`. 8380 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 8381 </hal_details> 8382 <tag id="RAW" /> 8383 </entry> 8384 <entry name="sensitivityRange" type="int32" visibility="public" 8385 type_notes="Range of supported sensitivities" 8386 container="array" typedef="rangeInt" 8387 hwlevel="full"> 8388 <array> 8389 <size>2</size> 8390 </array> 8391 <description>Range of sensitivities for android.sensor.sensitivity supported by this 8392 camera device.</description> 8393 <range>Min <= 100, Max &gt;= 800</range> 8394 <details> 8395 The values are the standard ISO sensitivity values, 8396 as defined in ISO 12232:2006. 8397 </details> 8398 8399 <tag id="BC" /> 8400 <tag id="V1" /> 8401 </entry> 8402 <entry name="colorFilterArrangement" type="byte" visibility="public" enum="true" 8403 hwlevel="full"> 8404 <enum> 8405 <value>RGGB</value> 8406 <value>GRBG</value> 8407 <value>GBRG</value> 8408 <value>BGGR</value> 8409 <value>RGB 8410 <notes>Sensor is not Bayer; output has 3 16-bit 8411 values for each pixel, instead of just 1 16-bit value 8412 per pixel.</notes></value> 8413 <value hal_version="3.4">MONO 8414 <notes>Sensor doesn't have any Bayer color filter. 8415 Such sensor captures visible light in monochrome. The exact weighting and 8416 wavelengths captured is not specified, but generally only includes the visible 8417 frequencies. This value implies a MONOCHROME camera.</notes></value> 8418 <value hal_version="3.4">NIR 8419 <notes>Sensor has a near infrared filter capturing light with wavelength between 8420 roughly 750nm and 1400nm, and the same filter covers the whole sensor array. This 8421 value implies a MONOCHROME camera.</notes></value> 8422 </enum> 8423 <description>The arrangement of color filters on sensor; 8424 represents the colors in the top-left 2x2 section of 8425 the sensor, in reading order, for a Bayer camera, or the 8426 light spectrum it captures for MONOCHROME camera. 8427 </description> 8428 <hal_details> 8429 Starting from Android Q, the colorFilterArrangement for a MONOCHROME camera must be 8430 single color patterns, such as MONO or NIR. 8431 </hal_details> 8432 <tag id="RAW" /> 8433 </entry> 8434 <entry name="exposureTimeRange" type="int64" visibility="public" 8435 type_notes="nanoseconds" container="array" typedef="rangeLong" 8436 hwlevel="full"> 8437 <array> 8438 <size>2</size> 8439 </array> 8440 <description>The range of image exposure times for android.sensor.exposureTime supported 8441 by this camera device. 8442 </description> 8443 <units>Nanoseconds</units> 8444 <range>The minimum exposure time will be less than 100 us. For FULL 8445 capability devices (android.info.supportedHardwareLevel == FULL), 8446 the maximum exposure time will be greater than 100ms.</range> 8447 <hal_details>For FULL capability devices (android.info.supportedHardwareLevel == FULL), 8448 The maximum of the range SHOULD be at least 1 second (1e9), MUST be at least 8449 100ms. 8450 </hal_details> 8451 <tag id="V1" /> 8452 </entry> 8453 <entry name="maxFrameDuration" type="int64" visibility="public" 8454 hwlevel="full"> 8455 <description>The maximum possible frame duration (minimum frame rate) for 8456 android.sensor.frameDuration that is supported this camera device.</description> 8457 <units>Nanoseconds</units> 8458 <range>For FULL capability devices 8459 (android.info.supportedHardwareLevel == FULL), at least 100ms. 8460 </range> 8461 <details>Attempting to use frame durations beyond the maximum will result in the frame 8462 duration being clipped to the maximum. See that control for a full definition of frame 8463 durations. 8464 8465 Refer to {@link 8466 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 8467 for the minimum frame duration values. 8468 </details> 8469 <hal_details> 8470 For FULL capability devices (android.info.supportedHardwareLevel == FULL), 8471 The maximum of the range SHOULD be at least 8472 1 second (1e9), MUST be at least 100ms (100e6). 8473 8474 android.sensor.info.maxFrameDuration must be greater or 8475 equal to the android.sensor.info.exposureTimeRange max 8476 value (since exposure time overrides frame duration). 8477 8478 Available minimum frame durations for JPEG must be no greater 8479 than that of the YUV_420_888/IMPLEMENTATION_DEFINED 8480 minimum frame durations (for that respective size). 8481 8482 Since JPEG processing is considered offline and can take longer than 8483 a single uncompressed capture, refer to 8484 android.scaler.availableStallDurations 8485 for details about encoding this scenario. 8486 </hal_details> 8487 <tag id="V1" /> 8488 </entry> 8489 <entry name="physicalSize" type="float" visibility="public" 8490 type_notes="width x height" 8491 container="array" typedef="sizeF" hwlevel="legacy"> 8492 <array> 8493 <size>2</size> 8494 </array> 8495 <description>The physical dimensions of the full pixel 8496 array.</description> 8497 <units>Millimeters</units> 8498 <details>This is the physical size of the sensor pixel 8499 array defined by android.sensor.info.pixelArraySize. 8500 </details> 8501 <hal_details>Needed for FOV calculation for old API</hal_details> 8502 <tag id="V1" /> 8503 <tag id="BC" /> 8504 </entry> 8505 <entry name="pixelArraySize" type="int32" visibility="public" 8506 container="array" typedef="size" hwlevel="legacy"> 8507 <array> 8508 <size>2</size> 8509 </array> 8510 <description>Dimensions of the full pixel array, possibly 8511 including black calibration pixels.</description> 8512 <units>Pixels</units> 8513 <details>The pixel count of the full pixel array of the image sensor, which covers 8514 android.sensor.info.physicalSize area. This represents the full pixel dimensions of 8515 the raw buffers produced by this sensor. 8516 8517 If a camera device supports raw sensor formats, either this or 8518 android.sensor.info.preCorrectionActiveArraySize is the maximum dimensions for the raw 8519 output formats listed in {@link 8520 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 8521 (this depends on whether or not the image sensor returns buffers containing pixels that 8522 are not part of the active array region for blacklevel calibration or other purposes). 8523 8524 Some parts of the full pixel array may not receive light from the scene, 8525 or be otherwise inactive. The android.sensor.info.preCorrectionActiveArraySize key 8526 defines the rectangle of active pixels that will be included in processed image 8527 formats. 8528 </details> 8529 <tag id="RAW" /> 8530 <tag id="BC" /> 8531 </entry> 8532 <entry name="whiteLevel" type="int32" visibility="public"> 8533 <description> 8534 Maximum raw value output by sensor. 8535 </description> 8536 <range>&gt; 255 (8-bit output)</range> 8537 <details> 8538 This specifies the fully-saturated encoding level for the raw 8539 sample values from the sensor. This is typically caused by the 8540 sensor becoming highly non-linear or clipping. The minimum for 8541 each channel is specified by the offset in the 8542 android.sensor.blackLevelPattern key. 8543 8544 The white level is typically determined either by sensor bit depth 8545 (8-14 bits is expected), or by the point where the sensor response 8546 becomes too non-linear to be useful. The default value for this is 8547 maximum representable value for a 16-bit raw sample (2^16 - 1). 8548 8549 The white level values of captured images may vary for different 8550 capture settings (e.g., android.sensor.sensitivity). This key 8551 represents a coarse approximation for such case. It is recommended 8552 to use android.sensor.dynamicWhiteLevel for captures when supported 8553 by the camera device, which provides more accurate white level values. 8554 </details> 8555 <hal_details> 8556 The full bit depth of the sensor must be available in the raw data, 8557 so the value for linear sensors should not be significantly lower 8558 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 8559 </hal_details> 8560 <tag id="RAW" /> 8561 </entry> 8562 <entry name="timestampSource" type="byte" visibility="public" 8563 enum="true" hwlevel="legacy"> 8564 <enum> 8565 <value>UNKNOWN 8566 <notes> 8567 Timestamps from android.sensor.timestamp are in nanoseconds and monotonic, but can 8568 not be compared to timestamps from other subsystems (e.g. accelerometer, gyro etc.), 8569 or other instances of the same or different camera devices in the same system with 8570 accuracy. However, the timestamps are roughly in the same timebase as 8571 {@link android.os.SystemClock#uptimeMillis}. The accuracy is sufficient for tasks 8572 like A/V synchronization for video recording, at least, and the timestamps can be 8573 directly used together with timestamps from the audio subsystem for that task. 8574 8575 Timestamps between streams and results for a single camera instance are comparable, 8576 and the timestamps for all buffers and the result metadata generated by a single 8577 capture are identical. 8578 </notes> 8579 </value> 8580 <value>REALTIME 8581 <notes> 8582 Timestamps from android.sensor.timestamp are in the same timebase as 8583 {@link android.os.SystemClock#elapsedRealtimeNanos}, 8584 and they can be compared to other timestamps using that base. 8585 8586 When buffers from a REALTIME device are passed directly to a video encoder from the 8587 camera, automatic compensation is done to account for differing timebases of the 8588 audio and camera subsystems. If the application is receiving buffers and then later 8589 sending them to a video encoder or other application where they are compared with 8590 audio subsystem timestamps or similar, this compensation is not present. In those 8591 cases, applications need to adjust the timestamps themselves. Since {@link 8592 android.os.SystemClock#elapsedRealtimeNanos} and {@link 8593 android.os.SystemClock#uptimeMillis} only diverge while the device is asleep, an 8594 offset between the two sources can be measured once per active session and applied 8595 to timestamps for sufficient accuracy for A/V sync. 8596 </notes> 8597 </value> 8598 </enum> 8599 <description>The time base source for sensor capture start timestamps.</description> 8600 <details> 8601 The timestamps provided for captures are always in nanoseconds and monotonic, but 8602 may not based on a time source that can be compared to other system time sources. 8603 8604 This characteristic defines the source for the timestamps, and therefore whether they 8605 can be compared against other system time sources/timestamps. 8606 </details> 8607 <hal_details> 8608 For camera devices implement UNKNOWN, the camera framework expects that the timestamp 8609 source to be SYSTEM_TIME_MONOTONIC. For camera devices implement REALTIME, the camera 8610 framework expects that the timestamp source to be SYSTEM_TIME_BOOTTIME. See 8611 system/core/include/utils/Timers.h for the definition of SYSTEM_TIME_MONOTONIC and 8612 SYSTEM_TIME_BOOTTIME. Note that HAL must follow above expectation; otherwise video 8613 recording might suffer unexpected behavior. 8614 8615 Also, camera devices which implement REALTIME must pass the ITS sensor fusion test which 8616 tests the alignment between camera timestamps and gyro sensor timestamps. 8617 </hal_details> 8618 <tag id="V1" /> 8619 </entry> 8620 <entry name="lensShadingApplied" type="byte" visibility="public" enum="true" 8621 typedef="boolean"> 8622 <enum> 8623 <value>FALSE</value> 8624 <value>TRUE</value> 8625 </enum> 8626 <description>Whether the RAW images output from this camera device are subject to 8627 lens shading correction.</description> 8628 <details> 8629 If TRUE, all images produced by the camera device in the RAW image formats will 8630 have lens shading correction already applied to it. If FALSE, the images will 8631 not be adjusted for lens shading correction. 8632 See android.request.maxNumOutputRaw for a list of RAW image formats. 8633 8634 This key will be `null` for all devices do not report this information. 8635 Devices with RAW capability will always report this information in this key. 8636 </details> 8637 </entry> 8638 <entry name="preCorrectionActiveArraySize" type="int32" visibility="public" 8639 type_notes="Four ints defining the active pixel rectangle" container="array" 8640 typedef="rectangle" hwlevel="legacy"> 8641 <array> 8642 <size>4</size> 8643 </array> 8644 <description> 8645 The area of the image sensor which corresponds to active pixels prior to the 8646 application of any geometric distortion correction. 8647 </description> 8648 <units>Pixel coordinates on the image sensor</units> 8649 <details> 8650 This is the rectangle representing the size of the active region of the sensor (i.e. 8651 the region that actually receives light from the scene) before any geometric correction 8652 has been applied, and should be treated as the active region rectangle for any of the 8653 raw formats. All metadata associated with raw processing (e.g. the lens shading 8654 correction map, and radial distortion fields) treats the top, left of this rectangle as 8655 the origin, (0,0). 8656 8657 The size of this region determines the maximum field of view and the maximum number of 8658 pixels that an image from this sensor can contain, prior to the application of 8659 geometric distortion correction. The effective maximum pixel dimensions of a 8660 post-distortion-corrected image is given by the android.sensor.info.activeArraySize 8661 field, and the effective maximum field of view for a post-distortion-corrected image 8662 can be calculated by applying the geometric distortion correction fields to this 8663 rectangle, and cropping to the rectangle given in android.sensor.info.activeArraySize. 8664 8665 E.g. to calculate position of a pixel, (x,y), in a processed YUV output image with the 8666 dimensions in android.sensor.info.activeArraySize given the position of a pixel, 8667 (x', y'), in the raw pixel array with dimensions given in 8668 android.sensor.info.pixelArraySize: 8669 8670 1. Choose a pixel (x', y') within the active array region of the raw buffer given in 8671 android.sensor.info.preCorrectionActiveArraySize, otherwise this pixel is considered 8672 to be outside of the FOV, and will not be shown in the processed output image. 8673 1. Apply geometric distortion correction to get the post-distortion pixel coordinate, 8674 (x_i, y_i). When applying geometric correction metadata, note that metadata for raw 8675 buffers is defined relative to the top, left of the 8676 android.sensor.info.preCorrectionActiveArraySize rectangle. 8677 1. If the resulting corrected pixel coordinate is within the region given in 8678 android.sensor.info.activeArraySize, then the position of this pixel in the 8679 processed output image buffer is `(x_i - activeArray.left, y_i - activeArray.top)`, 8680 when the top, left coordinate of that buffer is treated as (0, 0). 8681 8682 Thus, for pixel x',y' = (25, 25) on a sensor where android.sensor.info.pixelArraySize 8683 is (100,100), android.sensor.info.preCorrectionActiveArraySize is (10, 10, 100, 100), 8684 android.sensor.info.activeArraySize is (20, 20, 80, 80), and the geometric distortion 8685 correction doesn't change the pixel coordinate, the resulting pixel selected in 8686 pixel coordinates would be x,y = (25, 25) relative to the top,left of the raw buffer 8687 with dimensions given in android.sensor.info.pixelArraySize, and would be (5, 5) 8688 relative to the top,left of post-processed YUV output buffer with dimensions given in 8689 android.sensor.info.activeArraySize. 8690 8691 The currently supported fields that correct for geometric distortion are: 8692 8693 1. android.lens.distortion. 8694 8695 If the camera device doesn't support geometric distortion correction, or all of the 8696 geometric distortion fields are no-ops, this rectangle will be the same as the 8697 post-distortion-corrected rectangle given in android.sensor.info.activeArraySize. 8698 8699 This rectangle is defined relative to the full pixel array; (0,0) is the top-left of 8700 the full pixel array, and the size of the full pixel array is given by 8701 android.sensor.info.pixelArraySize. 8702 8703 The pre-correction active array may be smaller than the full pixel array, since the 8704 full array may include black calibration pixels or other inactive regions. 8705 </details> 8706 <ndk_details> 8707 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 8708 </ndk_details> 8709 <hal_details> 8710 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 8711 &gt;= `(0,0)`. 8712 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 8713 8714 If omitted by the HAL implementation, the camera framework will assume that this is 8715 the same as the post-correction active array region given in 8716 android.sensor.info.activeArraySize. 8717 </hal_details> 8718 <tag id="RAW" /> 8719 </entry> 8720 <entry name="activeArraySizeMaximumResolution" type="int32" visibility="public" 8721 type_notes="Four ints defining the active pixel rectangle" 8722 container="array" typedef="rectangle" hal_version="3.6"> 8723 <array> 8724 <size>4</size> 8725 </array> 8726 <description> 8727 The area of the image sensor which corresponds to active pixels after any geometric 8728 distortion correction has been applied, when the sensor runs in maximum resolution mode. 8729 </description> 8730 <units>Pixel coordinates on the image sensor</units> 8731 <details> 8732 Analogous to android.sensor.info.activeArraySize, when android.sensor.pixelMode 8733 is set to 8734 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8735 Refer to android.sensor.info.activeArraySize for details, with sensor array related keys 8736 replaced with their 8737 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 8738 counterparts. 8739 This key will only be present for devices which advertise the 8740 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8741 capability. 8742 </details> 8743 <ndk_details> 8744 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 8745 </ndk_details> 8746 <hal_details> 8747 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 8748 &gt;= `(0,0)`. 8749 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySizeMaximumResolution`. 8750 </hal_details> 8751 <tag id="RAW" /> 8752 </entry> 8753 <entry name="pixelArraySizeMaximumResolution" type="int32" visibility="public" 8754 container="array" typedef="size" hal_version="3.6"> 8755 <array> 8756 <size>2</size> 8757 </array> 8758 <description>Dimensions of the full pixel array, possibly 8759 including black calibration pixels, when the sensor runs in maximum resolution mode. 8760 Analogous to android.sensor.info.pixelArraySize, when android.sensor.pixelMode is 8761 set to 8762 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8763 </description> 8764 <units>Pixels</units> 8765 <details> 8766 The pixel count of the full pixel array of the image sensor, which covers 8767 android.sensor.info.physicalSize area. This represents the full pixel dimensions of 8768 the raw buffers produced by this sensor, when it runs in maximum resolution mode. That 8769 is, when android.sensor.pixelMode is set to 8770 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8771 This key will only be present for devices which advertise the 8772 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8773 capability. 8774 </details> 8775 <tag id="RAW" /> 8776 </entry> 8777 <entry name="preCorrectionActiveArraySizeMaximumResolution" type="int32" 8778 visibility="public" type_notes="Four ints defining the active pixel rectangle" 8779 container="array" typedef="rectangle" hal_version="3.6"> 8780 <array> 8781 <size>4</size> 8782 </array> 8783 <description> 8784 The area of the image sensor which corresponds to active pixels prior to the 8785 application of any geometric distortion correction, when the sensor runs in maximum 8786 resolution mode. This key must be used for crop / metering regions, only when 8787 android.sensor.pixelMode is set to 8788 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8789 </description> 8790 <units>Pixel coordinates on the image sensor</units> 8791 <details> 8792 Analogous to android.sensor.info.preCorrectionActiveArraySize, 8793 when android.sensor.pixelMode is set to 8794 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 8795 This key will only be present for devices which advertise the 8796 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8797 capability. 8798 </details> 8799 <ndk_details> 8800 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 8801 </ndk_details> 8802 <hal_details> 8803 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 8804 &gt;= `(0,0)`. 8805 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySizeMaximumResolution`. 8806 8807 If omitted by the HAL implementation, the camera framework will assume that this is 8808 the same as the post-correction active array region given in 8809 android.sensor.info.activeArraySizeMaximumResolution. 8810 </hal_details> 8811 <tag id="RAW" /> 8812 </entry> 8813 <entry name="binningFactor" type="int32" visibility="public" 8814 container="array" typedef="size" hal_version="3.6"> 8815 <array> 8816 <size>2</size> 8817 </array> 8818 <description> Dimensions of the group of pixels which are under the same color filter. 8819 This specifies the width and height (pair of integers) of the group of pixels which fall 8820 under the same color filter for ULTRA_HIGH_RESOLUTION sensors. 8821 </description> 8822 <units>Pixels</units> 8823 <details> Sensors can have pixels grouped together under the same color filter in order 8824 to improve various aspects of imaging such as noise reduction, low light 8825 performance etc. These groups can be of various sizes such as 2X2 (quad bayer), 8826 3X3 (nona-bayer). This key specifies the length and width of the pixels grouped under 8827 the same color filter. 8828 8829 This key will not be present if REMOSAIC_REPROCESSING is not supported, since RAW images 8830 will have a regular bayer pattern. 8831 8832 This key will not be present for sensors which don't have the 8833 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8834 capability. 8835 </details> 8836 </entry> 8837 </namespace> 8838 <entry name="referenceIlluminant1" type="byte" visibility="public" 8839 enum="true" permission_needed="true" > 8840 <enum> 8841 <value id="1">DAYLIGHT</value> 8842 <value id="2">FLUORESCENT</value> 8843 <value id="3">TUNGSTEN 8844 <notes>Incandescent light</notes> 8845 </value> 8846 <value id="4">FLASH</value> 8847 <value id="9">FINE_WEATHER</value> 8848 <value id="10">CLOUDY_WEATHER</value> 8849 <value id="11">SHADE</value> 8850 <value id="12">DAYLIGHT_FLUORESCENT 8851 <notes>D 5700 - 7100K</notes> 8852 </value> 8853 <value id="13">DAY_WHITE_FLUORESCENT 8854 <notes>N 4600 - 5400K</notes> 8855 </value> 8856 <value id="14">COOL_WHITE_FLUORESCENT 8857 <notes>W 3900 - 4500K</notes> 8858 </value> 8859 <value id="15">WHITE_FLUORESCENT 8860 <notes>WW 3200 - 3700K</notes> 8861 </value> 8862 <value id="17">STANDARD_A</value> 8863 <value id="18">STANDARD_B</value> 8864 <value id="19">STANDARD_C</value> 8865 <value id="20">D55</value> 8866 <value id="21">D65</value> 8867 <value id="22">D75</value> 8868 <value id="23">D50</value> 8869 <value id="24">ISO_STUDIO_TUNGSTEN</value> 8870 </enum> 8871 <description> 8872 The standard reference illuminant used as the scene light source when 8873 calculating the android.sensor.colorTransform1, 8874 android.sensor.calibrationTransform1, and 8875 android.sensor.forwardMatrix1 matrices. 8876 </description> 8877 <details> 8878 The values in this key correspond to the values defined for the 8879 EXIF LightSource tag. These illuminants are standard light sources 8880 that are often used calibrating camera devices. 8881 8882 If this key is present, then android.sensor.colorTransform1, 8883 android.sensor.calibrationTransform1, and 8884 android.sensor.forwardMatrix1 will also be present. 8885 8886 Some devices may choose to provide a second set of calibration 8887 information for improved quality, including 8888 android.sensor.referenceIlluminant2 and its corresponding matrices. 8889 8890 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 8891 the camera device has RAW capability. 8892 </details> 8893 <hal_details> 8894 The first reference illuminant (android.sensor.referenceIlluminant1) 8895 and corresponding matrices must be present to support the RAW capability 8896 and DNG output. 8897 8898 When producing raw images with a color profile that has only been 8899 calibrated against a single light source, it is valid to omit 8900 android.sensor.referenceIlluminant2 along with the 8901 android.sensor.colorTransform2, android.sensor.calibrationTransform2, 8902 and android.sensor.forwardMatrix2 matrices. 8903 8904 If only android.sensor.referenceIlluminant1 is included, it should be 8905 chosen so that it is representative of typical scene lighting. In 8906 general, D50 or DAYLIGHT will be chosen for this case. 8907 8908 If both android.sensor.referenceIlluminant1 and 8909 android.sensor.referenceIlluminant2 are included, they should be 8910 chosen to represent the typical range of scene lighting conditions. 8911 In general, low color temperature illuminant such as Standard-A will 8912 be chosen for the first reference illuminant and a higher color 8913 temperature illuminant such as D65 will be chosen for the second 8914 reference illuminant. 8915 </hal_details> 8916 <tag id="RAW" /> 8917 </entry> 8918 <entry name="referenceIlluminant2" type="byte" visibility="public" 8919 permission_needed="true" > 8920 <description> 8921 The standard reference illuminant used as the scene light source when 8922 calculating the android.sensor.colorTransform2, 8923 android.sensor.calibrationTransform2, and 8924 android.sensor.forwardMatrix2 matrices. 8925 </description> 8926 <range>Any value listed in android.sensor.referenceIlluminant1</range> 8927 <details> 8928 See android.sensor.referenceIlluminant1 for more details. 8929 8930 If this key is present, then android.sensor.colorTransform2, 8931 android.sensor.calibrationTransform2, and 8932 android.sensor.forwardMatrix2 will also be present. 8933 8934 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 8935 the camera device has RAW capability. 8936 </details> 8937 <tag id="RAW" /> 8938 </entry> 8939 <entry name="calibrationTransform1" type="rational" 8940 visibility="public" optional="true" 8941 type_notes="3x3 matrix in row-major-order" container="array" 8942 typedef="colorSpaceTransform" permission_needed="true" > 8943 <array> 8944 <size>3</size> 8945 <size>3</size> 8946 </array> 8947 <description> 8948 A per-device calibration transform matrix that maps from the 8949 reference sensor colorspace to the actual device sensor colorspace. 8950 </description> 8951 <details> 8952 This matrix is used to correct for per-device variations in the 8953 sensor colorspace, and is used for processing raw buffer data. 8954 8955 The matrix is expressed as a 3x3 matrix in row-major-order, and 8956 contains a per-device calibration transform that maps colors 8957 from reference sensor color space (i.e. the "golden module" 8958 colorspace) into this camera device's native sensor color 8959 space under the first reference illuminant 8960 (android.sensor.referenceIlluminant1). 8961 8962 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 8963 the camera device has RAW capability. 8964 </details> 8965 <tag id="RAW" /> 8966 </entry> 8967 <entry name="calibrationTransform2" type="rational" 8968 visibility="public" optional="true" 8969 type_notes="3x3 matrix in row-major-order" container="array" 8970 typedef="colorSpaceTransform" permission_needed="true" > 8971 <array> 8972 <size>3</size> 8973 <size>3</size> 8974 </array> 8975 <description> 8976 A per-device calibration transform matrix that maps from the 8977 reference sensor colorspace to the actual device sensor colorspace 8978 (this is the colorspace of the raw buffer data). 8979 </description> 8980 <details> 8981 This matrix is used to correct for per-device variations in the 8982 sensor colorspace, and is used for processing raw buffer data. 8983 8984 The matrix is expressed as a 3x3 matrix in row-major-order, and 8985 contains a per-device calibration transform that maps colors 8986 from reference sensor color space (i.e. the "golden module" 8987 colorspace) into this camera device's native sensor color 8988 space under the second reference illuminant 8989 (android.sensor.referenceIlluminant2). 8990 8991 This matrix will only be present if the second reference 8992 illuminant is present. 8993 8994 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 8995 the camera device has RAW capability. 8996 </details> 8997 <tag id="RAW" /> 8998 </entry> 8999 <entry name="colorTransform1" type="rational" 9000 visibility="public" optional="true" 9001 type_notes="3x3 matrix in row-major-order" container="array" 9002 typedef="colorSpaceTransform" permission_needed="true" > 9003 <array> 9004 <size>3</size> 9005 <size>3</size> 9006 </array> 9007 <description> 9008 A matrix that transforms color values from CIE XYZ color space to 9009 reference sensor color space. 9010 </description> 9011 <details> 9012 This matrix is used to convert from the standard CIE XYZ color 9013 space to the reference sensor colorspace, and is used when processing 9014 raw buffer data. 9015 9016 The matrix is expressed as a 3x3 matrix in row-major-order, and 9017 contains a color transform matrix that maps colors from the CIE 9018 XYZ color space to the reference sensor color space (i.e. the 9019 "golden module" colorspace) under the first reference illuminant 9020 (android.sensor.referenceIlluminant1). 9021 9022 The white points chosen in both the reference sensor color space 9023 and the CIE XYZ colorspace when calculating this transform will 9024 match the standard white point for the first reference illuminant 9025 (i.e. no chromatic adaptation will be applied by this transform). 9026 9027 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 9028 the camera device has RAW capability. 9029 </details> 9030 <tag id="RAW" /> 9031 </entry> 9032 <entry name="colorTransform2" type="rational" 9033 visibility="public" optional="true" 9034 type_notes="3x3 matrix in row-major-order" container="array" 9035 typedef="colorSpaceTransform" permission_needed="true" > 9036 <array> 9037 <size>3</size> 9038 <size>3</size> 9039 </array> 9040 <description> 9041 A matrix that transforms color values from CIE XYZ color space to 9042 reference sensor color space. 9043 </description> 9044 <details> 9045 This matrix is used to convert from the standard CIE XYZ color 9046 space to the reference sensor colorspace, and is used when processing 9047 raw buffer data. 9048 9049 The matrix is expressed as a 3x3 matrix in row-major-order, and 9050 contains a color transform matrix that maps colors from the CIE 9051 XYZ color space to the reference sensor color space (i.e. the 9052 "golden module" colorspace) under the second reference illuminant 9053 (android.sensor.referenceIlluminant2). 9054 9055 The white points chosen in both the reference sensor color space 9056 and the CIE XYZ colorspace when calculating this transform will 9057 match the standard white point for the second reference illuminant 9058 (i.e. no chromatic adaptation will be applied by this transform). 9059 9060 This matrix will only be present if the second reference 9061 illuminant is present. 9062 9063 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 9064 the camera device has RAW capability. 9065 </details> 9066 <tag id="RAW" /> 9067 </entry> 9068 <entry name="forwardMatrix1" type="rational" 9069 visibility="public" optional="true" 9070 type_notes="3x3 matrix in row-major-order" container="array" 9071 typedef="colorSpaceTransform" permission_needed="true" > 9072 <array> 9073 <size>3</size> 9074 <size>3</size> 9075 </array> 9076 <description> 9077 A matrix that transforms white balanced camera colors from the reference 9078 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 9079 </description> 9080 <details> 9081 This matrix is used to convert to the standard CIE XYZ colorspace, and 9082 is used when processing raw buffer data. 9083 9084 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 9085 a color transform matrix that maps white balanced colors from the 9086 reference sensor color space to the CIE XYZ color space with a D50 white 9087 point. 9088 9089 Under the first reference illuminant (android.sensor.referenceIlluminant1) 9090 this matrix is chosen so that the standard white point for this reference 9091 illuminant in the reference sensor colorspace is mapped to D50 in the 9092 CIE XYZ colorspace. 9093 9094 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 9095 the camera device has RAW capability. 9096 </details> 9097 <tag id="RAW" /> 9098 </entry> 9099 <entry name="forwardMatrix2" type="rational" 9100 visibility="public" optional="true" 9101 type_notes="3x3 matrix in row-major-order" container="array" 9102 typedef="colorSpaceTransform" permission_needed="true" > 9103 <array> 9104 <size>3</size> 9105 <size>3</size> 9106 </array> 9107 <description> 9108 A matrix that transforms white balanced camera colors from the reference 9109 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 9110 </description> 9111 <details> 9112 This matrix is used to convert to the standard CIE XYZ colorspace, and 9113 is used when processing raw buffer data. 9114 9115 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 9116 a color transform matrix that maps white balanced colors from the 9117 reference sensor color space to the CIE XYZ color space with a D50 white 9118 point. 9119 9120 Under the second reference illuminant (android.sensor.referenceIlluminant2) 9121 this matrix is chosen so that the standard white point for this reference 9122 illuminant in the reference sensor colorspace is mapped to D50 in the 9123 CIE XYZ colorspace. 9124 9125 This matrix will only be present if the second reference 9126 illuminant is present. 9127 9128 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 9129 the camera device has RAW capability. 9130 </details> 9131 <tag id="RAW" /> 9132 </entry> 9133 <entry name="baseGainFactor" type="rational" 9134 optional="true"> 9135 <description>Gain factor from electrons to raw units when 9136 ISO=100</description> 9137 <tag id="FUTURE" /> 9138 </entry> 9139 <entry name="blackLevelPattern" type="int32" visibility="public" 9140 optional="true" type_notes="2x2 raw count block" container="array" 9141 typedef="blackLevelPattern"> 9142 <array> 9143 <size>4</size> 9144 </array> 9145 <description> 9146 A fixed black level offset for each of the color filter arrangement 9147 (CFA) mosaic channels. 9148 </description> 9149 <range>&gt;= 0 for each.</range> 9150 <details> 9151 This key specifies the zero light value for each of the CFA mosaic 9152 channels in the camera sensor. The maximal value output by the 9153 sensor is represented by the value in android.sensor.info.whiteLevel. 9154 9155 The values are given in the same order as channels listed for the CFA 9156 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 9157 nth value given corresponds to the black level offset for the nth 9158 color channel listed in the CFA. 9159 9160 The black level values of captured images may vary for different 9161 capture settings (e.g., android.sensor.sensitivity). This key 9162 represents a coarse approximation for such case. It is recommended to 9163 use android.sensor.dynamicBlackLevel or use pixels from 9164 android.sensor.opticalBlackRegions directly for captures when 9165 supported by the camera device, which provides more accurate black 9166 level values. For raw capture in particular, it is recommended to use 9167 pixels from android.sensor.opticalBlackRegions to calculate black 9168 level values for each frame. 9169 9170 For a MONOCHROME camera device, all of the 2x2 channels must have the same values. 9171 </details> 9172 <hal_details> 9173 The values are given in row-column scan order, with the first value 9174 corresponding to the element of the CFA in row=0, column=0. 9175 </hal_details> 9176 <tag id="RAW" /> 9177 </entry> 9178 <entry name="maxAnalogSensitivity" type="int32" visibility="public" 9179 optional="true" hwlevel="full"> 9180 <description>Maximum sensitivity that is implemented 9181 purely through analog gain.</description> 9182 <details>For android.sensor.sensitivity values less than or 9183 equal to this, all applied gain must be analog. For 9184 values above this, the gain applied can be a mix of analog and 9185 digital.</details> 9186 <tag id="V1" /> 9187 <tag id="FULL" /> 9188 </entry> 9189 <entry name="orientation" type="int32" visibility="public" 9190 hwlevel="legacy"> 9191 <description>Clockwise angle through which the output image needs to be rotated to be 9192 upright on the device screen in its native orientation. 9193 </description> 9194 <units>Degrees of clockwise rotation; always a multiple of 9195 90</units> 9196 <range>0, 90, 180, 270</range> 9197 <details> 9198 Also defines the direction of rolling shutter readout, which is from top to bottom in 9199 the sensor's coordinate system. 9200 9201 Starting with Android API level 32, camera clients that query the orientation via 9202 {@link android.hardware.camera2.CameraCharacteristics#get} on foldable devices which 9203 include logical cameras can receive a value that can dynamically change depending on the 9204 device/fold state. 9205 Clients are advised to not cache or store the orientation value of such logical sensors. 9206 In case repeated queries to CameraCharacteristics are not preferred, then clients can 9207 also access the entire mapping from device state to sensor orientation in 9208 {@link android.hardware.camera2.params.DeviceStateSensorOrientationMap}. 9209 Do note that a dynamically changing sensor orientation value in camera characteristics 9210 will not be the best way to establish the orientation per frame. Clients that want to 9211 know the sensor orientation of a particular captured frame should query the 9212 android.logicalMultiCamera.activePhysicalId from the corresponding capture result and 9213 check the respective physical camera orientation. 9214 </details> 9215 <ndk_details> 9216 Native camera clients must query android.info.deviceStateOrientations for the mapping 9217 between device state and camera sensor orientation. Dynamic updates to the sensor 9218 orientation are not supported in this code path. 9219 </ndk_details> 9220 <tag id="BC" /> 9221 </entry> 9222 <entry name="profileHueSatMapDimensions" type="int32" 9223 visibility="system" optional="true" 9224 type_notes="Number of samples for hue, saturation, and value" 9225 container="array"> 9226 <array> 9227 <size>3</size> 9228 </array> 9229 <description> 9230 The number of input samples for each dimension of 9231 android.sensor.profileHueSatMap. 9232 </description> 9233 <range> 9234 Hue &gt;= 1, 9235 Saturation &gt;= 2, 9236 Value &gt;= 1 9237 </range> 9238 <details> 9239 The number of input samples for the hue, saturation, and value 9240 dimension of android.sensor.profileHueSatMap. The order of the 9241 dimensions given is hue, saturation, value; where hue is the 0th 9242 element. 9243 </details> 9244 <tag id="RAW" /> 9245 </entry> 9246 </static> 9247 <dynamic> 9248 <clone entry="android.sensor.exposureTime" kind="controls"> 9249 </clone> 9250 <clone entry="android.sensor.frameDuration" 9251 kind="controls"></clone> 9252 <clone entry="android.sensor.sensitivity" kind="controls"> 9253 </clone> 9254 <entry name="timestamp" type="int64" visibility="public" 9255 hwlevel="legacy"> 9256 <description>Time at start of exposure of first 9257 row of the image sensor active array, in nanoseconds.</description> 9258 <units>Nanoseconds</units> 9259 <range>&gt; 0</range> 9260 <details>The timestamps are also included in all image 9261 buffers produced for the same capture, and will be identical 9262 on all the outputs. 9263 9264 When android.sensor.info.timestampSource `==` UNKNOWN, 9265 the timestamps measure time since an unspecified starting point, 9266 and are monotonically increasing. They can be compared with the 9267 timestamps for other captures from the same camera device, but are 9268 not guaranteed to be comparable to any other time source. 9269 9270 When android.sensor.info.timestampSource `==` REALTIME, the 9271 timestamps measure time in the same timebase as {@link 9272 android.os.SystemClock#elapsedRealtimeNanos}, and they can 9273 be compared to other timestamps from other subsystems that 9274 are using that base. 9275 9276 For reprocessing, the timestamp will match the start of exposure of 9277 the input image, i.e. {@link CaptureResult#SENSOR_TIMESTAMP the 9278 timestamp} in the TotalCaptureResult that was used to create the 9279 reprocess capture request. 9280 </details> 9281 <hal_details> 9282 All timestamps must be in reference to the kernel's 9283 CLOCK_BOOTTIME monotonic clock, which properly accounts for 9284 time spent asleep. This allows for synchronization with 9285 sensors that continue to operate while the system is 9286 otherwise asleep. 9287 9288 If android.sensor.info.timestampSource `==` REALTIME, 9289 The timestamp must be synchronized with the timestamps from other 9290 sensor subsystems that are using the same timebase. 9291 9292 For reprocessing, the input image's start of exposure can be looked up 9293 with android.sensor.timestamp from the metadata included in the 9294 capture request. 9295 </hal_details> 9296 <tag id="BC" /> 9297 </entry> 9298 <entry name="temperature" type="float" 9299 optional="true"> 9300 <description>The temperature of the sensor, sampled at the time 9301 exposure began for this frame. 9302 9303 The thermal diode being queried should be inside the sensor PCB, or 9304 somewhere close to it. 9305 </description> 9306 9307 <units>Celsius</units> 9308 <range>Optional. This value is missing if no temperature is available.</range> 9309 <tag id="FUTURE" /> 9310 </entry> 9311 <entry name="neutralColorPoint" type="rational" visibility="public" 9312 optional="true" container="array"> 9313 <array> 9314 <size>3</size> 9315 </array> 9316 <description> 9317 The estimated camera neutral color in the native sensor colorspace at 9318 the time of capture. 9319 </description> 9320 <details> 9321 This value gives the neutral color point encoded as an RGB value in the 9322 native sensor color space. The neutral color point indicates the 9323 currently estimated white point of the scene illumination. It can be 9324 used to interpolate between the provided color transforms when 9325 processing raw sensor data. 9326 9327 The order of the values is R, G, B; where R is in the lowest index. 9328 9329 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 9330 the camera device has RAW capability. 9331 </details> 9332 <tag id="RAW" /> 9333 </entry> 9334 <entry name="noiseProfile" type="double" visibility="public" 9335 optional="true" type_notes="Pairs of noise model coefficients" 9336 container="array" typedef="pairDoubleDouble"> 9337 <array> 9338 <size>2</size> 9339 <size>CFA Channels</size> 9340 </array> 9341 <description> 9342 Noise model coefficients for each CFA mosaic channel. 9343 </description> 9344 <details> 9345 This key contains two noise model coefficients for each CFA channel 9346 corresponding to the sensor amplification (S) and sensor readout 9347 noise (O). These are given as pairs of coefficients for each channel 9348 in the same order as channels listed for the CFA layout key 9349 (see android.sensor.info.colorFilterArrangement). This is 9350 represented as an array of Pair&lt;Double, Double&gt;, where 9351 the first member of the Pair at index n is the S coefficient and the 9352 second member is the O coefficient for the nth color channel in the CFA. 9353 9354 These coefficients are used in a two parameter noise model to describe 9355 the amount of noise present in the image for each CFA channel. The 9356 noise model used here is: 9357 9358 N(x) = sqrt(Sx + O) 9359 9360 Where x represents the recorded signal of a CFA channel normalized to 9361 the range [0, 1], and S and O are the noise model coeffiecients for 9362 that channel. 9363 9364 A more detailed description of the noise model can be found in the 9365 Adobe DNG specification for the NoiseProfile tag. 9366 9367 For a MONOCHROME camera, there is only one color channel. So the noise model coefficients 9368 will only contain one S and one O. 9369 9370 </details> 9371 <hal_details> 9372 For a CFA layout of RGGB, the list of coefficients would be given as 9373 an array of doubles S0,O0,S1,O1,..., where S0 and O0 are the coefficients 9374 for the red channel, S1 and O1 are the coefficients for the first green 9375 channel, etc. 9376 </hal_details> 9377 <tag id="RAW" /> 9378 </entry> 9379 <entry name="profileHueSatMap" type="float" 9380 visibility="system" optional="true" 9381 type_notes="Mapping for hue, saturation, and value" 9382 container="array"> 9383 <array> 9384 <size>hue_samples</size> 9385 <size>saturation_samples</size> 9386 <size>value_samples</size> 9387 <size>3</size> 9388 </array> 9389 <description> 9390 A mapping containing a hue shift, saturation scale, and value scale 9391 for each pixel. 9392 </description> 9393 <units> 9394 The hue shift is given in degrees; saturation and value scale factors are 9395 unitless and are between 0 and 1 inclusive 9396 </units> 9397 <details> 9398 hue_samples, saturation_samples, and value_samples are given in 9399 android.sensor.profileHueSatMapDimensions. 9400 9401 Each entry of this map contains three floats corresponding to the 9402 hue shift, saturation scale, and value scale, respectively; where the 9403 hue shift has the lowest index. The map entries are stored in the key 9404 in nested loop order, with the value divisions in the outer loop, the 9405 hue divisions in the middle loop, and the saturation divisions in the 9406 inner loop. All zero input saturation entries are required to have a 9407 value scale factor of 1.0. 9408 </details> 9409 <tag id="RAW" /> 9410 </entry> 9411 <entry name="profileToneCurve" type="float" 9412 visibility="system" optional="true" 9413 type_notes="Samples defining a spline for a tone-mapping curve" 9414 container="array"> 9415 <array> 9416 <size>samples</size> 9417 <size>2</size> 9418 </array> 9419 <description> 9420 A list of x,y samples defining a tone-mapping curve for gamma adjustment. 9421 </description> 9422 <range> 9423 Each sample has an input range of `[0, 1]` and an output range of 9424 `[0, 1]`. The first sample is required to be `(0, 0)`, and the last 9425 sample is required to be `(1, 1)`. 9426 </range> 9427 <details> 9428 This key contains a default tone curve that can be applied while 9429 processing the image as a starting point for user adjustments. 9430 The curve is specified as a list of value pairs in linear gamma. 9431 The curve is interpolated using a cubic spline. 9432 </details> 9433 <tag id="RAW" /> 9434 </entry> 9435 <entry name="greenSplit" type="float" visibility="public" optional="true"> 9436 <description> 9437 The worst-case divergence between Bayer green channels. 9438 </description> 9439 <range> 9440 &gt;= 0 9441 </range> 9442 <details> 9443 This value is an estimate of the worst case split between the 9444 Bayer green channels in the red and blue rows in the sensor color 9445 filter array. 9446 9447 The green split is calculated as follows: 9448 9449 1. A 5x5 pixel (or larger) window W within the active sensor array is 9450 chosen. The term 'pixel' here is taken to mean a group of 4 Bayer 9451 mosaic channels (R, Gr, Gb, B). The location and size of the window 9452 chosen is implementation defined, and should be chosen to provide a 9453 green split estimate that is both representative of the entire image 9454 for this camera sensor, and can be calculated quickly. 9455 1. The arithmetic mean of the green channels from the red 9456 rows (mean_Gr) within W is computed. 9457 1. The arithmetic mean of the green channels from the blue 9458 rows (mean_Gb) within W is computed. 9459 1. The maximum ratio R of the two means is computed as follows: 9460 `R = max((mean_Gr + 1)/(mean_Gb + 1), (mean_Gb + 1)/(mean_Gr + 1))` 9461 9462 The ratio R is the green split divergence reported for this property, 9463 which represents how much the green channels differ in the mosaic 9464 pattern. This value is typically used to determine the treatment of 9465 the green mosaic channels when demosaicing. 9466 9467 The green split value can be roughly interpreted as follows: 9468 9469 * R &lt; 1.03 is a negligible split (&lt;3% divergence). 9470 * 1.20 &lt;= R &gt;= 1.03 will require some software 9471 correction to avoid demosaic errors (3-20% divergence). 9472 * R &gt; 1.20 will require strong software correction to produce 9473 a usuable image (&gt;20% divergence). 9474 9475 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 9476 the camera device has RAW capability. 9477 </details> 9478 <hal_details> 9479 The green split given may be a static value based on prior 9480 characterization of the camera sensor using the green split 9481 calculation method given here over a large, representative, sample 9482 set of images. Other methods of calculation that produce equivalent 9483 results, and can be interpreted in the same manner, may be used. 9484 </hal_details> 9485 <tag id="RAW" /> 9486 </entry> 9487 </dynamic> 9488 <controls> 9489 <entry name="testPatternData" type="int32" visibility="public" optional="true" container="array"> 9490 <array> 9491 <size>4</size> 9492 </array> 9493 <description> 9494 A pixel `[R, G_even, G_odd, B]` that supplies the test pattern 9495 when android.sensor.testPatternMode is SOLID_COLOR. 9496 </description> 9497 <details> 9498 Each color channel is treated as an unsigned 32-bit integer. 9499 The camera device then uses the most significant X bits 9500 that correspond to how many bits are in its Bayer raw sensor 9501 output. 9502 9503 For example, a sensor with RAW10 Bayer output would use the 9504 10 most significant bits from each color channel. 9505 </details> 9506 <hal_details> 9507 </hal_details> 9508 </entry> 9509 <entry name="testPatternMode" type="int32" visibility="public" optional="true" 9510 enum="true"> 9511 <enum> 9512 <value>OFF 9513 <notes>No test pattern mode is used, and the camera 9514 device returns captures from the image sensor. 9515 9516 This is the default if the key is not set.</notes> 9517 </value> 9518 <value>SOLID_COLOR 9519 <notes> 9520 Each pixel in `[R, G_even, G_odd, B]` is replaced by its 9521 respective color channel provided in 9522 android.sensor.testPatternData. 9523 9524 For example: 9525 9526 android.sensor.testPatternData = [0, 0xFFFFFFFF, 0xFFFFFFFF, 0] 9527 9528 All green pixels are 100% green. All red/blue pixels are black. 9529 9530 android.sensor.testPatternData = [0xFFFFFFFF, 0, 0xFFFFFFFF, 0] 9531 9532 All red pixels are 100% red. Only the odd green pixels 9533 are 100% green. All blue pixels are 100% black. 9534 </notes> 9535 </value> 9536 <value>COLOR_BARS 9537 <notes> 9538 All pixel data is replaced with an 8-bar color pattern. 9539 9540 The vertical bars (left-to-right) are as follows: 9541 9542 * 100% white 9543 * yellow 9544 * cyan 9545 * green 9546 * magenta 9547 * red 9548 * blue 9549 * black 9550 9551 In general the image would look like the following: 9552 9553 W Y C G M R B K 9554 W Y C G M R B K 9555 W Y C G M R B K 9556 W Y C G M R B K 9557 W Y C G M R B K 9558 . . . . . . . . 9559 . . . . . . . . 9560 . . . . . . . . 9561 9562 (B = Blue, K = Black) 9563 9564 Each bar should take up 1/8 of the sensor pixel array width. 9565 When this is not possible, the bar size should be rounded 9566 down to the nearest integer and the pattern can repeat 9567 on the right side. 9568 9569 Each bar's height must always take up the full sensor 9570 pixel array height. 9571 9572 Each pixel in this test pattern must be set to either 9573 0% intensity or 100% intensity. 9574 </notes> 9575 </value> 9576 <value>COLOR_BARS_FADE_TO_GRAY 9577 <notes> 9578 The test pattern is similar to COLOR_BARS, except that 9579 each bar should start at its specified color at the top, 9580 and fade to gray at the bottom. 9581 9582 Furthermore each bar is further subdivided into a left and 9583 right half. The left half should have a smooth gradient, 9584 and the right half should have a quantized gradient. 9585 9586 In particular, the right half's should consist of blocks of the 9587 same color for 1/16th active sensor pixel array width. 9588 9589 The least significant bits in the quantized gradient should 9590 be copied from the most significant bits of the smooth gradient. 9591 9592 The height of each bar should always be a multiple of 128. 9593 When this is not the case, the pattern should repeat at the bottom 9594 of the image. 9595 </notes> 9596 </value> 9597 <value>PN9 9598 <notes> 9599 All pixel data is replaced by a pseudo-random sequence 9600 generated from a PN9 512-bit sequence (typically implemented 9601 in hardware with a linear feedback shift register). 9602 9603 The generator should be reset at the beginning of each frame, 9604 and thus each subsequent raw frame with this test pattern should 9605 be exactly the same as the last. 9606 </notes> 9607 </value> 9608 <value visibility="test" hal_version="3.6">BLACK 9609 <notes> 9610 All pixel data is replaced by 0% intensity (black) values. 9611 9612 This test pattern is identical to SOLID_COLOR with a value of `[0, 0, 0, 0]` for 9613 android.sensor.testPatternData. It is recommended that devices implement full 9614 SOLID_COLOR support instead, but BLACK can be used to provide minimal support for a 9615 test pattern suitable for privacy use cases. 9616 </notes> 9617 </value> 9618 <value id="256">CUSTOM1 9619 <notes>The first custom test pattern. All custom patterns that are 9620 available only on this camera device are at least this numeric 9621 value. 9622 9623 All of the custom test patterns will be static 9624 (that is the raw image must not vary from frame to frame). 9625 </notes> 9626 </value> 9627 </enum> 9628 <description>When enabled, the sensor sends a test pattern instead of 9629 doing a real exposure from the camera. 9630 </description> 9631 <range>android.sensor.availableTestPatternModes</range> 9632 <details> 9633 When a test pattern is enabled, all manual sensor controls specified 9634 by android.sensor.* will be ignored. All other controls should 9635 work as normal. 9636 9637 For example, if manual flash is enabled, flash firing should still 9638 occur (and that the test pattern remain unmodified, since the flash 9639 would not actually affect it). 9640 9641 Defaults to OFF. 9642 </details> 9643 <hal_details> 9644 All test patterns are specified in the Bayer domain. 9645 9646 The HAL may choose to substitute test patterns from the sensor 9647 with test patterns from on-device memory. In that case, it should be 9648 indistinguishable to the ISP whether the data came from the 9649 sensor interconnect bus (such as CSI2) or memory. 9650 9651 For privacy use cases, if the camera device: 9652 9653 * supports SOLID_COLOR or BLACK test patterns, 9654 * is a logical multi-camera, and 9655 * lists testPatternMode as a physical request key, 9656 9657 Each physical camera must support the same SOLID_COLOR and/or BLACK test patterns 9658 as the logical camera. 9659 </hal_details> 9660 </entry> 9661 </controls> 9662 <dynamic> 9663 <clone entry="android.sensor.testPatternData" kind="controls"> 9664 </clone> 9665 <clone entry="android.sensor.testPatternMode" kind="controls"> 9666 </clone> 9667 </dynamic> 9668 <static> 9669 <entry name="availableTestPatternModes" type="int32" visibility="public" optional="true" 9670 type_notes="list of enums" container="array"> 9671 <array> 9672 <size>n</size> 9673 </array> 9674 <description>List of sensor test pattern modes for android.sensor.testPatternMode 9675 supported by this camera device. 9676 </description> 9677 <range>Any value listed in android.sensor.testPatternMode</range> 9678 <details> 9679 Defaults to OFF, and always includes OFF if defined. 9680 </details> 9681 <hal_details> 9682 All custom modes must be >= CUSTOM1. 9683 </hal_details> 9684 </entry> 9685 </static> 9686 <dynamic> 9687 <entry name="rollingShutterSkew" type="int64" visibility="public" hwlevel="limited"> 9688 <description>Duration between the start of exposure for the first row of the image sensor, 9689 and the start of exposure for one past the last row of the image sensor.</description> 9690 <units>Nanoseconds</units> 9691 <range> &gt;= 0 and &lt; 9692 {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration}.</range> 9693 <details> 9694 This is the exposure time skew between the first and `(last+1)` row exposure start times. The 9695 first row and the last row are the first and last rows inside of the 9696 android.sensor.info.activeArraySize. 9697 9698 For typical camera sensors that use rolling shutters, this is also equivalent to the frame 9699 readout time. 9700 9701 If the image sensor is operating in a binned or cropped mode due to the current output 9702 target resolutions, it's possible this skew is reported to be larger than the exposure 9703 time, for example, since it is based on the full array even if a partial array is read 9704 out. Be sure to scale the number to cover the section of the sensor actually being used 9705 for the outputs you care about. So if your output covers N rows of the active array of 9706 height H, scale this value by N/H to get the total skew for that viewport. 9707 9708 *Note:* Prior to Android 11, this field was described as measuring duration from 9709 first to last row of the image sensor, which is not equal to the frame readout time for a 9710 rolling shutter sensor. Implementations generally reported the latter value, so to resolve 9711 the inconsistency, the description has been updated to range from (first, last+1) row 9712 exposure start, instead. 9713 </details> 9714 <hal_details> 9715 The HAL must report `0` if the sensor is using global shutter, where all pixels begin 9716 exposure at the same time. 9717 </hal_details> 9718 <tag id="V1" /> 9719 </entry> 9720 </dynamic> 9721 <static> 9722 <entry name="opticalBlackRegions" type="int32" visibility="public" optional="true" 9723 container="array" typedef="rectangle"> 9724 <array> 9725 <size>4</size> 9726 <size>num_regions</size> 9727 </array> 9728 <description>List of disjoint rectangles indicating the sensor 9729 optically shielded black pixel regions. 9730 </description> 9731 <details> 9732 In most camera sensors, the active array is surrounded by some 9733 optically shielded pixel areas. By blocking light, these pixels 9734 provides a reliable black reference for black level compensation 9735 in active array region. 9736 9737 This key provides a list of disjoint rectangles specifying the 9738 regions of optically shielded (with metal shield) black pixel 9739 regions if the camera device is capable of reading out these black 9740 pixels in the output raw images. In comparison to the fixed black 9741 level values reported by android.sensor.blackLevelPattern, this key 9742 may provide a more accurate way for the application to calculate 9743 black level of each captured raw images. 9744 9745 When this key is reported, the android.sensor.dynamicBlackLevel and 9746 android.sensor.dynamicWhiteLevel will also be reported. 9747 </details> 9748 <ndk_details> 9749 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 9750 </ndk_details> 9751 <hal_details> 9752 This array contains (xmin, ymin, width, height). The (xmin, ymin) 9753 must be &gt;= (0,0) and &lt;= 9754 android.sensor.info.pixelArraySize. The (width, height) must be 9755 &lt;= android.sensor.info.pixelArraySize. Each region must be 9756 outside the region reported by 9757 android.sensor.info.preCorrectionActiveArraySize. 9758 9759 The HAL must report minimal number of disjoint regions for the 9760 optically shielded back pixel regions. For example, if a region can 9761 be covered by one rectangle, the HAL must not split this region into 9762 multiple rectangles. 9763 </hal_details> 9764 </entry> 9765 </static> 9766 <dynamic> 9767 <entry name="dynamicBlackLevel" type="float" visibility="public" 9768 optional="true" type_notes="2x2 raw count block" container="array"> 9769 <array> 9770 <size>4</size> 9771 </array> 9772 <description> 9773 A per-frame dynamic black level offset for each of the color filter 9774 arrangement (CFA) mosaic channels. 9775 </description> 9776 <range>&gt;= 0 for each.</range> 9777 <details> 9778 Camera sensor black levels may vary dramatically for different 9779 capture settings (e.g. android.sensor.sensitivity). The fixed black 9780 level reported by android.sensor.blackLevelPattern may be too 9781 inaccurate to represent the actual value on a per-frame basis. The 9782 camera device internal pipeline relies on reliable black level values 9783 to process the raw images appropriately. To get the best image 9784 quality, the camera device may choose to estimate the per frame black 9785 level values either based on optically shielded black regions 9786 (android.sensor.opticalBlackRegions) or its internal model. 9787 9788 This key reports the camera device estimated per-frame zero light 9789 value for each of the CFA mosaic channels in the camera sensor. The 9790 android.sensor.blackLevelPattern may only represent a coarse 9791 approximation of the actual black level values. This value is the 9792 black level used in camera device internal image processing pipeline 9793 and generally more accurate than the fixed black level values. 9794 However, since they are estimated values by the camera device, they 9795 may not be as accurate as the black level values calculated from the 9796 optical black pixels reported by android.sensor.opticalBlackRegions. 9797 9798 The values are given in the same order as channels listed for the CFA 9799 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 9800 nth value given corresponds to the black level offset for the nth 9801 color channel listed in the CFA. 9802 9803 For a MONOCHROME camera, all of the 2x2 channels must have the same values. 9804 9805 This key will be available if android.sensor.opticalBlackRegions is available or the 9806 camera device advertises this key via {@link 9807 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 9808 </details> 9809 <hal_details> 9810 The values are given in row-column scan order, with the first value 9811 corresponding to the element of the CFA in row=0, column=0. 9812 </hal_details> 9813 <tag id="RAW" /> 9814 </entry> 9815 <entry name="dynamicWhiteLevel" type="int32" visibility="public" 9816 optional="true" > 9817 <description> 9818 Maximum raw value output by sensor for this frame. 9819 </description> 9820 <range> &gt;= 0</range> 9821 <details> 9822 Since the android.sensor.blackLevelPattern may change for different 9823 capture settings (e.g., android.sensor.sensitivity), the white 9824 level will change accordingly. This key is similar to 9825 android.sensor.info.whiteLevel, but specifies the camera device 9826 estimated white level for each frame. 9827 9828 This key will be available if android.sensor.opticalBlackRegions is 9829 available or the camera device advertises this key via 9830 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureRequestKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 9831 </details> 9832 <hal_details> 9833 The full bit depth of the sensor must be available in the raw data, 9834 so the value for linear sensors should not be significantly lower 9835 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 9836 </hal_details> 9837 <tag id="RAW" /> 9838 </entry> 9839 </dynamic> 9840 <static> 9841 <entry name="opaqueRawSize" type="int32" visibility="system" container="array"> 9842 <array> 9843 <size>n</size> 9844 <size>3</size> 9845 </array> 9846 <description>Size in bytes for all the listed opaque RAW buffer sizes</description> 9847 <range>Must be large enough to fit the opaque RAW of corresponding size produced by 9848 the camera</range> 9849 <details> 9850 This configurations are listed as `(width, height, size_in_bytes)` tuples. 9851 This is used for sizing the gralloc buffers for opaque RAW buffers. 9852 All RAW_OPAQUE output stream configuration listed in 9853 android.scaler.availableStreamConfigurations will have a corresponding tuple in 9854 this key. 9855 </details> 9856 <hal_details> 9857 This key is added in legacy HAL3.4. 9858 9859 For legacy HAL3.4 or above: devices advertising RAW_OPAQUE format output must list this 9860 key. For legacy HAL3.3 or earlier devices: if RAW_OPAQUE ouput is advertised, camera 9861 framework will derive this key by assuming each pixel takes two bytes and no padding bytes 9862 between rows. 9863 </hal_details> 9864 </entry> 9865 <entry name="opaqueRawSizeMaximumResolution" type="int32" visibility="system" 9866 container="array" hal_version="3.6"> 9867 <array> 9868 <size>n</size> 9869 <size>3</size> 9870 </array> 9871 <description>Size in bytes for all the listed opaque RAW buffer sizes when 9872 android.sensor.pixelMode is set to 9873 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9874 </description> 9875 <range>Must be large enough to fit the opaque RAW of corresponding size produced by 9876 the camera</range> 9877 <details> 9878 Refer to android.sensor.opaqueRawSize for details. 9879 </details> 9880 <hal_details> 9881 Refer to android.sensor.opaqueRawSize for details. 9882 </hal_details> 9883 </entry> 9884 </static> 9885 <controls> 9886 <entry name="pixelMode" type="byte" visibility="public" enum="true" 9887 hal_version="3.6"> 9888 <enum> 9889 <value>DEFAULT 9890 <notes> This is the default sensor pixel mode. This is the only sensor pixel mode 9891 supported unless a camera device advertises 9892 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR}. 9893 </notes> 9894 </value> 9895 <value>MAXIMUM_RESOLUTION 9896 <notes> This sensor pixel mode is offered by devices with capability 9897 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR}. 9898 In this mode, sensors typically do not bin pixels, as a result can offer larger 9899 image sizes. 9900 </notes> 9901 </value> 9902 </enum> 9903 <description> 9904 Switches sensor pixel mode between maximum resolution mode and default mode. 9905 </description> 9906 <details> 9907 This key controls whether the camera sensor operates in 9908 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 9909 mode or not. By default, all camera devices operate in 9910 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode. 9911 When operating in 9912 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode, sensors 9913 with {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9914 capability would typically perform pixel binning in order to improve low light 9915 performance, noise reduction etc. However, in 9916 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 9917 mode (supported only 9918 by {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9919 sensors), sensors typically operate in unbinned mode allowing for a larger image size. 9920 The stream configurations supported in 9921 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 9922 mode are also different from those of 9923 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode. 9924 They can be queried through 9925 {@link android.hardware.camera2.CameraCharacteristics#get} with 9926 {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP_MAXIMUM_RESOLUTION)}. 9927 Unless reported by both 9928 {@link android.hardware.camera2.params.StreamConfigurationMap}s, the outputs from 9929 `android.scaler.streamConfigurationMapMaximumResolution` and 9930 `android.scaler.streamConfigurationMap` 9931 must not be mixed in the same CaptureRequest. In other words, these outputs are 9932 exclusive to each other. 9933 This key does not need to be set for reprocess requests. 9934 </details> 9935 </entry> 9936 </controls> 9937 <dynamic> 9938 <clone entry="android.sensor.pixelMode" kind="controls"> 9939 </clone> 9940 <entry name="rawBinningFactorUsed" type="byte" visibility="public" enum="true" 9941 typedef="boolean" hal_version="3.6"> 9942 <enum> 9943 <value>TRUE 9944 <notes> The `RAW` targets in this capture have android.sensor.info.binningFactor as the 9945 bayer pattern. 9946 </notes> 9947 </value> 9948 <value>FALSE 9949 <notes> The `RAW` targets have a regular bayer pattern in this capture. 9950 </notes> 9951 </value> 9952 </enum> 9953 <description> 9954 Whether `RAW` images requested have their bayer pattern as described by 9955 android.sensor.info.binningFactor. 9956 </description> 9957 <details> 9958 This key will only be present in devices advertisting the 9959 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9960 capability which also advertise `REMOSAIC_REPROCESSING` capability. On all other devices 9961 RAW targets will have a regular bayer pattern. 9962 </details> 9963 </entry> 9964 </dynamic> 9965 </section> 9966 <section name="shading"> 9967 <controls> 9968 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 9969 <enum> 9970 <value>OFF 9971 <notes>No lens shading correction is applied.</notes></value> 9972 <value>FAST 9973 <notes>Apply lens shading corrections, without slowing 9974 frame rate relative to sensor raw output</notes></value> 9975 <value>HIGH_QUALITY 9976 <notes>Apply high-quality lens shading correction, at the 9977 cost of possibly reduced frame rate.</notes></value> 9978 </enum> 9979 <description>Quality of lens shading correction applied 9980 to the image data.</description> 9981 <range>android.shading.availableModes</range> 9982 <details> 9983 When set to OFF mode, no lens shading correction will be applied by the 9984 camera device, and an identity lens shading map data will be provided 9985 if `android.statistics.lensShadingMapMode == ON`. For example, for lens 9986 shading map with size of `[ 4, 3 ]`, 9987 the output android.statistics.lensShadingCorrectionMap for this case will be an identity 9988 map shown below: 9989 9990 [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9991 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9992 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9993 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9994 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9995 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] 9996 9997 When set to other modes, lens shading correction will be applied by the camera 9998 device. Applications can request lens shading map data by setting 9999 android.statistics.lensShadingMapMode to ON, and then the camera device will provide lens 10000 shading map data in android.statistics.lensShadingCorrectionMap; the returned shading map 10001 data will be the one applied by the camera device for this capture request. 10002 10003 The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore 10004 the reliability of the map data may be affected by the AE and AWB algorithms. When AE and 10005 AWB are in AUTO modes(android.control.aeMode `!=` OFF and android.control.awbMode `!=` 10006 OFF), to get best results, it is recommended that the applications wait for the AE and AWB 10007 to be converged before using the returned shading map data. 10008 </details> 10009 </entry> 10010 <entry name="strength" type="byte"> 10011 <description>Control the amount of shading correction 10012 applied to the images</description> 10013 <units>unitless: 1-10; 10 is full shading 10014 compensation</units> 10015 <tag id="FUTURE" /> 10016 </entry> 10017 </controls> 10018 <dynamic> 10019 <clone entry="android.shading.mode" kind="controls"> 10020 </clone> 10021 </dynamic> 10022 <static> 10023 <entry name="availableModes" type="byte" visibility="public" 10024 type_notes="List of enums (android.shading.mode)." container="array" 10025 typedef="enumList" hwlevel="legacy"> 10026 <array> 10027 <size>n</size> 10028 </array> 10029 <description> 10030 List of lens shading modes for android.shading.mode that are supported by this camera device. 10031 </description> 10032 <range>Any value listed in android.shading.mode</range> 10033 <details> 10034 This list contains lens shading modes that can be set for the camera device. 10035 Camera devices that support the MANUAL_POST_PROCESSING capability will always 10036 list OFF and FAST mode. This includes all FULL level devices. 10037 LEGACY devices will always only support FAST mode. 10038 </details> 10039 <hal_details> 10040 HAL must support both FAST and HIGH_QUALITY if lens shading correction control is 10041 available on the camera device, but the underlying implementation can be the same for 10042 both modes. That is, if the highest quality implementation on the camera device does not 10043 slow down capture rate, then FAST and HIGH_QUALITY will generate the same output. 10044 </hal_details> 10045 </entry> 10046 </static> 10047 </section> 10048 <section name="statistics"> 10049 <controls> 10050 <entry name="faceDetectMode" type="byte" visibility="public" enum="true" 10051 hwlevel="legacy"> 10052 <enum> 10053 <value>OFF 10054 <notes>Do not include face detection statistics in capture 10055 results.</notes></value> 10056 <value optional="true">SIMPLE 10057 <notes>Return face rectangle and confidence values only. 10058 </notes></value> 10059 <value optional="true">FULL 10060 <notes>Return all face 10061 metadata. 10062 10063 In this mode, face rectangles, scores, landmarks, and face IDs are all valid. 10064 </notes></value> 10065 </enum> 10066 <description>Operating mode for the face detector 10067 unit.</description> 10068 <range>android.statistics.info.availableFaceDetectModes</range> 10069 <details>Whether face detection is enabled, and whether it 10070 should output just the basic fields or the full set of 10071 fields.</details> 10072 <hal_details> 10073 SIMPLE mode must fill in android.statistics.faceRectangles and 10074 android.statistics.faceScores. 10075 FULL mode must also fill in android.statistics.faceIds, and 10076 android.statistics.faceLandmarks. 10077 </hal_details> 10078 <tag id="BC" /> 10079 </entry> 10080 <entry name="histogramMode" type="byte" enum="true" typedef="boolean"> 10081 <enum> 10082 <value>OFF</value> 10083 <value>ON</value> 10084 </enum> 10085 <description>Operating mode for histogram 10086 generation</description> 10087 <tag id="FUTURE" /> 10088 </entry> 10089 <entry name="sharpnessMapMode" type="byte" enum="true" typedef="boolean"> 10090 <enum> 10091 <value>OFF</value> 10092 <value>ON</value> 10093 </enum> 10094 <description>Operating mode for sharpness map 10095 generation</description> 10096 <tag id="FUTURE" /> 10097 </entry> 10098 <entry name="hotPixelMapMode" type="byte" visibility="public" enum="true" 10099 typedef="boolean"> 10100 <enum> 10101 <value>OFF 10102 <notes>Hot pixel map production is disabled. 10103 </notes></value> 10104 <value>ON 10105 <notes>Hot pixel map production is enabled. 10106 </notes></value> 10107 </enum> 10108 <description> 10109 Operating mode for hot pixel map generation. 10110 </description> 10111 <range>android.statistics.info.availableHotPixelMapModes</range> 10112 <details> 10113 If set to `true`, a hot pixel map is returned in android.statistics.hotPixelMap. 10114 If set to `false`, no hot pixel map will be returned. 10115 </details> 10116 <tag id="V1" /> 10117 <tag id="RAW" /> 10118 </entry> 10119 </controls> 10120 <static> 10121 <namespace name="info"> 10122 <entry name="availableFaceDetectModes" type="byte" 10123 visibility="public" 10124 type_notes="List of enums from android.statistics.faceDetectMode" 10125 container="array" 10126 typedef="enumList" 10127 hwlevel="legacy"> 10128 <array> 10129 <size>n</size> 10130 </array> 10131 <description>List of face detection modes for android.statistics.faceDetectMode that are 10132 supported by this camera device. 10133 </description> 10134 <range>Any value listed in android.statistics.faceDetectMode</range> 10135 <details>OFF is always supported. 10136 </details> 10137 </entry> 10138 <entry name="histogramBucketCount" type="int32"> 10139 <description>Number of histogram buckets 10140 supported</description> 10141 <range>&gt;= 64</range> 10142 <tag id="FUTURE" /> 10143 </entry> 10144 <entry name="maxFaceCount" type="int32" visibility="public" hwlevel="legacy"> 10145 <description>The maximum number of simultaneously detectable 10146 faces.</description> 10147 <range>0 for cameras without available face detection; otherwise: 10148 `>=4` for LIMITED or FULL hwlevel devices or 10149 `>0` for LEGACY devices.</range> 10150 <tag id="BC" /> 10151 </entry> 10152 <entry name="maxHistogramCount" type="int32"> 10153 <description>Maximum value possible for a histogram 10154 bucket</description> 10155 <tag id="FUTURE" /> 10156 </entry> 10157 <entry name="maxSharpnessMapValue" type="int32"> 10158 <description>Maximum value possible for a sharpness map 10159 region.</description> 10160 <tag id="FUTURE" /> 10161 </entry> 10162 <entry name="sharpnessMapSize" type="int32" 10163 type_notes="width x height" container="array" typedef="size"> 10164 <array> 10165 <size>2</size> 10166 </array> 10167 <description>Dimensions of the sharpness 10168 map</description> 10169 <range>Must be at least 32 x 32</range> 10170 <tag id="FUTURE" /> 10171 </entry> 10172 <entry name="availableHotPixelMapModes" type="byte" visibility="public" 10173 type_notes="list of enums" container="array" typedef="boolean"> 10174 <array> 10175 <size>n</size> 10176 </array> 10177 <description> 10178 List of hot pixel map output modes for android.statistics.hotPixelMapMode that are 10179 supported by this camera device. 10180 </description> 10181 <range>Any value listed in android.statistics.hotPixelMapMode</range> 10182 <details> 10183 If no hotpixel map output is available for this camera device, this will contain only 10184 `false`. 10185 10186 ON is always supported on devices with the RAW capability. 10187 </details> 10188 <tag id="V1" /> 10189 <tag id="RAW" /> 10190 </entry> 10191 <entry name="availableLensShadingMapModes" type="byte" visibility="public" 10192 type_notes="list of enums" container="array" typedef="enumList"> 10193 <array> 10194 <size>n</size> 10195 </array> 10196 <description> 10197 List of lens shading map output modes for android.statistics.lensShadingMapMode that 10198 are supported by this camera device. 10199 </description> 10200 <range>Any value listed in android.statistics.lensShadingMapMode</range> 10201 <details> 10202 If no lens shading map output is available for this camera device, this key will 10203 contain only OFF. 10204 10205 ON is always supported on devices with the RAW capability. 10206 LEGACY mode devices will always only support OFF. 10207 </details> 10208 </entry> 10209 <entry name="availableOisDataModes" type="byte" visibility="public" 10210 type_notes="list of enums" container="array" typedef="enumList" hal_version="3.3"> 10211 <array> 10212 <size>n</size> 10213 </array> 10214 <description> 10215 List of OIS data output modes for android.statistics.oisDataMode that 10216 are supported by this camera device. 10217 </description> 10218 <range>Any value listed in android.statistics.oisDataMode</range> 10219 <details> 10220 If no OIS data output is available for this camera device, this key will 10221 contain only OFF. 10222 </details> 10223 </entry> 10224 </namespace> 10225 </static> 10226 <dynamic> 10227 <clone entry="android.statistics.faceDetectMode" 10228 kind="controls"></clone> 10229 <entry name="faceIds" type="int32" visibility="ndk_public" 10230 container="array" hwlevel="legacy"> 10231 <array> 10232 <size>n</size> 10233 </array> 10234 <description>List of unique IDs for detected faces.</description> 10235 <details> 10236 Each detected face is given a unique ID that is valid for as long as the face is visible 10237 to the camera device. A face that leaves the field of view and later returns may be 10238 assigned a new ID. 10239 10240 Only available if android.statistics.faceDetectMode == FULL</details> 10241 <tag id="BC" /> 10242 </entry> 10243 <entry name="faceLandmarks" type="int32" visibility="ndk_public" 10244 type_notes="(leftEyeX, leftEyeY, rightEyeX, rightEyeY, mouthX, mouthY)" 10245 container="array" hwlevel="legacy"> 10246 <array> 10247 <size>n</size> 10248 <size>6</size> 10249 </array> 10250 <description>List of landmarks for detected 10251 faces.</description> 10252 <details> 10253 For devices not supporting android.distortionCorrection.mode control, the coordinate 10254 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 10255 the top-left pixel of the active array. 10256 10257 For devices supporting android.distortionCorrection.mode control, the coordinate 10258 system depends on the mode being set. 10259 When the distortion correction mode is OFF, the coordinate system follows 10260 android.sensor.info.preCorrectionActiveArraySize, with 10261 `(0, 0)` being the top-left pixel of the pre-correction active array. 10262 When the distortion correction mode is not OFF, the coordinate system follows 10263 android.sensor.info.activeArraySize, with 10264 `(0, 0)` being the top-left pixel of the active array. 10265 10266 Only available if android.statistics.faceDetectMode == FULL. 10267 10268 Starting from API level 30, the coordinate system of activeArraySize or 10269 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 10270 pre-zoomRatio field of view. This means that if the relative position of faces and 10271 the camera device doesn't change, when zooming in by increasing 10272 android.control.zoomRatio, the face landmarks move farther away from the center of the 10273 activeArray or preCorrectionActiveArray. If android.control.zoomRatio is set to 1.0 10274 (default), the face landmarks coordinates won't change as android.scaler.cropRegion 10275 changes. See android.control.zoomRatio for details. Whether to use activeArraySize or 10276 preCorrectionActiveArraySize still depends on distortion correction mode. 10277 </details> 10278 <hal_details> 10279 HAL must always report face landmarks in the coordinate system of pre-correction 10280 active array. 10281 </hal_details> 10282 <tag id="BC" /> 10283 </entry> 10284 <entry name="faceRectangles" type="int32" visibility="ndk_public" 10285 type_notes="(xmin, ymin, xmax, ymax). (0,0) is top-left of active pixel area" 10286 container="array" typedef="rectangle" hwlevel="legacy"> 10287 <array> 10288 <size>n</size> 10289 <size>4</size> 10290 </array> 10291 <description>List of the bounding rectangles for detected 10292 faces.</description> 10293 <details> 10294 For devices not supporting android.distortionCorrection.mode control, the coordinate 10295 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 10296 the top-left pixel of the active array. 10297 10298 For devices supporting android.distortionCorrection.mode control, the coordinate 10299 system depends on the mode being set. 10300 When the distortion correction mode is OFF, the coordinate system follows 10301 android.sensor.info.preCorrectionActiveArraySize, with 10302 `(0, 0)` being the top-left pixel of the pre-correction active array. 10303 When the distortion correction mode is not OFF, the coordinate system follows 10304 android.sensor.info.activeArraySize, with 10305 `(0, 0)` being the top-left pixel of the active array. 10306 10307 Only available if android.statistics.faceDetectMode != OFF. 10308 10309 Starting from API level 30, the coordinate system of activeArraySize or 10310 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 10311 pre-zoomRatio field of view. This means that if the relative position of faces and 10312 the camera device doesn't change, when zooming in by increasing 10313 android.control.zoomRatio, the face rectangles grow larger and move farther away from 10314 the center of the activeArray or preCorrectionActiveArray. If android.control.zoomRatio 10315 is set to 1.0 (default), the face rectangles won't change as android.scaler.cropRegion 10316 changes. See android.control.zoomRatio for details. Whether to use activeArraySize or 10317 preCorrectionActiveArraySize still depends on distortion correction mode. 10318 </details> 10319 <ndk_details> 10320 The data representation is `int[4]`, which maps to `(left, top, right, bottom)`. 10321 </ndk_details> 10322 <hal_details> 10323 HAL must always report face rectangles in the coordinate system of pre-correction 10324 active array. 10325 </hal_details> 10326 <tag id="BC" /> 10327 </entry> 10328 <entry name="faceScores" type="byte" visibility="ndk_public" 10329 container="array" hwlevel="legacy"> 10330 <array> 10331 <size>n</size> 10332 </array> 10333 <description>List of the face confidence scores for 10334 detected faces</description> 10335 <range>1-100</range> 10336 <details>Only available if android.statistics.faceDetectMode != OFF. 10337 </details> 10338 <hal_details> 10339 The value should be meaningful (for example, setting 100 at 10340 all times is illegal).</hal_details> 10341 <tag id="BC" /> 10342 </entry> 10343 <entry name="faces" type="int32" visibility="java_public" synthetic="true" 10344 container="array" typedef="face" hwlevel="legacy"> 10345 <array> 10346 <size>n</size> 10347 </array> 10348 <description>List of the faces detected through camera face detection 10349 in this capture.</description> 10350 <details> 10351 Only available if android.statistics.faceDetectMode `!=` OFF. 10352 </details> 10353 </entry> 10354 <entry name="histogram" type="int32" 10355 type_notes="count of pixels for each color channel that fall into each histogram bucket, scaled to be between 0 and maxHistogramCount" 10356 container="array"> 10357 <array> 10358 <size>n</size> 10359 <size>3</size> 10360 </array> 10361 <description>A 3-channel histogram based on the raw 10362 sensor data</description> 10363 <details>The k'th bucket (0-based) covers the input range 10364 (with w = android.sensor.info.whiteLevel) of [ k * w/N, 10365 (k + 1) * w / N ). If only a monochrome sharpness map is 10366 supported, all channels should have the same data</details> 10367 <tag id="FUTURE" /> 10368 </entry> 10369 <clone entry="android.statistics.histogramMode" 10370 kind="controls"></clone> 10371 <entry name="sharpnessMap" type="int32" 10372 type_notes="estimated sharpness for each region of the input image. Normalized to be between 0 and maxSharpnessMapValue. Higher values mean sharper (better focused)" 10373 container="array"> 10374 <array> 10375 <size>n</size> 10376 <size>m</size> 10377 <size>3</size> 10378 </array> 10379 <description>A 3-channel sharpness map, based on the raw 10380 sensor data</description> 10381 <details>If only a monochrome sharpness map is supported, 10382 all channels should have the same data</details> 10383 <tag id="FUTURE" /> 10384 </entry> 10385 <clone entry="android.statistics.sharpnessMapMode" 10386 kind="controls"></clone> 10387 <entry name="lensShadingCorrectionMap" type="byte" visibility="java_public" 10388 typedef="lensShadingMap" hwlevel="full"> 10389 <description>The shading map is a low-resolution floating-point map 10390 that lists the coefficients used to correct for vignetting, for each 10391 Bayer color channel.</description> 10392 <range>Each gain factor is &gt;= 1</range> 10393 <details> 10394 The map provided here is the same map that is used by the camera device to 10395 correct both color shading and vignetting for output non-RAW images. 10396 10397 When there is no lens shading correction applied to RAW 10398 output images (android.sensor.info.lensShadingApplied `==` 10399 false), this map is the complete lens shading correction 10400 map; when there is some lens shading correction applied to 10401 the RAW output image (android.sensor.info.lensShadingApplied 10402 `==` true), this map reports the remaining lens shading 10403 correction map that needs to be applied to get shading 10404 corrected images that match the camera device's output for 10405 non-RAW formats. 10406 10407 For a complete shading correction map, the least shaded 10408 section of the image will have a gain factor of 1; all 10409 other sections will have gains above 1. 10410 10411 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 10412 will take into account the colorCorrection settings. 10413 10414 The shading map is for the entire active pixel array, and is not 10415 affected by the crop region specified in the request. Each shading map 10416 entry is the value of the shading compensation map over a specific 10417 pixel on the sensor. Specifically, with a (N x M) resolution shading 10418 map, and an active pixel array size (W x H), shading map entry 10419 (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at 10420 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 10421 The map is assumed to be bilinearly interpolated between the sample points. 10422 10423 The channel order is [R, Geven, Godd, B], where Geven is the green 10424 channel for the even rows of a Bayer pattern, and Godd is the odd rows. 10425 The shading map is stored in a fully interleaved format. 10426 10427 The shading map will generally have on the order of 30-40 rows and columns, 10428 and will be smaller than 64x64. 10429 10430 As an example, given a very small map defined as: 10431 10432 width,height = [ 4, 3 ] 10433 values = 10434 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 10435 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 10436 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 10437 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 10438 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 10439 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 10440 10441 The low-resolution scaling map images for each channel are 10442 (displayed using nearest-neighbor interpolation): 10443 10444  10445  10446  10447  10448 10449 As a visualization only, inverting the full-color map to recover an 10450 image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives: 10451 10452  10453 10454 For a MONOCHROME camera, all of the 2x2 channels must have the same values. An example 10455 shading map for such a camera is defined as: 10456 10457 android.lens.info.shadingMapSize = [ 4, 3 ] 10458 android.statistics.lensShadingMap = 10459 [ 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 10460 1.1, 1.1, 1.1, 1.1, 1.3, 1.3, 1.3, 1.3, 10461 1.2, 1.2, 1.2, 1.2, 1.1, 1.1, 1.1, 1.1, 10462 1.0, 1.0, 1.0, 1.0, 1.2, 1.2, 1.2, 1.2, 10463 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 10464 1.2, 1.2, 1.2, 1.2, 1.3, 1.3, 1.3, 1.3 ] 10465 10466 </details> 10467 </entry> 10468 <entry name="lensShadingMap" type="float" visibility="ndk_public" 10469 type_notes="2D array of float gain factors per channel to correct lens shading" 10470 container="array" hwlevel="full"> 10471 <array> 10472 <size>4</size> 10473 <size>n</size> 10474 <size>m</size> 10475 </array> 10476 <description>The shading map is a low-resolution floating-point map 10477 that lists the coefficients used to correct for vignetting and color shading, 10478 for each Bayer color channel of RAW image data.</description> 10479 <range>Each gain factor is &gt;= 1</range> 10480 <details> 10481 The map provided here is the same map that is used by the camera device to 10482 correct both color shading and vignetting for output non-RAW images. 10483 10484 When there is no lens shading correction applied to RAW 10485 output images (android.sensor.info.lensShadingApplied `==` 10486 false), this map is the complete lens shading correction 10487 map; when there is some lens shading correction applied to 10488 the RAW output image (android.sensor.info.lensShadingApplied 10489 `==` true), this map reports the remaining lens shading 10490 correction map that needs to be applied to get shading 10491 corrected images that match the camera device's output for 10492 non-RAW formats. 10493 10494 For a complete shading correction map, the least shaded 10495 section of the image will have a gain factor of 1; all 10496 other sections will have gains above 1. 10497 10498 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 10499 will take into account the colorCorrection settings. 10500 10501 The shading map is for the entire active pixel array, and is not 10502 affected by the crop region specified in the request. Each shading map 10503 entry is the value of the shading compensation map over a specific 10504 pixel on the sensor. Specifically, with a (N x M) resolution shading 10505 map, and an active pixel array size (W x H), shading map entry 10506 (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at 10507 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 10508 The map is assumed to be bilinearly interpolated between the sample points. 10509 10510 For a Bayer camera, the channel order is [R, Geven, Godd, B], where Geven is 10511 the green channel for the even rows of a Bayer pattern, and Godd is the odd rows. 10512 The shading map is stored in a fully interleaved format, and its size 10513 is provided in the camera static metadata by android.lens.info.shadingMapSize. 10514 10515 The shading map will generally have on the order of 30-40 rows and columns, 10516 and will be smaller than 64x64. 10517 10518 As an example, given a very small map for a Bayer camera defined as: 10519 10520 android.lens.info.shadingMapSize = [ 4, 3 ] 10521 android.statistics.lensShadingMap = 10522 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 10523 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 10524 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 10525 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 10526 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 10527 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 10528 10529 The low-resolution scaling map images for each channel are 10530 (displayed using nearest-neighbor interpolation): 10531 10532  10533  10534  10535  10536 10537 As a visualization only, inverting the full-color map to recover an 10538 image of a gray wall (using bicubic interpolation for visual quality) 10539 as captured by the sensor gives: 10540 10541  10542 10543 For a MONOCHROME camera, all of the 2x2 channels must have the same values. An example 10544 shading map for such a camera is defined as: 10545 10546 android.lens.info.shadingMapSize = [ 4, 3 ] 10547 android.statistics.lensShadingMap = 10548 [ 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 10549 1.1, 1.1, 1.1, 1.1, 1.3, 1.3, 1.3, 1.3, 10550 1.2, 1.2, 1.2, 1.2, 1.1, 1.1, 1.1, 1.1, 10551 1.0, 1.0, 1.0, 1.0, 1.2, 1.2, 1.2, 1.2, 10552 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 10553 1.2, 1.2, 1.2, 1.2, 1.3, 1.3, 1.3, 1.3 ] 10554 10555 Note that the RAW image data might be subject to lens shading 10556 correction not reported on this map. Query 10557 android.sensor.info.lensShadingApplied to see if RAW image data has subject 10558 to lens shading correction. If android.sensor.info.lensShadingApplied 10559 is TRUE, the RAW image data is subject to partial or full lens shading 10560 correction. In the case full lens shading correction is applied to RAW 10561 images, the gain factor map reported in this key will contain all 1.0 gains. 10562 In other words, the map reported in this key is the remaining lens shading 10563 that needs to be applied on the RAW image to get images without lens shading 10564 artifacts. See android.request.maxNumOutputRaw for a list of RAW image 10565 formats. 10566 </details> 10567 <hal_details> 10568 The lens shading map calculation may depend on exposure and white balance statistics. 10569 When AE and AWB are in AUTO modes 10570 (android.control.aeMode `!=` OFF and android.control.awbMode `!=` OFF), the HAL 10571 may have all the information it need to generate most accurate lens shading map. When 10572 AE or AWB are in manual mode 10573 (android.control.aeMode `==` OFF or android.control.awbMode `==` OFF), the shading map 10574 may be adversely impacted by manual exposure or white balance parameters. To avoid 10575 generating unreliable shading map data, the HAL may choose to lock the shading map with 10576 the latest known good map generated when the AE and AWB are in AUTO modes. 10577 </hal_details> 10578 </entry> 10579 <entry name="predictedColorGains" type="float" 10580 visibility="hidden" 10581 deprecated="true" 10582 optional="true" 10583 type_notes="A 1D array of floats for 4 color channel gains" 10584 container="array"> 10585 <array> 10586 <size>4</size> 10587 </array> 10588 <description>The best-fit color channel gains calculated 10589 by the camera device's statistics units for the current output frame. 10590 </description> 10591 <deprecation_description> 10592 Never fully implemented or specified; do not use 10593 </deprecation_description> 10594 <details> 10595 This may be different than the gains used for this frame, 10596 since statistics processing on data from a new frame 10597 typically completes after the transform has already been 10598 applied to that frame. 10599 10600 The 4 channel gains are defined in Bayer domain, 10601 see android.colorCorrection.gains for details. 10602 10603 This value should always be calculated by the auto-white balance (AWB) block, 10604 regardless of the android.control.* current values. 10605 </details> 10606 </entry> 10607 <entry name="predictedColorTransform" type="rational" 10608 visibility="hidden" 10609 deprecated="true" 10610 optional="true" 10611 type_notes="3x3 rational matrix in row-major order" 10612 container="array"> 10613 <array> 10614 <size>3</size> 10615 <size>3</size> 10616 </array> 10617 <description>The best-fit color transform matrix estimate 10618 calculated by the camera device's statistics units for the current 10619 output frame.</description> 10620 <deprecation_description> 10621 Never fully implemented or specified; do not use 10622 </deprecation_description> 10623 <details>The camera device will provide the estimate from its 10624 statistics unit on the white balance transforms to use 10625 for the next frame. These are the values the camera device believes 10626 are the best fit for the current output frame. This may 10627 be different than the transform used for this frame, since 10628 statistics processing on data from a new frame typically 10629 completes after the transform has already been applied to 10630 that frame. 10631 10632 These estimates must be provided for all frames, even if 10633 capture settings and color transforms are set by the application. 10634 10635 This value should always be calculated by the auto-white balance (AWB) block, 10636 regardless of the android.control.* current values. 10637 </details> 10638 </entry> 10639 <entry name="sceneFlicker" type="byte" visibility="public" enum="true" 10640 hwlevel="full"> 10641 <enum> 10642 <value>NONE 10643 <notes>The camera device does not detect any flickering illumination 10644 in the current scene.</notes></value> 10645 <value>50HZ 10646 <notes>The camera device detects illumination flickering at 50Hz 10647 in the current scene.</notes></value> 10648 <value>60HZ 10649 <notes>The camera device detects illumination flickering at 60Hz 10650 in the current scene.</notes></value> 10651 </enum> 10652 <description>The camera device estimated scene illumination lighting 10653 frequency.</description> 10654 <details> 10655 Many light sources, such as most fluorescent lights, flicker at a rate 10656 that depends on the local utility power standards. This flicker must be 10657 accounted for by auto-exposure routines to avoid artifacts in captured images. 10658 The camera device uses this entry to tell the application what the scene 10659 illuminant frequency is. 10660 10661 When manual exposure control is enabled 10662 (`android.control.aeMode == OFF` or `android.control.mode == 10663 OFF`), the android.control.aeAntibandingMode doesn't perform 10664 antibanding, and the application can ensure it selects 10665 exposure times that do not cause banding issues by looking 10666 into this metadata field. See 10667 android.control.aeAntibandingMode for more details. 10668 10669 Reports NONE if there doesn't appear to be flickering illumination. 10670 </details> 10671 </entry> 10672 <clone entry="android.statistics.hotPixelMapMode" kind="controls"> 10673 </clone> 10674 <entry name="hotPixelMap" type="int32" visibility="public" 10675 type_notes="list of coordinates based on android.sensor.pixelArraySize" 10676 container="array" typedef="point"> 10677 <array> 10678 <size>2</size> 10679 <size>n</size> 10680 </array> 10681 <description> 10682 List of `(x, y)` coordinates of hot/defective pixels on the sensor. 10683 </description> 10684 <range> 10685 n <= number of pixels on the sensor. 10686 The `(x, y)` coordinates must be bounded by 10687 android.sensor.info.pixelArraySize. 10688 </range> 10689 <details> 10690 A coordinate `(x, y)` must lie between `(0, 0)`, and 10691 `(width - 1, height - 1)` (inclusive), which are the top-left and 10692 bottom-right of the pixel array, respectively. The width and 10693 height dimensions are given in android.sensor.info.pixelArraySize. 10694 This may include hot pixels that lie outside of the active array 10695 bounds given by android.sensor.info.activeArraySize. 10696 </details> 10697 <hal_details> 10698 A hotpixel map contains the coordinates of pixels on the camera 10699 sensor that do report valid values (usually due to defects in 10700 the camera sensor). This includes pixels that are stuck at certain 10701 values, or have a response that does not accuractly encode the 10702 incoming light from the scene. 10703 10704 To avoid performance issues, there should be significantly fewer hot 10705 pixels than actual pixels on the camera sensor. 10706 </hal_details> 10707 <tag id="V1" /> 10708 <tag id="RAW" /> 10709 </entry> 10710 </dynamic> 10711 <controls> 10712 <entry name="lensShadingMapMode" type="byte" visibility="public" enum="true" hwlevel="full"> 10713 <enum> 10714 <value>OFF 10715 <notes>Do not include a lens shading map in the capture result.</notes></value> 10716 <value>ON 10717 <notes>Include a lens shading map in the capture result.</notes></value> 10718 </enum> 10719 <description>Whether the camera device will output the lens 10720 shading map in output result metadata.</description> 10721 <range>android.statistics.info.availableLensShadingMapModes</range> 10722 <details>When set to ON, 10723 android.statistics.lensShadingMap will be provided in 10724 the output result metadata. 10725 10726 ON is always supported on devices with the RAW capability. 10727 </details> 10728 <tag id="RAW" /> 10729 </entry> 10730 </controls> 10731 <dynamic> 10732 <clone entry="android.statistics.lensShadingMapMode" kind="controls"> 10733 </clone> 10734 </dynamic> 10735 <controls> 10736 <entry name="oisDataMode" type="byte" visibility="public" enum="true" hal_version="3.3"> 10737 <enum> 10738 <value>OFF 10739 <notes>Do not include OIS data in the capture result.</notes></value> 10740 <value>ON 10741 <notes>Include OIS data in the capture result.</notes> 10742 <sdk_notes>android.statistics.oisSamples provides OIS sample data in the 10743 output result metadata. 10744 </sdk_notes> 10745 <ndk_notes>android.statistics.oisTimestamps, android.statistics.oisXShifts, 10746 and android.statistics.oisYShifts provide OIS data in the output result metadata. 10747 </ndk_notes> 10748 </value> 10749 </enum> 10750 <description>A control for selecting whether optical stabilization (OIS) position 10751 information is included in output result metadata.</description> 10752 <range>android.statistics.info.availableOisDataModes</range> 10753 <details> 10754 Since optical image stabilization generally involves motion much faster than the duration 10755 of individual image exposure, multiple OIS samples can be included for a single capture 10756 result. For example, if the OIS reporting operates at 200 Hz, a typical camera operating 10757 at 30fps may have 6-7 OIS samples per capture result. This information can be combined 10758 with the rolling shutter skew to account for lens motion during image exposure in 10759 post-processing algorithms. 10760 </details> 10761 </entry> 10762 </controls> 10763 <dynamic> 10764 <clone entry="android.statistics.oisDataMode" kind="controls"> 10765 </clone> 10766 <entry name="oisTimestamps" type="int64" visibility="ndk_public" container="array" hal_version="3.3"> 10767 <array> 10768 <size>n</size> 10769 </array> 10770 <description> 10771 An array of timestamps of OIS samples, in nanoseconds. 10772 </description> 10773 <units>nanoseconds</units> 10774 <details> 10775 The array contains the timestamps of OIS samples. The timestamps are in the same 10776 timebase as and comparable to android.sensor.timestamp. 10777 </details> 10778 </entry> 10779 <entry name="oisXShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3"> 10780 <array> 10781 <size>n</size> 10782 </array> 10783 <description> 10784 An array of shifts of OIS samples, in x direction. 10785 </description> 10786 <units>Pixels in active array.</units> 10787 <details> 10788 The array contains the amount of shifts in x direction, in pixels, based on OIS samples. 10789 A positive value is a shift from left to right in the pre-correction active array 10790 coordinate system. For example, if the optical center is (1000, 500) in pre-correction 10791 active array coordinates, a shift of (3, 0) puts the new optical center at (1003, 500). 10792 10793 The number of shifts must match the number of timestamps in 10794 android.statistics.oisTimestamps. 10795 10796 The OIS samples are not affected by whether lens distortion correction is enabled (on 10797 supporting devices). They are always reported in pre-correction active array coordinates, 10798 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 10799 is needed. 10800 </details> 10801 </entry> 10802 <entry name="oisYShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3"> 10803 <array> 10804 <size>n</size> 10805 </array> 10806 <description> 10807 An array of shifts of OIS samples, in y direction. 10808 </description> 10809 <units>Pixels in active array.</units> 10810 <details> 10811 The array contains the amount of shifts in y direction, in pixels, based on OIS samples. 10812 A positive value is a shift from top to bottom in pre-correction active array coordinate 10813 system. For example, if the optical center is (1000, 500) in active array coordinates, a 10814 shift of (0, 5) puts the new optical center at (1000, 505). 10815 10816 The number of shifts must match the number of timestamps in 10817 android.statistics.oisTimestamps. 10818 10819 The OIS samples are not affected by whether lens distortion correction is enabled (on 10820 supporting devices). They are always reported in pre-correction active array coordinates, 10821 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 10822 is needed. 10823 </details> 10824 </entry> 10825 <entry name="oisSamples" type="float" visibility="java_public" synthetic="true" 10826 container="array" typedef="oisSample" hal_version="3.3"> 10827 <array> 10828 <size>n</size> 10829 </array> 10830 <description> 10831 An array of optical stabilization (OIS) position samples. 10832 </description> 10833 <details> 10834 Each OIS sample contains the timestamp and the amount of shifts in x and y direction, 10835 in pixels, of the OIS sample. 10836 10837 A positive value for a shift in x direction is a shift from left to right in the 10838 pre-correction active array coordinate system. For example, if the optical center is 10839 (1000, 500) in pre-correction active array coordinates, a shift of (3, 0) puts the new 10840 optical center at (1003, 500). 10841 10842 A positive value for a shift in y direction is a shift from top to bottom in 10843 pre-correction active array coordinate system. For example, if the optical center is 10844 (1000, 500) in active array coordinates, a shift of (0, 5) puts the new optical center at 10845 (1000, 505). 10846 10847 The OIS samples are not affected by whether lens distortion correction is enabled (on 10848 supporting devices). They are always reported in pre-correction active array coordinates, 10849 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 10850 is needed. 10851 </details> 10852 </entry> 10853 </dynamic> 10854 </section> 10855 <section name="tonemap"> 10856 <controls> 10857 <entry name="curveBlue" type="float" visibility="ndk_public" 10858 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 10859 container="array" hwlevel="full"> 10860 <array> 10861 <size>n</size> 10862 <size>2</size> 10863 </array> 10864 <description>Tonemapping / contrast / gamma curve for the blue 10865 channel, to use when android.tonemap.mode is 10866 CONTRAST_CURVE.</description> 10867 <details>See android.tonemap.curveRed for more details.</details> 10868 </entry> 10869 <entry name="curveGreen" type="float" visibility="ndk_public" 10870 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 10871 container="array" hwlevel="full"> 10872 <array> 10873 <size>n</size> 10874 <size>2</size> 10875 </array> 10876 <description>Tonemapping / contrast / gamma curve for the green 10877 channel, to use when android.tonemap.mode is 10878 CONTRAST_CURVE.</description> 10879 <details>See android.tonemap.curveRed for more details.</details> 10880 </entry> 10881 <entry name="curveRed" type="float" visibility="ndk_public" 10882 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 10883 container="array" hwlevel="full"> 10884 <array> 10885 <size>n</size> 10886 <size>2</size> 10887 </array> 10888 <description>Tonemapping / contrast / gamma curve for the red 10889 channel, to use when android.tonemap.mode is 10890 CONTRAST_CURVE.</description> 10891 <range>0-1 on both input and output coordinates, normalized 10892 as a floating-point value such that 0 == black and 1 == white. 10893 </range> 10894 <details> 10895 Each channel's curve is defined by an array of control points: 10896 10897 android.tonemap.curveRed = 10898 [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ] 10899 2 <= N <= android.tonemap.maxCurvePoints 10900 10901 These are sorted in order of increasing `Pin`; it is 10902 required that input values 0.0 and 1.0 are included in the list to 10903 define a complete mapping. For input values between control points, 10904 the camera device must linearly interpolate between the control 10905 points. 10906 10907 Each curve can have an independent number of points, and the number 10908 of points can be less than max (that is, the request doesn't have to 10909 always provide a curve with number of points equivalent to 10910 android.tonemap.maxCurvePoints). 10911 10912 For devices with MONOCHROME capability, all three channels must have the same set of 10913 control points. 10914 10915 A few examples, and their corresponding graphical mappings; these 10916 only specify the red channel and the precision is limited to 4 10917 digits, for conciseness. 10918 10919 Linear mapping: 10920 10921 android.tonemap.curveRed = [ 0, 0, 1.0, 1.0 ] 10922 10923  10924 10925 Invert mapping: 10926 10927 android.tonemap.curveRed = [ 0, 1.0, 1.0, 0 ] 10928 10929  10930 10931 Gamma 1/2.2 mapping, with 16 control points: 10932 10933 android.tonemap.curveRed = [ 10934 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812, 10935 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072, 10936 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685, 10937 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ] 10938 10939  10940 10941 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 10942 10943 android.tonemap.curveRed = [ 10944 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845, 10945 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130, 10946 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721, 10947 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ] 10948 10949  10950 </details> 10951 <hal_details> 10952 For good quality of mapping, at least 128 control points are 10953 preferred. 10954 10955 A typical use case of this would be a gamma-1/2.2 curve, with as many 10956 control points used as are available. 10957 </hal_details> 10958 </entry> 10959 <entry name="curve" type="float" visibility="java_public" synthetic="true" 10960 typedef="tonemapCurve" 10961 hwlevel="full"> 10962 <description>Tonemapping / contrast / gamma curve to use when android.tonemap.mode 10963 is CONTRAST_CURVE.</description> 10964 <details> 10965 The tonemapCurve consist of three curves for each of red, green, and blue 10966 channels respectively. The following example uses the red channel as an 10967 example. The same logic applies to green and blue channel. 10968 Each channel's curve is defined by an array of control points: 10969 10970 curveRed = 10971 [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ] 10972 2 <= N <= android.tonemap.maxCurvePoints 10973 10974 These are sorted in order of increasing `Pin`; it is always 10975 guaranteed that input values 0.0 and 1.0 are included in the list to 10976 define a complete mapping. For input values between control points, 10977 the camera device must linearly interpolate between the control 10978 points. 10979 10980 Each curve can have an independent number of points, and the number 10981 of points can be less than max (that is, the request doesn't have to 10982 always provide a curve with number of points equivalent to 10983 android.tonemap.maxCurvePoints). 10984 10985 For devices with MONOCHROME capability, all three channels must have the same set of 10986 control points. 10987 10988 A few examples, and their corresponding graphical mappings; these 10989 only specify the red channel and the precision is limited to 4 10990 digits, for conciseness. 10991 10992 Linear mapping: 10993 10994 curveRed = [ (0, 0), (1.0, 1.0) ] 10995 10996  10997 10998 Invert mapping: 10999 11000 curveRed = [ (0, 1.0), (1.0, 0) ] 11001 11002  11003 11004 Gamma 1/2.2 mapping, with 16 control points: 11005 11006 curveRed = [ 11007 (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812), 11008 (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072), 11009 (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685), 11010 (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ] 11011 11012  11013 11014 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 11015 11016 curveRed = [ 11017 (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845), 11018 (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130), 11019 (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721), 11020 (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ] 11021 11022  11023 </details> 11024 <hal_details> 11025 This entry is created by the framework from the curveRed, curveGreen and 11026 curveBlue entries. 11027 </hal_details> 11028 </entry> 11029 <entry name="mode" type="byte" visibility="public" enum="true" 11030 hwlevel="full"> 11031 <enum> 11032 <value>CONTRAST_CURVE 11033 <notes>Use the tone mapping curve specified in 11034 the android.tonemap.curve* entries. 11035 11036 All color enhancement and tonemapping must be disabled, except 11037 for applying the tonemapping curve specified by 11038 android.tonemap.curve. 11039 11040 Must not slow down frame rate relative to raw 11041 sensor output. 11042 </notes> 11043 </value> 11044 <value>FAST 11045 <notes> 11046 Advanced gamma mapping and color enhancement may be applied, without 11047 reducing frame rate compared to raw sensor output. 11048 </notes> 11049 </value> 11050 <value>HIGH_QUALITY 11051 <notes> 11052 High-quality gamma mapping and color enhancement will be applied, at 11053 the cost of possibly reduced frame rate compared to raw sensor output. 11054 </notes> 11055 </value> 11056 <value>GAMMA_VALUE 11057 <notes> 11058 Use the gamma value specified in android.tonemap.gamma to peform 11059 tonemapping. 11060 11061 All color enhancement and tonemapping must be disabled, except 11062 for applying the tonemapping curve specified by android.tonemap.gamma. 11063 11064 Must not slow down frame rate relative to raw sensor output. 11065 </notes> 11066 </value> 11067 <value>PRESET_CURVE 11068 <notes> 11069 Use the preset tonemapping curve specified in 11070 android.tonemap.presetCurve to peform tonemapping. 11071 11072 All color enhancement and tonemapping must be disabled, except 11073 for applying the tonemapping curve specified by 11074 android.tonemap.presetCurve. 11075 11076 Must not slow down frame rate relative to raw sensor output. 11077 </notes> 11078 </value> 11079 </enum> 11080 <description>High-level global contrast/gamma/tonemapping control. 11081 </description> 11082 <range>android.tonemap.availableToneMapModes</range> 11083 <details> 11084 When switching to an application-defined contrast curve by setting 11085 android.tonemap.mode to CONTRAST_CURVE, the curve is defined 11086 per-channel with a set of `(in, out)` points that specify the 11087 mapping from input high-bit-depth pixel value to the output 11088 low-bit-depth value. Since the actual pixel ranges of both input 11089 and output may change depending on the camera pipeline, the values 11090 are specified by normalized floating-point numbers. 11091 11092 More-complex color mapping operations such as 3D color look-up 11093 tables, selective chroma enhancement, or other non-linear color 11094 transforms will be disabled when android.tonemap.mode is 11095 CONTRAST_CURVE. 11096 11097 When using either FAST or HIGH_QUALITY, the camera device will 11098 emit its own tonemap curve in android.tonemap.curve. 11099 These values are always available, and as close as possible to the 11100 actually used nonlinear/nonglobal transforms. 11101 11102 If a request is sent with CONTRAST_CURVE with the camera device's 11103 provided curve in FAST or HIGH_QUALITY, the image's tonemap will be 11104 roughly the same.</details> 11105 </entry> 11106 </controls> 11107 <static> 11108 <entry name="maxCurvePoints" type="int32" visibility="public" 11109 hwlevel="full"> 11110 <description>Maximum number of supported points in the 11111 tonemap curve that can be used for android.tonemap.curve. 11112 </description> 11113 <details> 11114 If the actual number of points provided by the application (in android.tonemap.curve*) is 11115 less than this maximum, the camera device will resample the curve to its internal 11116 representation, using linear interpolation. 11117 11118 The output curves in the result metadata may have a different number 11119 of points than the input curves, and will represent the actual 11120 hardware curves used as closely as possible when linearly interpolated. 11121 </details> 11122 <hal_details> 11123 This value must be at least 64. This should be at least 128. 11124 </hal_details> 11125 </entry> 11126 <entry name="availableToneMapModes" type="byte" visibility="public" 11127 type_notes="list of enums" container="array" typedef="enumList" hwlevel="full"> 11128 <array> 11129 <size>n</size> 11130 </array> 11131 <description> 11132 List of tonemapping modes for android.tonemap.mode that are supported by this camera 11133 device. 11134 </description> 11135 <range>Any value listed in android.tonemap.mode</range> 11136 <details> 11137 Camera devices that support the MANUAL_POST_PROCESSING capability will always contain 11138 at least one of below mode combinations: 11139 11140 * CONTRAST_CURVE, FAST and HIGH_QUALITY 11141 * GAMMA_VALUE, PRESET_CURVE, FAST and HIGH_QUALITY 11142 11143 This includes all FULL level devices. 11144 </details> 11145 <hal_details> 11146 HAL must support both FAST and HIGH_QUALITY if automatic tonemap control is available 11147 on the camera device, but the underlying implementation can be the same for both modes. 11148 That is, if the highest quality implementation on the camera device does not slow down 11149 capture rate, then FAST and HIGH_QUALITY will generate the same output. 11150 </hal_details> 11151 </entry> 11152 </static> 11153 <dynamic> 11154 <clone entry="android.tonemap.curveBlue" kind="controls"> 11155 </clone> 11156 <clone entry="android.tonemap.curveGreen" kind="controls"> 11157 </clone> 11158 <clone entry="android.tonemap.curveRed" kind="controls"> 11159 </clone> 11160 <clone entry="android.tonemap.curve" kind="controls"> 11161 </clone> 11162 <clone entry="android.tonemap.mode" kind="controls"> 11163 </clone> 11164 </dynamic> 11165 <controls> 11166 <entry name="gamma" type="float" visibility="public"> 11167 <description> Tonemapping curve to use when android.tonemap.mode is 11168 GAMMA_VALUE 11169 </description> 11170 <details> 11171 The tonemap curve will be defined the following formula: 11172 * OUT = pow(IN, 1.0 / gamma) 11173 where IN and OUT is the input pixel value scaled to range [0.0, 1.0], 11174 pow is the power function and gamma is the gamma value specified by this 11175 key. 11176 11177 The same curve will be applied to all color channels. The camera device 11178 may clip the input gamma value to its supported range. The actual applied 11179 value will be returned in capture result. 11180 11181 The valid range of gamma value varies on different devices, but values 11182 within [1.0, 5.0] are guaranteed not to be clipped. 11183 </details> 11184 </entry> 11185 <entry name="presetCurve" type="byte" visibility="public" enum="true"> 11186 <enum> 11187 <value>SRGB 11188 <notes>Tonemapping curve is defined by sRGB</notes> 11189 </value> 11190 <value>REC709 11191 <notes>Tonemapping curve is defined by ITU-R BT.709</notes> 11192 </value> 11193 </enum> 11194 <description> Tonemapping curve to use when android.tonemap.mode is 11195 PRESET_CURVE 11196 </description> 11197 <details> 11198 The tonemap curve will be defined by specified standard. 11199 11200 sRGB (approximated by 16 control points): 11201 11202  11203 11204 Rec. 709 (approximated by 16 control points): 11205 11206  11207 11208 Note that above figures show a 16 control points approximation of preset 11209 curves. Camera devices may apply a different approximation to the curve. 11210 </details> 11211 </entry> 11212 </controls> 11213 <dynamic> 11214 <clone entry="android.tonemap.gamma" kind="controls"> 11215 </clone> 11216 <clone entry="android.tonemap.presetCurve" kind="controls"> 11217 </clone> 11218 </dynamic> 11219 </section> 11220 <section name="led"> 11221 <controls> 11222 <entry name="transmit" type="byte" visibility="hidden" optional="true" 11223 enum="true" typedef="boolean"> 11224 <enum> 11225 <value>OFF</value> 11226 <value>ON</value> 11227 </enum> 11228 <description>This LED is nominally used to indicate to the user 11229 that the camera is powered on and may be streaming images back to the 11230 Application Processor. In certain rare circumstances, the OS may 11231 disable this when video is processed locally and not transmitted to 11232 any untrusted applications. 11233 11234 In particular, the LED *must* always be on when the data could be 11235 transmitted off the device. The LED *should* always be on whenever 11236 data is stored locally on the device. 11237 11238 The LED *may* be off if a trusted application is using the data that 11239 doesn't violate the above rules. 11240 </description> 11241 </entry> 11242 </controls> 11243 <dynamic> 11244 <clone entry="android.led.transmit" kind="controls"></clone> 11245 </dynamic> 11246 <static> 11247 <entry name="availableLeds" type="byte" visibility="hidden" optional="true" 11248 enum="true" 11249 container="array"> 11250 <array> 11251 <size>n</size> 11252 </array> 11253 <enum> 11254 <value>TRANSMIT 11255 <notes>android.led.transmit control is used.</notes> 11256 </value> 11257 </enum> 11258 <description>A list of camera LEDs that are available on this system. 11259 </description> 11260 </entry> 11261 </static> 11262 </section> 11263 <section name="info"> 11264 <static> 11265 <entry name="supportedHardwareLevel" type="byte" visibility="public" 11266 enum="true" hwlevel="legacy"> 11267 <enum> 11268 <value> 11269 LIMITED 11270 <notes> 11271 This camera device does not have enough capabilities to qualify as a `FULL` device or 11272 better. 11273 11274 Only the stream configurations listed in the `LEGACY` and `LIMITED` tables in the 11275 {@link android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession 11276 createCaptureSession} documentation are guaranteed to be supported. 11277 11278 All `LIMITED` devices support the `BACKWARDS_COMPATIBLE` capability, indicating basic 11279 support for color image capture. The only exception is that the device may 11280 alternatively support only the `DEPTH_OUTPUT` capability, if it can only output depth 11281 measurements and not color images. 11282 11283 `LIMITED` devices and above require the use of android.control.aePrecaptureTrigger 11284 to lock exposure metering (and calculate flash power, for cameras with flash) before 11285 capturing a high-quality still image. 11286 11287 A `LIMITED` device that only lists the `BACKWARDS_COMPATIBLE` capability is only 11288 required to support full-automatic operation and post-processing (`OFF` is not 11289 supported for android.control.aeMode, android.control.afMode, or 11290 android.control.awbMode) 11291 11292 Additional capabilities may optionally be supported by a `LIMITED`-level device, and 11293 can be checked for in android.request.availableCapabilities. 11294 </notes> 11295 </value> 11296 <value> 11297 FULL 11298 <notes> 11299 This camera device is capable of supporting advanced imaging applications. 11300 11301 The stream configurations listed in the `FULL`, `LEGACY` and `LIMITED` tables in the 11302 {@link android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession 11303 createCaptureSession} documentation are guaranteed to be supported. 11304 11305 A `FULL` device will support below capabilities: 11306 11307 * `BURST_CAPTURE` capability (android.request.availableCapabilities contains 11308 `BURST_CAPTURE`) 11309 * Per frame control (android.sync.maxLatency `==` PER_FRAME_CONTROL) 11310 * Manual sensor control (android.request.availableCapabilities contains `MANUAL_SENSOR`) 11311 * Manual post-processing control (android.request.availableCapabilities contains 11312 `MANUAL_POST_PROCESSING`) 11313 * The required exposure time range defined in android.sensor.info.exposureTimeRange 11314 * The required maxFrameDuration defined in android.sensor.info.maxFrameDuration 11315 11316 Note: 11317 Pre-API level 23, FULL devices also supported arbitrary cropping region 11318 (android.scaler.croppingType `== FREEFORM`); this requirement was relaxed in API level 11319 23, and `FULL` devices may only support `CENTERED` cropping. 11320 </notes> 11321 </value> 11322 <value> 11323 LEGACY 11324 <notes> 11325 This camera device is running in backward compatibility mode. 11326 11327 Only the stream configurations listed in the `LEGACY` table in the {@link 11328 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession 11329 createCaptureSession} documentation are supported. 11330 11331 A `LEGACY` device does not support per-frame control, manual sensor control, manual 11332 post-processing, arbitrary cropping regions, and has relaxed performance constraints. 11333 No additional capabilities beyond `BACKWARD_COMPATIBLE` will ever be listed by a 11334 `LEGACY` device in android.request.availableCapabilities. 11335 11336 In addition, the android.control.aePrecaptureTrigger is not functional on `LEGACY` 11337 devices. Instead, every request that includes a JPEG-format output target is treated 11338 as triggering a still capture, internally executing a precapture trigger. This may 11339 fire the flash for flash power metering during precapture, and then fire the flash 11340 for the final capture, if a flash is available on the device and the AE mode is set to 11341 enable the flash. 11342 11343 Devices that initially shipped with Android version {@link 11344 android.os.Build.VERSION_CODES#Q Q} or newer will not include any LEGACY-level devices. 11345 </notes> 11346 </value> 11347 <value> 11348 3 11349 <notes> 11350 This camera device is capable of YUV reprocessing and RAW data capture, in addition to 11351 FULL-level capabilities. 11352 11353 The stream configurations listed in the `LEVEL_3`, `RAW`, `FULL`, `LEGACY` and 11354 `LIMITED` tables in the {@link 11355 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession 11356 createCaptureSession} documentation are guaranteed to be supported. 11357 11358 The following additional capabilities are guaranteed to be supported: 11359 11360 * `YUV_REPROCESSING` capability (android.request.availableCapabilities contains 11361 `YUV_REPROCESSING`) 11362 * `RAW` capability (android.request.availableCapabilities contains 11363 `RAW`) 11364 </notes> 11365 </value> 11366 <value hal_version="3.3"> 11367 EXTERNAL 11368 <notes> 11369 This camera device is backed by an external camera connected to this Android device. 11370 11371 The device has capability identical to a LIMITED level device, with the following 11372 exceptions: 11373 11374 * The device may not report lens/sensor related information such as 11375 - android.lens.focalLength 11376 - android.lens.info.hyperfocalDistance 11377 - android.sensor.info.physicalSize 11378 - android.sensor.info.whiteLevel 11379 - android.sensor.blackLevelPattern 11380 - android.sensor.info.colorFilterArrangement 11381 - android.sensor.rollingShutterSkew 11382 * The device will report 0 for android.sensor.orientation 11383 * The device has less guarantee on stable framerate, as the framerate partly depends 11384 on the external camera being used. 11385 </notes> 11386 </value> 11387 </enum> 11388 <description> 11389 Generally classifies the overall set of the camera device functionality. 11390 </description> 11391 <details> 11392 The supported hardware level is a high-level description of the camera device's 11393 capabilities, summarizing several capabilities into one field. Each level adds additional 11394 features to the previous one, and is always a strict superset of the previous level. 11395 The ordering is `LEGACY < LIMITED < FULL < LEVEL_3`. 11396 11397 Starting from `LEVEL_3`, the level enumerations are guaranteed to be in increasing 11398 numerical value as well. To check if a given device is at least at a given hardware level, 11399 the following code snippet can be used: 11400 11401 // Returns true if the device supports the required hardware level, or better. 11402 boolean isHardwareLevelSupported(CameraCharacteristics c, int requiredLevel) { 11403 final int[] sortedHwLevels = { 11404 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, 11405 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, 11406 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, 11407 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, 11408 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 11409 }; 11410 int deviceLevel = c.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL); 11411 if (requiredLevel == deviceLevel) { 11412 return true; 11413 } 11414 11415 for (int sortedlevel : sortedHwLevels) { 11416 if (sortedlevel == requiredLevel) { 11417 return true; 11418 } else if (sortedlevel == deviceLevel) { 11419 return false; 11420 } 11421 } 11422 return false; // Should never reach here 11423 } 11424 11425 At a high level, the levels are: 11426 11427 * `LEGACY` devices operate in a backwards-compatibility mode for older 11428 Android devices, and have very limited capabilities. 11429 * `LIMITED` devices represent the 11430 baseline feature set, and may also include additional capabilities that are 11431 subsets of `FULL`. 11432 * `FULL` devices additionally support per-frame manual control of sensor, flash, lens and 11433 post-processing settings, and image capture at a high rate. 11434 * `LEVEL_3` devices additionally support YUV reprocessing and RAW image capture, along 11435 with additional output stream configurations. 11436 * `EXTERNAL` devices are similar to `LIMITED` devices with exceptions like some sensor or 11437 lens information not reported or less stable framerates. 11438 11439 See the individual level enums for full descriptions of the supported capabilities. The 11440 android.request.availableCapabilities entry describes the device's capabilities at a 11441 finer-grain level, if needed. In addition, many controls have their available settings or 11442 ranges defined in individual entries from {@link 11443 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics}. 11444 11445 Some features are not part of any particular hardware level or capability and must be 11446 queried separately. These include: 11447 11448 * Calibrated timestamps (android.sensor.info.timestampSource `==` REALTIME) 11449 * Precision lens control (android.lens.info.focusDistanceCalibration `==` CALIBRATED) 11450 * Face detection (android.statistics.info.availableFaceDetectModes) 11451 * Optical or electrical image stabilization 11452 (android.lens.info.availableOpticalStabilization, 11453 android.control.availableVideoStabilizationModes) 11454 11455 </details> 11456 <hal_details> 11457 A camera HALv3 device can implement one of three possible operational modes; LIMITED, 11458 FULL, and LEVEL_3. 11459 11460 FULL support or better is expected from new higher-end devices. Limited 11461 mode has hardware requirements roughly in line with those for a camera HAL device v1 11462 implementation, and is expected from older or inexpensive devices. Each level is a strict 11463 superset of the previous level, and they share the same essential operational flow. 11464 11465 For full details refer to "S3. Operational Modes" in camera3.h 11466 11467 Camera HAL3+ must not implement LEGACY mode. It is there for backwards compatibility in 11468 the `android.hardware.camera2` user-facing API only on legacy HALv1 devices, and is 11469 implemented by the camera framework code. 11470 11471 EXTERNAL level devices have lower peformance bar in CTS since the peformance might depend 11472 on the external camera being used and is not fully controlled by the device manufacturer. 11473 The ITS test suite is exempted for the same reason. 11474 </hal_details> 11475 </entry> 11476 <entry name="version" type="byte" visibility="public" typedef="string" hal_version="3.3"> 11477 <description> 11478 A short string for manufacturer version information about the camera device, such as 11479 ISP hardware, sensors, etc. 11480 </description> 11481 <details> 11482 This can be used in {@link android.media.ExifInterface#TAG_IMAGE_DESCRIPTION TAG_IMAGE_DESCRIPTION} 11483 in jpeg EXIF. This key may be absent if no version information is available on the 11484 device. 11485 </details> 11486 <hal_details> 11487 The string must consist of only alphanumeric characters, punctuation, and 11488 whitespace, i.e. it must match regular expression "[\p{Alnum}\p{Punct}\p{Space}]*". 11489 It must not exceed 256 characters. 11490 </hal_details> 11491 </entry> 11492 <entry name="supportedBufferManagementVersion" type="byte" visibility="system" 11493 enum="true" hal_version="3.4"> 11494 <enum> 11495 <value> 11496 HIDL_DEVICE_3_5 11497 <notes> 11498 This camera device supports and opts in to the buffer management APIs provided by 11499 HIDL ICameraDevice version 3.5. 11500 </notes> 11501 </value> 11502 </enum> 11503 <description> 11504 The version of buffer management API this camera device supports and opts into. 11505 </description> 11506 <details> 11507 When this key is not present, camera framework will interact with this camera device 11508 without any buffer management HAL API. When this key is present and camera framework 11509 supports the buffer management API version, camera framework will interact with camera 11510 HAL using such version of buffer management API. 11511 </details> 11512 </entry> 11513 <entry name="deviceStateSensorOrientationMap" type="int64" visibility="java_public" 11514 synthetic="true" optional="true" typedef="deviceStateSensorOrientationMap" 11515 hwlevel="limited"> 11516 <description>This lists the mapping between a device folding state and 11517 specific camera sensor orientation for logical cameras on a foldable device. 11518 </description> 11519 <details> 11520 Logical cameras on foldable devices can support sensors with different orientation 11521 values. The orientation value may need to change depending on the specific folding 11522 state. Information about the mapping between the device folding state and the 11523 sensor orientation can be obtained in 11524 {@link android.hardware.camera2.params.DeviceStateSensorOrientationMap}. 11525 Device state orientation maps are optional and maybe present on devices that support 11526 android.scaler.rotateAndCrop. 11527 </details> 11528 </entry> 11529 <entry name="deviceStateOrientations" type="int64" visibility="ndk_public" 11530 container="array" hwlevel="limited" hal_version="3.7"> 11531 <array> 11532 <size>2</size> 11533 <size>n</size> 11534 </array> 11535 <units>(device fold state, sensor orientation) x n</units> 11536 <details> 11537 HAL must populate the array with 11538 (hardware::camera::provider::V2_5::DeviceState, sensorOrientation) pairs for each 11539 supported device state bitwise combination. 11540 </details> 11541 </entry> 11542 </static> 11543 </section> 11544 <section name="blackLevel"> 11545 <controls> 11546 <entry name="lock" type="byte" visibility="public" enum="true" 11547 typedef="boolean" hwlevel="full"> 11548 <enum> 11549 <value>OFF</value> 11550 <value>ON</value> 11551 </enum> 11552 <description> Whether black-level compensation is locked 11553 to its current values, or is free to vary.</description> 11554 <details>When set to `true` (ON), the values used for black-level 11555 compensation will not change until the lock is set to 11556 `false` (OFF). 11557 11558 Since changes to certain capture parameters (such as 11559 exposure time) may require resetting of black level 11560 compensation, the camera device must report whether setting 11561 the black level lock was successful in the output result 11562 metadata. 11563 11564 For example, if a sequence of requests is as follows: 11565 11566 * Request 1: Exposure = 10ms, Black level lock = OFF 11567 * Request 2: Exposure = 10ms, Black level lock = ON 11568 * Request 3: Exposure = 10ms, Black level lock = ON 11569 * Request 4: Exposure = 20ms, Black level lock = ON 11570 * Request 5: Exposure = 20ms, Black level lock = ON 11571 * Request 6: Exposure = 20ms, Black level lock = ON 11572 11573 And the exposure change in Request 4 requires the camera 11574 device to reset the black level offsets, then the output 11575 result metadata is expected to be: 11576 11577 * Result 1: Exposure = 10ms, Black level lock = OFF 11578 * Result 2: Exposure = 10ms, Black level lock = ON 11579 * Result 3: Exposure = 10ms, Black level lock = ON 11580 * Result 4: Exposure = 20ms, Black level lock = OFF 11581 * Result 5: Exposure = 20ms, Black level lock = ON 11582 * Result 6: Exposure = 20ms, Black level lock = ON 11583 11584 This indicates to the application that on frame 4, black 11585 levels were reset due to exposure value changes, and pixel 11586 values may not be consistent across captures. 11587 11588 The camera device will maintain the lock to the extent 11589 possible, only overriding the lock to OFF when changes to 11590 other request parameters require a black level recalculation 11591 or reset. 11592 </details> 11593 <hal_details> 11594 If for some reason black level locking is no longer possible 11595 (for example, the analog gain has changed, which forces 11596 black level offsets to be recalculated), then the HAL must 11597 override this request (and it must report 'OFF' when this 11598 does happen) until the next capture for which locking is 11599 possible again.</hal_details> 11600 <tag id="HAL2" /> 11601 </entry> 11602 </controls> 11603 <dynamic> 11604 <clone entry="android.blackLevel.lock" 11605 kind="controls"> 11606 <details> 11607 Whether the black level offset was locked for this frame. Should be 11608 ON if android.blackLevel.lock was ON in the capture request, unless 11609 a change in other capture settings forced the camera device to 11610 perform a black level reset. 11611 </details> 11612 </clone> 11613 </dynamic> 11614 </section> 11615 <section name="sync"> 11616 <dynamic> 11617 <entry name="frameNumber" type="int64" visibility="ndk_public" 11618 enum="true" hwlevel="legacy"> 11619 <enum> 11620 <value id="-1">CONVERGING 11621 <notes> 11622 The current result is not yet fully synchronized to any request. 11623 11624 Synchronization is in progress, and reading metadata from this 11625 result may include a mix of data that have taken effect since the 11626 last synchronization time. 11627 11628 In some future result, within android.sync.maxLatency frames, 11629 this value will update to the actual frame number frame number 11630 the result is guaranteed to be synchronized to (as long as the 11631 request settings remain constant). 11632 </notes> 11633 </value> 11634 <value id="-2">UNKNOWN 11635 <notes> 11636 The current result's synchronization status is unknown. 11637 11638 The result may have already converged, or it may be in 11639 progress. Reading from this result may include some mix 11640 of settings from past requests. 11641 11642 After a settings change, the new settings will eventually all 11643 take effect for the output buffers and results. However, this 11644 value will not change when that happens. Altering settings 11645 rapidly may provide outcomes using mixes of settings from recent 11646 requests. 11647 11648 This value is intended primarily for backwards compatibility with 11649 the older camera implementations (for android.hardware.Camera). 11650 </notes> 11651 </value> 11652 </enum> 11653 <description>The frame number corresponding to the last request 11654 with which the output result (metadata + buffers) has been fully 11655 synchronized.</description> 11656 <range>Either a non-negative value corresponding to a 11657 `frame_number`, or one of the two enums (CONVERGING / UNKNOWN). 11658 </range> 11659 <details> 11660 When a request is submitted to the camera device, there is usually a 11661 delay of several frames before the controls get applied. A camera 11662 device may either choose to account for this delay by implementing a 11663 pipeline and carefully submit well-timed atomic control updates, or 11664 it may start streaming control changes that span over several frame 11665 boundaries. 11666 11667 In the latter case, whenever a request's settings change relative to 11668 the previous submitted request, the full set of changes may take 11669 multiple frame durations to fully take effect. Some settings may 11670 take effect sooner (in less frame durations) than others. 11671 11672 While a set of control changes are being propagated, this value 11673 will be CONVERGING. 11674 11675 Once it is fully known that a set of control changes have been 11676 finished propagating, and the resulting updated control settings 11677 have been read back by the camera device, this value will be set 11678 to a non-negative frame number (corresponding to the request to 11679 which the results have synchronized to). 11680 11681 Older camera device implementations may not have a way to detect 11682 when all camera controls have been applied, and will always set this 11683 value to UNKNOWN. 11684 11685 FULL capability devices will always have this value set to the 11686 frame number of the request corresponding to this result. 11687 11688 _Further details_: 11689 11690 * Whenever a request differs from the last request, any future 11691 results not yet returned may have this value set to CONVERGING (this 11692 could include any in-progress captures not yet returned by the camera 11693 device, for more details see pipeline considerations below). 11694 * Submitting a series of multiple requests that differ from the 11695 previous request (e.g. r1, r2, r3 s.t. r1 != r2 != r3) 11696 moves the new synchronization frame to the last non-repeating 11697 request (using the smallest frame number from the contiguous list of 11698 repeating requests). 11699 * Submitting the same request repeatedly will not change this value 11700 to CONVERGING, if it was already a non-negative value. 11701 * When this value changes to non-negative, that means that all of the 11702 metadata controls from the request have been applied, all of the 11703 metadata controls from the camera device have been read to the 11704 updated values (into the result), and all of the graphics buffers 11705 corresponding to this result are also synchronized to the request. 11706 11707 _Pipeline considerations_: 11708 11709 Submitting a request with updated controls relative to the previously 11710 submitted requests may also invalidate the synchronization state 11711 of all the results corresponding to currently in-flight requests. 11712 11713 In other words, results for this current request and up to 11714 android.request.pipelineMaxDepth prior requests may have their 11715 android.sync.frameNumber change to CONVERGING. 11716 </details> 11717 <hal_details> 11718 Using UNKNOWN here is illegal unless android.sync.maxLatency 11719 is also UNKNOWN. 11720 11721 FULL capability devices should simply set this value to the 11722 `frame_number` of the request this result corresponds to. 11723 </hal_details> 11724 <tag id="V1" /> 11725 </entry> 11726 </dynamic> 11727 <static> 11728 <entry name="maxLatency" type="int32" visibility="public" enum="true" 11729 hwlevel="legacy"> 11730 <enum> 11731 <value id="0">PER_FRAME_CONTROL 11732 <notes> 11733 Every frame has the requests immediately applied. 11734 11735 Changing controls over multiple requests one after another will 11736 produce results that have those controls applied atomically 11737 each frame. 11738 11739 All FULL capability devices will have this as their maxLatency. 11740 </notes> 11741 </value> 11742 <value id="-1">UNKNOWN 11743 <notes> 11744 Each new frame has some subset (potentially the entire set) 11745 of the past requests applied to the camera settings. 11746 11747 By submitting a series of identical requests, the camera device 11748 will eventually have the camera settings applied, but it is 11749 unknown when that exact point will be. 11750 11751 All LEGACY capability devices will have this as their maxLatency. 11752 </notes> 11753 </value> 11754 </enum> 11755 <description> 11756 The maximum number of frames that can occur after a request 11757 (different than the previous) has been submitted, and before the 11758 result's state becomes synchronized. 11759 </description> 11760 <units>Frame counts</units> 11761 <range>A positive value, PER_FRAME_CONTROL, or UNKNOWN.</range> 11762 <details> 11763 This defines the maximum distance (in number of metadata results), 11764 between the frame number of the request that has new controls to apply 11765 and the frame number of the result that has all the controls applied. 11766 11767 In other words this acts as an upper boundary for how many frames 11768 must occur before the camera device knows for a fact that the new 11769 submitted camera settings have been applied in outgoing frames. 11770 </details> 11771 <hal_details> 11772 For example if maxLatency was 2, 11773 11774 initial request = X (repeating) 11775 request1 = X 11776 request2 = Y 11777 request3 = Y 11778 request4 = Y 11779 11780 where requestN has frameNumber N, and the first of the repeating 11781 initial request's has frameNumber F (and F < 1). 11782 11783 initial result = X' + { android.sync.frameNumber == F } 11784 result1 = X' + { android.sync.frameNumber == F } 11785 result2 = X' + { android.sync.frameNumber == CONVERGING } 11786 result3 = X' + { android.sync.frameNumber == CONVERGING } 11787 result4 = X' + { android.sync.frameNumber == 2 } 11788 11789 where resultN has frameNumber N. 11790 11791 Since `result4` has a `frameNumber == 4` and 11792 `android.sync.frameNumber == 2`, the distance is clearly 11793 `4 - 2 = 2`. 11794 11795 Use `frame_count` from camera3_request_t instead of 11796 android.request.frameCount or 11797 `{@link android.hardware.camera2.CaptureResult#getFrameNumber}`. 11798 11799 LIMITED devices are strongly encouraged to use a non-negative 11800 value. If UNKNOWN is used here then app developers do not have a way 11801 to know when sensor settings have been applied. 11802 </hal_details> 11803 <tag id="V1" /> 11804 </entry> 11805 </static> 11806 </section> 11807 <section name="reprocess"> 11808 <controls> 11809 <entry name="effectiveExposureFactor" type="float" visibility="java_public" hwlevel="limited"> 11810 <description> 11811 The amount of exposure time increase factor applied to the original output 11812 frame by the application processing before sending for reprocessing. 11813 </description> 11814 <units>Relative exposure time increase factor.</units> 11815 <range> &gt;= 1.0</range> 11816 <details> 11817 This is optional, and will be supported if the camera device supports YUV_REPROCESSING 11818 capability (android.request.availableCapabilities contains YUV_REPROCESSING). 11819 11820 For some YUV reprocessing use cases, the application may choose to filter the original 11821 output frames to effectively reduce the noise to the same level as a frame that was 11822 captured with longer exposure time. To be more specific, assuming the original captured 11823 images were captured with a sensitivity of S and an exposure time of T, the model in 11824 the camera device is that the amount of noise in the image would be approximately what 11825 would be expected if the original capture parameters had been a sensitivity of 11826 S/effectiveExposureFactor and an exposure time of T*effectiveExposureFactor, rather 11827 than S and T respectively. If the captured images were processed by the application 11828 before being sent for reprocessing, then the application may have used image processing 11829 algorithms and/or multi-frame image fusion to reduce the noise in the 11830 application-processed images (input images). By using the effectiveExposureFactor 11831 control, the application can communicate to the camera device the actual noise level 11832 improvement in the application-processed image. With this information, the camera 11833 device can select appropriate noise reduction and edge enhancement parameters to avoid 11834 excessive noise reduction (android.noiseReduction.mode) and insufficient edge 11835 enhancement (android.edge.mode) being applied to the reprocessed frames. 11836 11837 For example, for multi-frame image fusion use case, the application may fuse 11838 multiple output frames together to a final frame for reprocessing. When N image are 11839 fused into 1 image for reprocessing, the exposure time increase factor could be up to 11840 square root of N (based on a simple photon shot noise model). The camera device will 11841 adjust the reprocessing noise reduction and edge enhancement parameters accordingly to 11842 produce the best quality images. 11843 11844 This is relative factor, 1.0 indicates the application hasn't processed the input 11845 buffer in a way that affects its effective exposure time. 11846 11847 This control is only effective for YUV reprocessing capture request. For noise 11848 reduction reprocessing, it is only effective when `android.noiseReduction.mode != OFF`. 11849 Similarly, for edge enhancement reprocessing, it is only effective when 11850 `android.edge.mode != OFF`. 11851 </details> 11852 <tag id="REPROC" /> 11853 </entry> 11854 </controls> 11855 <dynamic> 11856 <clone entry="android.reprocess.effectiveExposureFactor" kind="controls"> 11857 </clone> 11858 </dynamic> 11859 <static> 11860 <entry name="maxCaptureStall" type="int32" visibility="java_public" hwlevel="limited"> 11861 <description> 11862 The maximal camera capture pipeline stall (in unit of frame count) introduced by a 11863 reprocess capture request. 11864 </description> 11865 <units>Number of frames.</units> 11866 <range> &lt;= 4</range> 11867 <details> 11868 The key describes the maximal interference that one reprocess (input) request 11869 can introduce to the camera simultaneous streaming of regular (output) capture 11870 requests, including repeating requests. 11871 11872 When a reprocessing capture request is submitted while a camera output repeating request 11873 (e.g. preview) is being served by the camera device, it may preempt the camera capture 11874 pipeline for at least one frame duration so that the camera device is unable to process 11875 the following capture request in time for the next sensor start of exposure boundary. 11876 When this happens, the application may observe a capture time gap (longer than one frame 11877 duration) between adjacent capture output frames, which usually exhibits as preview 11878 glitch if the repeating request output targets include a preview surface. This key gives 11879 the worst-case number of frame stall introduced by one reprocess request with any kind of 11880 formats/sizes combination. 11881 11882 If this key reports 0, it means a reprocess request doesn't introduce any glitch to the 11883 ongoing camera repeating request outputs, as if this reprocess request is never issued. 11884 11885 This key is supported if the camera device supports PRIVATE or YUV reprocessing ( 11886 i.e. android.request.availableCapabilities contains PRIVATE_REPROCESSING or 11887 YUV_REPROCESSING). 11888 </details> 11889 <tag id="REPROC" /> 11890 </entry> 11891 </static> 11892 </section> 11893 <section name="depth"> 11894 <static> 11895 <entry name="maxDepthSamples" type="int32" visibility="system" hwlevel="limited"> 11896 <description>Maximum number of points that a depth point cloud may contain. 11897 </description> 11898 <details> 11899 If a camera device supports outputting depth range data in the form of a depth point 11900 cloud ({@link android.graphics.ImageFormat#DEPTH_POINT_CLOUD}), this is the maximum 11901 number of points an output buffer may contain. 11902 11903 Any given buffer may contain between 0 and maxDepthSamples points, inclusive. 11904 If output in the depth point cloud format is not supported, this entry will 11905 not be defined. 11906 </details> 11907 <tag id="DEPTH" /> 11908 </entry> 11909 <entry name="availableDepthStreamConfigurations" type="int32" visibility="ndk_public" 11910 enum="true" container="array" typedef="streamConfiguration" hwlevel="limited"> 11911 <array> 11912 <size>n</size> 11913 <size>4</size> 11914 </array> 11915 <enum> 11916 <value>OUTPUT</value> 11917 <value>INPUT</value> 11918 </enum> 11919 <description>The available depth dataspace stream 11920 configurations that this camera device supports 11921 (i.e. format, width, height, output/input stream). 11922 </description> 11923 <details> 11924 These are output stream configurations for use with 11925 dataSpace HAL_DATASPACE_DEPTH. The configurations are 11926 listed as `(format, width, height, input?)` tuples. 11927 11928 Only devices that support depth output for at least 11929 the HAL_PIXEL_FORMAT_Y16 dense depth map may include 11930 this entry. 11931 11932 A device that also supports the HAL_PIXEL_FORMAT_BLOB 11933 sparse depth point cloud must report a single entry for 11934 the format in this list as `(HAL_PIXEL_FORMAT_BLOB, 11935 android.depth.maxDepthSamples, 1, OUTPUT)` in addition to 11936 the entries for HAL_PIXEL_FORMAT_Y16. 11937 </details> 11938 <tag id="DEPTH" /> 11939 </entry> 11940 <entry name="availableDepthMinFrameDurations" type="int64" visibility="ndk_public" 11941 container="array" typedef="streamConfigurationDuration" hwlevel="limited"> 11942 <array> 11943 <size>4</size> 11944 <size>n</size> 11945 </array> 11946 <description>This lists the minimum frame duration for each 11947 format/size combination for depth output formats. 11948 </description> 11949 <units>(format, width, height, ns) x n</units> 11950 <details> 11951 This should correspond to the frame duration when only that 11952 stream is active, with all processing (typically in android.*.mode) 11953 set to either OFF or FAST. 11954 11955 When multiple streams are used in a request, the minimum frame 11956 duration will be max(individual stream min durations). 11957 11958 The minimum frame duration of a stream (of a particular format, size) 11959 is the same regardless of whether the stream is input or output. 11960 11961 See android.sensor.frameDuration and 11962 android.scaler.availableStallDurations for more details about 11963 calculating the max frame rate. 11964 </details> 11965 <tag id="DEPTH" /> 11966 </entry> 11967 <entry name="availableDepthStallDurations" type="int64" visibility="ndk_public" 11968 container="array" typedef="streamConfigurationDuration" hwlevel="limited"> 11969 <array> 11970 <size>4</size> 11971 <size>n</size> 11972 </array> 11973 <description>This lists the maximum stall duration for each 11974 output format/size combination for depth streams. 11975 </description> 11976 <units>(format, width, height, ns) x n</units> 11977 <details> 11978 A stall duration is how much extra time would get added 11979 to the normal minimum frame duration for a repeating request 11980 that has streams with non-zero stall. 11981 11982 This functions similarly to 11983 android.scaler.availableStallDurations for depth 11984 streams. 11985 11986 All depth output stream formats may have a nonzero stall 11987 duration. 11988 </details> 11989 <tag id="DEPTH" /> 11990 </entry> 11991 <entry name="depthIsExclusive" type="byte" visibility="public" 11992 enum="true" typedef="boolean" hwlevel="limited"> 11993 <enum> 11994 <value>FALSE</value> 11995 <value>TRUE</value> 11996 </enum> 11997 <description>Indicates whether a capture request may target both a 11998 DEPTH16 / DEPTH_POINT_CLOUD output, and normal color outputs (such as 11999 YUV_420_888, JPEG, or RAW) simultaneously. 12000 </description> 12001 <details> 12002 If TRUE, including both depth and color outputs in a single 12003 capture request is not supported. An application must interleave color 12004 and depth requests. If FALSE, a single request can target both types 12005 of output. 12006 12007 Typically, this restriction exists on camera devices that 12008 need to emit a specific pattern or wavelength of light to 12009 measure depth values, which causes the color image to be 12010 corrupted during depth measurement. 12011 </details> 12012 </entry> 12013 <entry name="availableRecommendedDepthStreamConfigurations" type="int32" 12014 visibility="ndk_public" optional="true" container="array" 12015 typedef="recommendedStreamConfiguration" hal_version="3.4"> 12016 <array> 12017 <size>n</size> 12018 <size>5</size> 12019 </array> 12020 <description>Recommended depth stream configurations for common client use cases. 12021 </description> 12022 <details>Optional subset of the android.depth.availableDepthStreamConfigurations that 12023 contains similar tuples listed as 12024 (i.e. width, height, format, output/input stream, usecase bit field). 12025 Camera devices will be able to suggest particular depth stream configurations which are 12026 power and performance efficient for specific use cases. For more information about 12027 retrieving the suggestions see 12028 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 12029 </details> 12030 <ndk_details> 12031 For data representation please refer to 12032 android.scaler.availableRecommendedStreamConfigurations 12033 </ndk_details> 12034 <hal_details> 12035 Recommended depth configurations are expected to be declared with SNAPSHOT and/or 12036 ZSL if supported by the device. 12037 For additional details on how to declare recommended stream configurations, check 12038 android.scaler.availableRecommendedStreamConfigurations. 12039 For additional requirements on depth streams please consider 12040 android.depth.availableDepthStreamConfigurations. 12041 </hal_details> 12042 </entry> 12043 <entry name="availableDynamicDepthStreamConfigurations" type="int32" visibility="ndk_public" 12044 enum="true" container="array" typedef="streamConfiguration" hal_version="3.4"> 12045 <array> 12046 <size>n</size> 12047 <size>4</size> 12048 </array> 12049 <enum> 12050 <value>OUTPUT</value> 12051 <value>INPUT</value> 12052 </enum> 12053 <description>The available dynamic depth dataspace stream 12054 configurations that this camera device supports 12055 (i.e. format, width, height, output/input stream). 12056 </description> 12057 <details> 12058 These are output stream configurations for use with 12059 dataSpace DYNAMIC_DEPTH. The configurations are 12060 listed as `(format, width, height, input?)` tuples. 12061 12062 Only devices that support depth output for at least 12063 the HAL_PIXEL_FORMAT_Y16 dense depth map along with 12064 HAL_PIXEL_FORMAT_BLOB with the same size or size with 12065 the same aspect ratio can have dynamic depth dataspace 12066 stream configuration. android.depth.depthIsExclusive also 12067 needs to be set to FALSE. 12068 </details> 12069 <hal_details> 12070 Do not set this property directly. 12071 It is populated by camera framework and must not be set 12072 at the HAL layer. 12073 </hal_details> 12074 <tag id="DEPTH" /> 12075 </entry> 12076 <entry name="availableDynamicDepthMinFrameDurations" type="int64" visibility="ndk_public" 12077 container="array" typedef="streamConfigurationDuration" hal_version="3.4"> 12078 <array> 12079 <size>4</size> 12080 <size>n</size> 12081 </array> 12082 <description>This lists the minimum frame duration for each 12083 format/size combination for dynamic depth output streams. 12084 </description> 12085 <units>(format, width, height, ns) x n</units> 12086 <details> 12087 This should correspond to the frame duration when only that 12088 stream is active, with all processing (typically in android.*.mode) 12089 set to either OFF or FAST. 12090 12091 When multiple streams are used in a request, the minimum frame 12092 duration will be max(individual stream min durations). 12093 12094 The minimum frame duration of a stream (of a particular format, size) 12095 is the same regardless of whether the stream is input or output. 12096 </details> 12097 <hal_details> 12098 Do not set this property directly. 12099 It is populated by camera framework and must not be set 12100 at the HAL layer. 12101 </hal_details> 12102 <tag id="DEPTH" /> 12103 </entry> 12104 <entry name="availableDynamicDepthStallDurations" type="int64" visibility="ndk_public" 12105 container="array" typedef="streamConfigurationDuration" hal_version="3.4"> 12106 <array> 12107 <size>4</size> 12108 <size>n</size> 12109 </array> 12110 <description>This lists the maximum stall duration for each 12111 output format/size combination for dynamic depth streams. 12112 </description> 12113 <units>(format, width, height, ns) x n</units> 12114 <details> 12115 A stall duration is how much extra time would get added 12116 to the normal minimum frame duration for a repeating request 12117 that has streams with non-zero stall. 12118 12119 All dynamic depth output streams may have a nonzero stall 12120 duration. 12121 </details> 12122 <hal_details> 12123 Do not set this property directly. 12124 It is populated by camera framework and must not be set 12125 at the HAL layer. 12126 </hal_details> 12127 <tag id="DEPTH" /> 12128 </entry> 12129 <entry name="availableDepthStreamConfigurationsMaximumResolution" type="int32" 12130 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 12131 hal_version="3.6"> 12132 <array> 12133 <size>n</size> 12134 <size>4</size> 12135 </array> 12136 <enum> 12137 <value>OUTPUT</value> 12138 <value>INPUT</value> 12139 </enum> 12140 <description>The available depth dataspace stream 12141 configurations that this camera device supports 12142 (i.e. format, width, height, output/input stream) when a CaptureRequest is submitted with 12143 android.sensor.pixelMode set to 12144 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12145 </description> 12146 <details> 12147 Analogous to android.depth.availableDepthStreamConfigurations, for configurations which 12148 are applicable when android.sensor.pixelMode is set to 12149 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12150 </details> 12151 <tag id="DEPTH" /> 12152 </entry> 12153 <entry name="availableDepthMinFrameDurationsMaximumResolution" type="int64" 12154 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 12155 hal_version="3.6"> 12156 <array> 12157 <size>4</size> 12158 <size>n</size> 12159 </array> 12160 <description>This lists the minimum frame duration for each 12161 format/size combination for depth output formats when a CaptureRequest is submitted with 12162 android.sensor.pixelMode set to 12163 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12164 </description> 12165 <units>(format, width, height, ns) x n</units> 12166 <details> 12167 Analogous to android.depth.availableDepthMinFrameDurations, for configurations which 12168 are applicable when android.sensor.pixelMode is set to 12169 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12170 12171 See android.sensor.frameDuration and 12172 android.scaler.availableStallDurationsMaximumResolution for more details about 12173 calculating the max frame rate. 12174 </details> 12175 <tag id="DEPTH" /> 12176 </entry> 12177 <entry name="availableDepthStallDurationsMaximumResolution" type="int64" 12178 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 12179 hal_version="3.6"> 12180 <array> 12181 <size>4</size> 12182 <size>n</size> 12183 </array> 12184 <description>This lists the maximum stall duration for each 12185 output format/size combination for depth streams for CaptureRequests where 12186 android.sensor.pixelMode is set to 12187 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12188 </description> 12189 <units>(format, width, height, ns) x n</units> 12190 <details> 12191 Analogous to android.depth.availableDepthStallDurations, for configurations which 12192 are applicable when android.sensor.pixelMode is set to 12193 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12194 </details> 12195 <tag id="DEPTH" /> 12196 </entry> 12197 <entry name="availableDynamicDepthStreamConfigurationsMaximumResolution" type="int32" 12198 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 12199 hal_version="3.6"> 12200 <array> 12201 <size>n</size> 12202 <size>4</size> 12203 </array> 12204 <enum> 12205 <value>OUTPUT</value> 12206 <value>INPUT</value> 12207 </enum> 12208 <description>The available dynamic depth dataspace stream 12209 configurations that this camera device supports (i.e. format, width, height, 12210 output/input stream) for CaptureRequests where android.sensor.pixelMode is set to 12211 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12212 </description> 12213 <details> 12214 Analogous to android.depth.availableDynamicDepthStreamConfigurations, for configurations 12215 which are applicable when android.sensor.pixelMode is set to 12216 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12217 </details> 12218 <hal_details> 12219 Do not set this property directly. 12220 It is populated by camera framework and must not be set 12221 at the HAL layer. 12222 </hal_details> 12223 <tag id="DEPTH" /> 12224 </entry> 12225 <entry name="availableDynamicDepthMinFrameDurationsMaximumResolution" type="int64" 12226 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 12227 hal_version="3.6"> 12228 <array> 12229 <size>4</size> 12230 <size>n</size> 12231 </array> 12232 <description>This lists the minimum frame duration for each 12233 format/size combination for dynamic depth output streams for CaptureRequests where 12234 android.sensor.pixelMode is set to 12235 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12236 </description> 12237 <units>(format, width, height, ns) x n</units> 12238 <details> 12239 Analogous to android.depth.availableDynamicDepthMinFrameDurations, for configurations 12240 which are applicable when android.sensor.pixelMode is set to 12241 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12242 </details> 12243 <hal_details> 12244 Do not set this property directly. 12245 It is populated by camera framework and must not be set 12246 at the HAL layer. 12247 </hal_details> 12248 <tag id="DEPTH" /> 12249 </entry> 12250 <entry name="availableDynamicDepthStallDurationsMaximumResolution" type="int64" 12251 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 12252 hal_version="3.6"> 12253 <array> 12254 <size>4</size> 12255 <size>n</size> 12256 </array> 12257 <description>This lists the maximum stall duration for each 12258 output format/size combination for dynamic depth streams for CaptureRequests where 12259 android.sensor.pixelMode is set to 12260 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12261 </description> 12262 <units>(format, width, height, ns) x n</units> 12263 <details> 12264 Analogous to android.depth.availableDynamicDepthStallDurations, for configurations 12265 which are applicable when android.sensor.pixelMode is set to 12266 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12267 </details> 12268 <hal_details> 12269 Do not set this property directly. 12270 It is populated by camera framework and must not be set 12271 at the HAL layer. 12272 </hal_details> 12273 <tag id="DEPTH" /> 12274 </entry> 12275 </static> 12276 </section> 12277 <section name="logicalMultiCamera"> 12278 <static> 12279 <entry name="physicalIds" type="byte" visibility="ndk_public" 12280 container="array" hwlevel="limited" hal_version="3.3"> 12281 <array> 12282 <size>n</size> 12283 </array> 12284 <description>String containing the ids of the underlying physical cameras. 12285 </description> 12286 <units>UTF-8 null-terminated string</units> 12287 <details> 12288 For a logical camera, this is concatenation of all underlying physical camera IDs. 12289 The null terminator for physical camera ID must be preserved so that the whole string 12290 can be tokenized using '\0' to generate list of physical camera IDs. 12291 12292 For example, if the physical camera IDs of the logical camera are "2" and "3", the 12293 value of this tag will be ['2', '\0', '3', '\0']. 12294 12295 The number of physical camera IDs must be no less than 2. 12296 </details> 12297 <tag id="LOGICALCAMERA" /> 12298 </entry> 12299 <entry name="sensorSyncType" type="byte" visibility="public" 12300 enum="true" hwlevel="limited" hal_version="3.3"> 12301 <enum> 12302 <value>APPROXIMATE 12303 <notes> 12304 A software mechanism is used to synchronize between the physical cameras. As a result, 12305 the timestamp of an image from a physical stream is only an approximation of the 12306 image sensor start-of-exposure time. 12307 </notes> 12308 </value> 12309 <value>CALIBRATED 12310 <notes> 12311 The camera device supports frame timestamp synchronization at the hardware level, 12312 and the timestamp of a physical stream image accurately reflects its 12313 start-of-exposure time. 12314 </notes> 12315 </value> 12316 </enum> 12317 <description>The accuracy of frame timestamp synchronization between physical cameras</description> 12318 <details> 12319 The accuracy of the frame timestamp synchronization determines the physical cameras' 12320 ability to start exposure at the same time. If the sensorSyncType is CALIBRATED, the 12321 physical camera sensors usually run in leader/follower mode where one sensor generates a 12322 timing signal for the other, so that their shutter time is synchronized. For APPROXIMATE 12323 sensorSyncType, the camera sensors usually run in leader/leader mode, where both sensors 12324 use their own timing generator, and there could be offset between their start of exposure. 12325 12326 In both cases, all images generated for a particular capture request still carry the same 12327 timestamps, so that they can be used to look up the matching frame number and 12328 onCaptureStarted callback. 12329 12330 This tag is only applicable if the logical camera device supports concurrent physical 12331 streams from different physical cameras. 12332 </details> 12333 <tag id="LOGICALCAMERA" /> 12334 </entry> 12335 </static> 12336 <dynamic> 12337 <entry name="activePhysicalId" type="byte" visibility="public" 12338 typedef="string" hal_version="3.4"> 12339 <description>String containing the ID of the underlying active physical camera. 12340 </description> 12341 <units>UTF-8 null-terminated string</units> 12342 <details> 12343 The ID of the active physical camera that's backing the logical camera. All camera 12344 streams and metadata that are not physical camera specific will be originating from this 12345 physical camera. 12346 12347 For a logical camera made up of physical cameras where each camera's lenses have 12348 different characteristics, the camera device may choose to switch between the physical 12349 cameras when application changes FOCAL_LENGTH or SCALER_CROP_REGION. 12350 At the time of lens switch, this result metadata reflects the new active physical camera 12351 ID. 12352 12353 This key will be available if the camera device advertises this key via {@link 12354 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 12355 When available, this must be one of valid physical IDs backing this logical multi-camera. 12356 If this key is not available for a logical multi-camera, the camera device implementation 12357 may still switch between different active physical cameras based on use case, but the 12358 current active physical camera information won't be available to the application. 12359 </details> 12360 <hal_details> 12361 Staring from HIDL ICameraDevice version 3.5, the tag must be available in the capture 12362 result metadata to indicate current active physical camera ID. 12363 </hal_details> 12364 <tag id="LOGICALCAMERA" /> 12365 </entry> 12366 </dynamic> 12367 </section> 12368 <section name="distortionCorrection"> 12369 <controls> 12370 <entry name="mode" type="byte" visibility="public" enum="true" hal_version="3.3"> 12371 <enum> 12372 <value>OFF 12373 <notes>No distortion correction is applied.</notes></value> 12374 <value>FAST <notes>Lens distortion correction is applied without reducing frame rate 12375 relative to sensor output. It may be the same as OFF if distortion correction would 12376 reduce frame rate relative to sensor.</notes></value> 12377 <value>HIGH_QUALITY <notes>High-quality distortion correction is applied, at the cost of 12378 possibly reduced frame rate relative to sensor output.</notes></value> 12379 </enum> 12380 <description>Mode of operation for the lens distortion correction block.</description> 12381 <range>android.distortionCorrection.availableModes</range> 12382 <details>The lens distortion correction block attempts to improve image quality by fixing 12383 radial, tangential, or other geometric aberrations in the camera device's optics. If 12384 available, the android.lens.distortion field documents the lens's distortion parameters. 12385 12386 OFF means no distortion correction is done. 12387 12388 FAST/HIGH_QUALITY both mean camera device determined distortion correction will be 12389 applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality 12390 correction algorithms, even if it slows down capture rate. FAST means the camera device 12391 will not slow down capture rate when applying correction. FAST may be the same as OFF if 12392 any correction at all would slow down capture rate. Every output stream will have a 12393 similar amount of enhancement applied. 12394 12395 The correction only applies to processed outputs such as YUV, Y8, JPEG, or DEPTH16; it is 12396 not applied to any RAW output. 12397 12398 This control will be on by default on devices that support this control. Applications 12399 disabling distortion correction need to pay extra attention with the coordinate system of 12400 metering regions, crop region, and face rectangles. When distortion correction is OFF, 12401 metadata coordinates follow the coordinate system of 12402 android.sensor.info.preCorrectionActiveArraySize. When distortion is not OFF, metadata 12403 coordinates follow the coordinate system of android.sensor.info.activeArraySize. The 12404 camera device will map these metadata fields to match the corrected image produced by the 12405 camera device, for both capture requests and results. However, this mapping is not very 12406 precise, since rectangles do not generally map to rectangles when corrected. Only linear 12407 scaling between the active array and precorrection active array coordinates is 12408 performed. Applications that require precise correction of metadata need to undo that 12409 linear scaling, and apply a more complete correction that takes into the account the app's 12410 own requirements. 12411 12412 The full list of metadata that is affected in this way by distortion correction is: 12413 12414 * android.control.afRegions 12415 * android.control.aeRegions 12416 * android.control.awbRegions 12417 * android.scaler.cropRegion 12418 * android.statistics.faces 12419 </details> 12420 </entry> 12421 </controls> 12422 <static> 12423 <entry name="availableModes" type="byte" visibility="public" 12424 type_notes="list of enums" container="array" typedef="enumList" hal_version="3.3"> 12425 <array> 12426 <size>n</size> 12427 </array> 12428 <description> 12429 List of distortion correction modes for android.distortionCorrection.mode that are 12430 supported by this camera device. 12431 </description> 12432 <range>Any value listed in android.distortionCorrection.mode</range> 12433 <details> 12434 No device is required to support this API; such devices will always list only 'OFF'. 12435 All devices that support this API will list both FAST and HIGH_QUALITY. 12436 </details> 12437 <hal_details> 12438 HAL must support both FAST and HIGH_QUALITY if distortion correction is available 12439 on the camera device, but the underlying implementation can be the same for both modes. 12440 That is, if the highest quality implementation on the camera device does not slow down 12441 capture rate, then FAST and HIGH_QUALITY will generate the same output. 12442 </hal_details> 12443 <tag id="V1" /> 12444 <tag id="REPROC" /> 12445 </entry> 12446 </static> 12447 <dynamic> 12448 <clone entry="android.distortionCorrection.mode" kind="controls" hal_version="3.3"> 12449 </clone> 12450 </dynamic> 12451 </section> 12452 <section name="heic"> 12453 <static> 12454 <namespace name="info"> 12455 <entry name="supported" type="byte" visibility="system" enum="true" 12456 typedef="boolean" hwlevel="limited" hal_version="3.4"> 12457 <enum> 12458 <value>FALSE</value> 12459 <value>TRUE</value> 12460 </enum> 12461 <description>Whether this camera device can support identical set of stream combinations 12462 involving HEIC image format, compared to the 12463 {@link android.hardware.camera2.CameraDevice#createCaptureSession table of combinations} 12464 involving JPEG image format required for the device's hardware level and capabilities. 12465 </description> 12466 <details> 12467 All the static, control and dynamic metadata tags related to JPEG apply to HEIC formats 12468 as well. For example, the same android.jpeg.orientation and android.jpeg.quality are 12469 used to control the orientation and quality of the HEIC image. Configuring JPEG and 12470 HEIC streams at the same time is not supported. 12471 12472 If a camera device supports HEIC format (ISO/IEC 23008-12), not only does it 12473 support the existing mandatory stream 12474 {@link android.hardware.camera2.CameraDevice#createCaptureSession combinations} 12475 required for the device's hardware level and capabilities, it also supports swapping 12476 each JPEG stream with HEIC stream in all guaranteed combinations. 12477 12478 For every HEIC stream configured by the application, the camera framework sets up 2 12479 internal streams with camera HAL: 12480 12481 * A YUV_420_888 or IMPLEMENTATION_DEFINED HAL stream as input to HEIC or HEVC encoder. 12482 * A BLOB stream with JPEG_APPS_SEGMENTS dataspace to extract application markers 12483 including EXIF and thumbnail to be saved in HEIF container. 12484 12485 A camera device can output HEIC format to the application if and only if: 12486 12487 * The system contains a HEIC or HEVC encoder with constant quality mode, and 12488 * This tag is set to TRUE, meaning that camera HAL supports replacing JPEG streams in 12489 all mandatory stream combinations with a [YUV_420_888/IMPLEMENTATION_DEFINED stream + 12490 JPEG_APPS_SEGMENT BLOB stream] combo. 12491 12492 As an example, if the camera device's hardware level is LIMITED, and it supports HEIC, 12493 in addition to the required stream combinations, HAL must support below stream 12494 combinations as well: 12495 12496 * IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 12497 * PRIV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 12498 * YUV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 12499 * PRIV PREVIEW + YUV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + 12500 JPEG_SEGMENTS_BLOB 12501 12502 The selection logic between YUV_420_888 and IMPLEMENTATION_DEFINED for HAL internal 12503 stream is as follows: 12504 12505 if (HEIC encoder exists and supports the size) { 12506 use IMPLEMENTATION_DEFINED with GRALLOC_USAGE_HW_IMAGE_ENCODER usage flag; 12507 } else { 12508 // HVC encoder exists 12509 if (size is less than framework predefined tile size) { 12510 use IMPLEMENTATINO_DEFINED with GRALLOC_USAGE_HW_VIDEO_ENCODER usage flag; 12511 } else { 12512 use YUV_420_888; 12513 } 12514 } 12515 </details> 12516 <tag id="HEIC" /> 12517 </entry> 12518 <entry name="maxJpegAppSegmentsCount" type="byte" visibility="system" 12519 hwlevel="limited" hal_version="3.4"> 12520 <description>The maximum number of Jpeg APP segments supported by the camera HAL device. 12521 </description> 12522 <details> 12523 The camera framework will use this value to derive the size of the BLOB buffer with 12524 JPEG_APP_SEGMENTS dataspace, with each APP segment occupying at most 64K bytes. If the 12525 value of this tag is n, the size of the framework allocated buffer will be: 12526 12527 n * (2 + 0xFFFF) + sizeof(struct CameraBlob) 12528 12529 where 2 is number of bytes for APP marker, 0xFFFF is the maximum size per APP segment 12530 (including segment size). 12531 12532 The value of this tag must be at least 1, and APP1 marker (0xFFE1) segment must be the 12533 first segment stored in the JPEG_APPS_SEGMENTS BLOB buffer. APP1 segment stores EXIF and 12534 thumbnail. 12535 12536 Since media encoder embeds the orientation in the metadata of the output image, to be 12537 consistent between main image and thumbnail, camera HAL must not rotate the thumbnail 12538 image data based on android.jpeg.orientation. The framework will write the orientation 12539 into EXIF and HEIC container. 12540 12541 APP1 segment is followed immediately by one or multiple APP2 segments, and APPn 12542 segments. After the HAL fills and returns the JPEG_APP_SEGMENTS buffer, the camera 12543 framework modifies the APP1 segment by filling in the EXIF tags that are related to 12544 main image bitstream and the tags that can be derived from capture result metadata, 12545 before saving them into the HEIC container. 12546 12547 The value of this tag must not be more than 16. 12548 </details> 12549 <tag id="HEIC" /> 12550 </entry> 12551 </namespace> 12552 12553 <entry name="availableHeicStreamConfigurations" type="int32" visibility="ndk_public" 12554 enum="true" container="array" typedef="streamConfiguration" 12555 hwlevel="limited" hal_version="3.4"> 12556 <array> 12557 <size>n</size> 12558 <size>4</size> 12559 </array> 12560 <enum> 12561 <value>OUTPUT</value> 12562 <value>INPUT</value> 12563 </enum> 12564 <description>The available HEIC (ISO/IEC 23008-12) stream 12565 configurations that this camera device supports 12566 (i.e. format, width, height, output/input stream). 12567 </description> 12568 <details> 12569 The configurations are listed as `(format, width, height, input?)` tuples. 12570 12571 If the camera device supports HEIC image format, it will support identical set of stream 12572 combinations involving HEIC image format, compared to the combinations involving JPEG 12573 image format as required by the device's hardware level and capabilities. 12574 12575 All the static, control, and dynamic metadata tags related to JPEG apply to HEIC formats. 12576 Configuring JPEG and HEIC streams at the same time is not supported. 12577 </details> 12578 <ndk_details> 12579 All the configuration tuples `(format, width, height, input?)` will contain 12580 AIMAGE_FORMAT_HEIC format as OUTPUT only. 12581 </ndk_details> 12582 <hal_details> 12583 These are output stream configurations for use with dataSpace HAL_DATASPACE_HEIF. 12584 12585 Do not set this property directly. It is populated by camera framework and must not be 12586 set by the HAL layer. 12587 </hal_details> 12588 <tag id="HEIC" /> 12589 </entry> 12590 <entry name="availableHeicMinFrameDurations" type="int64" visibility="ndk_public" 12591 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 12592 hal_version="3.4"> 12593 <array> 12594 <size>4</size> 12595 <size>n</size> 12596 </array> 12597 <description>This lists the minimum frame duration for each 12598 format/size combination for HEIC output formats. 12599 </description> 12600 <units>(format, width, height, ns) x n</units> 12601 <details> 12602 This should correspond to the frame duration when only that 12603 stream is active, with all processing (typically in android.*.mode) 12604 set to either OFF or FAST. 12605 12606 When multiple streams are used in a request, the minimum frame 12607 duration will be max(individual stream min durations). 12608 12609 See android.sensor.frameDuration and 12610 android.scaler.availableStallDurations for more details about 12611 calculating the max frame rate. 12612 </details> 12613 <hal_details> 12614 Do not set this property directly. It is populated by camera framework and must not be 12615 set by the HAL layer. 12616 </hal_details> 12617 <tag id="HEIC" /> 12618 </entry> 12619 <entry name="availableHeicStallDurations" type="int64" visibility="ndk_public" 12620 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 12621 hal_version="3.4"> 12622 <array> 12623 <size>4</size> 12624 <size>n</size> 12625 </array> 12626 <description>This lists the maximum stall duration for each 12627 output format/size combination for HEIC streams. 12628 </description> 12629 <units>(format, width, height, ns) x n</units> 12630 <details> 12631 A stall duration is how much extra time would get added 12632 to the normal minimum frame duration for a repeating request 12633 that has streams with non-zero stall. 12634 12635 This functions similarly to 12636 android.scaler.availableStallDurations for HEIC 12637 streams. 12638 12639 All HEIC output stream formats may have a nonzero stall 12640 duration. 12641 </details> 12642 <hal_details> 12643 Do not set this property directly. It is populated by camera framework and must not be 12644 set by the HAL layer. 12645 </hal_details> 12646 <tag id="HEIC" /> 12647 </entry> 12648 <entry name="availableHeicStreamConfigurationsMaximumResolution" type="int32" 12649 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 12650 hal_version="3.6"> 12651 <array> 12652 <size>n</size> 12653 <size>4</size> 12654 </array> 12655 <enum> 12656 <value>OUTPUT</value> 12657 <value>INPUT</value> 12658 </enum> 12659 <description>The available HEIC (ISO/IEC 23008-12) stream 12660 configurations that this camera device supports 12661 (i.e. format, width, height, output/input stream). 12662 </description> 12663 <details> 12664 Refer to android.heic.availableHeicStreamConfigurations for details. 12665 </details> 12666 <ndk_details> 12667 All the configuration tuples `(format, width, height, input?)` will contain 12668 AIMAGE_FORMAT_HEIC format as OUTPUT only. 12669 </ndk_details> 12670 <hal_details> 12671 These are output stream configurations for use with dataSpace HAL_DATASPACE_HEIF. 12672 12673 Do not set this property directly. It is populated by camera framework and must not be 12674 set by the HAL layer. 12675 </hal_details> 12676 <tag id="HEIC" /> 12677 </entry> 12678 <entry name="availableHeicMinFrameDurationsMaximumResolution" type="int64" 12679 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 12680 hal_version="3.6"> 12681 <array> 12682 <size>4</size> 12683 <size>n</size> 12684 </array> 12685 <description>This lists the minimum frame duration for each 12686 format/size combination for HEIC output formats for CaptureRequests where 12687 android.sensor.pixelMode is set to 12688 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12689 </description> 12690 <units>(format, width, height, ns) x n</units> 12691 <details> 12692 Refer to android.heic.availableHeicMinFrameDurations for details. 12693 </details> 12694 <hal_details> 12695 Do not set this property directly. It is populated by camera framework and must not be 12696 set by the HAL layer. 12697 </hal_details> 12698 <tag id="HEIC" /> 12699 </entry> 12700 <entry name="availableHeicStallDurationsMaximumResolution" type="int64" 12701 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 12702 hal_version="3.6"> 12703 <array> 12704 <size>4</size> 12705 <size>n</size> 12706 </array> 12707 <description>This lists the maximum stall duration for each 12708 output format/size combination for HEIC streams for CaptureRequests where 12709 android.sensor.pixelMode is set to 12710 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12711 </description> 12712 <units>(format, width, height, ns) x n</units> 12713 <details> 12714 Refer to android.heic.availableHeicStallDurations for details. 12715 </details> 12716 <hal_details> 12717 Do not set this property directly. It is populated by camera framework and must not be 12718 set by the HAL layer. 12719 </hal_details> 12720 <tag id="HEIC" /> 12721 </entry> 12722 </static> 12723 </section> 12724 </namespace> 12725</metadata> 12726
